docs: add xml comments for tenant modules

src/Domain/TakeoutSaaS.Domain/Tenants/Repositories/ITenantAnnouncementReadRepository.cs

@@ -10,13 +10,45 @@ namespace TakeoutSaaS.Domain.Tenants.Repositories;
 /// </summary>
 public interface ITenantAnnouncementReadRepository
 {
+    /// <summary>
+    /// 按公告查询已读记录。
+    /// </summary>
+    /// <param name="tenantId">租户 ID。</param>
+    /// <param name="announcementId">公告 ID。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>指定公告的已读列表。</returns>
     Task<IReadOnlyList<TenantAnnouncementRead>> GetByAnnouncementAsync(long tenantId, long announcementId, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 批量按公告查询已读记录，可选按用户过滤。
+    /// </summary>
+    /// <param name="tenantId">租户 ID。</param>
+    /// <param name="announcementIds">公告 ID 集合。</param>
+    /// <param name="userId">用户 ID，空则不按用户筛选。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>匹配条件的已读列表。</returns>
     Task<IReadOnlyList<TenantAnnouncementRead>> GetByAnnouncementAsync(long tenantId, IEnumerable<long> announcementIds, long? userId, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 查询指定用户对某公告的已读记录。
+    /// </summary>
+    /// <param name="tenantId">租户 ID。</param>
+    /// <param name="announcementId">公告 ID。</param>
+    /// <param name="userId">用户 ID。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>已读记录，未读返回 null。</returns>
     Task<TenantAnnouncementRead?> FindAsync(long tenantId, long announcementId, long? userId, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 新增已读记录。
+    /// </summary>
+    /// <param name="record">已读实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task AddAsync(TenantAnnouncementRead record, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 保存变更。
+    /// </summary>
+    /// <param name="cancellationToken">取消标记。</param>
     Task SaveChangesAsync(CancellationToken cancellationToken = default);
 }

src/Domain/TakeoutSaaS.Domain/Tenants/Repositories/ITenantAnnouncementRepository.cs

@@ -11,6 +11,15 @@ namespace TakeoutSaaS.Domain.Tenants.Repositories;
 /// </summary>
 public interface ITenantAnnouncementRepository
 {
+    /// <summary>
+    /// 查询公告列表，按类型、启用状态与生效时间筛选。
+    /// </summary>
+    /// <param name="tenantId">租户 ID。</param>
+    /// <param name="type">公告类型。</param>
+    /// <param name="isActive">启用状态。</param>
+    /// <param name="effectiveAt">生效时间点，为空不限制。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>公告集合。</returns>
     Task<IReadOnlyList<TenantAnnouncement>> SearchAsync(
         long tenantId,
         TenantAnnouncementType? type,
@@ -18,13 +27,40 @@ public interface ITenantAnnouncementRepository
         DateTime? effectiveAt,
         CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 按 ID 获取公告。
+    /// </summary>
+    /// <param name="tenantId">租户 ID。</param>
+    /// <param name="announcementId">公告 ID。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>公告实体或 null。</returns>
     Task<TenantAnnouncement?> FindByIdAsync(long tenantId, long announcementId, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 新增公告。
+    /// </summary>
+    /// <param name="announcement">公告实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task AddAsync(TenantAnnouncement announcement, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 更新公告。
+    /// </summary>
+    /// <param name="announcement">公告实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task UpdateAsync(TenantAnnouncement announcement, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 删除公告。
+    /// </summary>
+    /// <param name="tenantId">租户 ID。</param>
+    /// <param name="announcementId">公告 ID。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task DeleteAsync(long tenantId, long announcementId, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 保存变更。
+    /// </summary>
+    /// <param name="cancellationToken">取消标记。</param>
     Task SaveChangesAsync(CancellationToken cancellationToken = default);
 }

src/Domain/TakeoutSaaS.Domain/Tenants/Repositories/ITenantBillingRepository.cs

@@ -11,6 +11,15 @@ namespace TakeoutSaaS.Domain.Tenants.Repositories;
 /// </summary>
 public interface ITenantBillingRepository
 {
+    /// <summary>
+    /// 查询账单列表，按状态与时间范围筛选。
+    /// </summary>
+    /// <param name="tenantId">租户 ID。</param>
+    /// <param name="status">账单状态。</param>
+    /// <param name="from">开始时间（UTC）。</param>
+    /// <param name="to">结束时间（UTC）。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>账单集合。</returns>
     Task<IReadOnlyList<TenantBillingStatement>> SearchAsync(
         long tenantId,
         TenantBillingStatus? status,
@@ -18,13 +27,41 @@ public interface ITenantBillingRepository
         DateTime? to,
         CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 按 ID 获取账单。
+    /// </summary>
+    /// <param name="tenantId">租户 ID。</param>
+    /// <param name="billingId">账单 ID。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>账单实体或 null。</returns>
     Task<TenantBillingStatement?> FindByIdAsync(long tenantId, long billingId, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 按账单编号获取账单。
+    /// </summary>
+    /// <param name="tenantId">租户 ID。</param>
+    /// <param name="statementNo">账单编号。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>账单实体或 null。</returns>
     Task<TenantBillingStatement?> FindByStatementNoAsync(long tenantId, string statementNo, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 新增账单。
+    /// </summary>
+    /// <param name="bill">账单实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task AddAsync(TenantBillingStatement bill, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 更新账单。
+    /// </summary>
+    /// <param name="bill">账单实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task UpdateAsync(TenantBillingStatement bill, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 保存变更。
+    /// </summary>
+    /// <param name="cancellationToken">取消标记。</param>
     Task SaveChangesAsync(CancellationToken cancellationToken = default);
 }

src/Domain/TakeoutSaaS.Domain/Tenants/Repositories/ITenantNotificationRepository.cs

@@ -11,6 +11,16 @@ namespace TakeoutSaaS.Domain.Tenants.Repositories;
 /// </summary>
 public interface ITenantNotificationRepository
 {
+    /// <summary>
+    /// 查询通知列表，按等级、未读状态与时间范围筛选。
+    /// </summary>
+    /// <param name="tenantId">租户 ID。</param>
+    /// <param name="severity">通知等级。</param>
+    /// <param name="unreadOnly">仅返回未读。</param>
+    /// <param name="from">开始时间（UTC）。</param>
+    /// <param name="to">结束时间（UTC）。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>通知集合。</returns>
     Task<IReadOnlyList<TenantNotification>> SearchAsync(
         long tenantId,
         TenantNotificationSeverity? severity,
@@ -19,11 +29,32 @@ public interface ITenantNotificationRepository
         DateTime? to,
         CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 按 ID 获取通知。
+    /// </summary>
+    /// <param name="tenantId">租户 ID。</param>
+    /// <param name="notificationId">通知 ID。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>通知实体或 null。</returns>
     Task<TenantNotification?> FindByIdAsync(long tenantId, long notificationId, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 新增通知。
+    /// </summary>
+    /// <param name="notification">通知实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task AddAsync(TenantNotification notification, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 更新通知。
+    /// </summary>
+    /// <param name="notification">通知实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task UpdateAsync(TenantNotification notification, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// 保存变更。
+    /// </summary>
+    /// <param name="cancellationToken">取消标记。</param>
     Task SaveChangesAsync(CancellationToken cancellationToken = default);
 }