docs: refine tenant repository comments

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

@@ -11,32 +11,46 @@ namespace TakeoutSaaS.Domain.Tenants.Repositories;
 public interface ITenantPackageRepository
 {
     /// <summary>
-    /// 按 ID 查询套餐。
+    /// 按套餐 ID 查询套餐。
     /// </summary>
+    /// <param name="id">套餐 ID（雪花算法）。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>匹配的套餐实体，未找到返回 null。</returns>
     Task<TenantPackage?> FindByIdAsync(long id, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 按关键词与启用状态搜索套餐。
     /// </summary>
+    /// <param name="keyword">名称或描述关键字，空则不按关键字过滤。</param>
+    /// <param name="isActive">启用状态，空则不按状态过滤。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>符合条件的套餐列表。</returns>
     Task<IReadOnlyList<TenantPackage>> SearchAsync(string? keyword, bool? isActive, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 新增套餐。
     /// </summary>
+    /// <param name="package">套餐实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task AddAsync(TenantPackage package, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 更新套餐。
     /// </summary>
+    /// <param name="package">套餐实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task UpdateAsync(TenantPackage package, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 删除套餐。
     /// </summary>
+    /// <param name="id">套餐 ID（雪花算法）。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task DeleteAsync(long id, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 持久化。
     /// </summary>
+    /// <param name="cancellationToken">取消标记。</param>
     Task SaveChangesAsync(CancellationToken cancellationToken = default);
 }

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

@@ -14,25 +14,37 @@ public interface ITenantQuotaUsageRepository
     /// <summary>
     /// 获取租户指定配额的使用情况。
     /// </summary>
+    /// <param name="tenantId">租户 ID（雪花算法）。</param>
+    /// <param name="quotaType">配额类型。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>配额使用记录，未初始化则返回 null。</returns>
     Task<TenantQuotaUsage?> FindAsync(long tenantId, TenantQuotaType quotaType, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 按租户批量获取配额使用记录。
     /// </summary>
+    /// <param name="tenantId">租户 ID（雪花算法）。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>该租户的所有配额使用记录。</returns>
     Task<IReadOnlyList<TenantQuotaUsage>> GetByTenantAsync(long tenantId, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 新增配额使用记录。
     /// </summary>
+    /// <param name="usage">配额使用实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task AddAsync(TenantQuotaUsage usage, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 更新配额使用记录。
     /// </summary>
+    /// <param name="usage">配额使用实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task UpdateAsync(TenantQuotaUsage usage, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 持久化。
     /// </summary>
+    /// <param name="cancellationToken">取消标记。</param>
     Task SaveChangesAsync(CancellationToken cancellationToken = default);
 }

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

@@ -13,11 +13,18 @@ public interface ITenantRepository
     /// <summary>
     /// 依据 ID 获取租户。
     /// </summary>
+    /// <param name="tenantId">租户 ID（雪花算法）。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>租户实体，未找到返回 null。</returns>
     Task<Tenant?> FindByIdAsync(long tenantId, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 按状态与关键词查询租户列表。
     /// </summary>
+    /// <param name="status">租户状态，为空不按状态过滤。</param>
+    /// <param name="keyword">名称或编码关键字，为空不按关键字过滤。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>符合条件的租户列表。</returns>
     Task<IReadOnlyList<Tenant>> SearchAsync(
         TenantStatus? status,
         string? keyword,
@@ -26,70 +33,104 @@ public interface ITenantRepository
     /// <summary>
     /// 新增租户。
     /// </summary>
+    /// <param name="tenant">租户实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task AddTenantAsync(Tenant tenant, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 更新租户。
     /// </summary>
+    /// <param name="tenant">租户实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task UpdateTenantAsync(Tenant tenant, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 判断编码是否存在。
     /// </summary>
+    /// <param name="code">租户编码。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>存在返回 true，否则 false。</returns>
     Task<bool> ExistsByCodeAsync(string code, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 获取实名资料。
     /// </summary>
+    /// <param name="tenantId">租户 ID（雪花算法）。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>实名资料实体，未提交返回 null。</returns>
     Task<TenantVerificationProfile?> GetVerificationProfileAsync(long tenantId, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 新增或更新实名资料。
     /// </summary>
+    /// <param name="profile">实名资料实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task UpsertVerificationProfileAsync(TenantVerificationProfile profile, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 获取当前订阅。
     /// </summary>
+    /// <param name="tenantId">租户 ID（雪花算法）。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>当前有效订阅，若无则 null。</returns>
     Task<TenantSubscription?> GetActiveSubscriptionAsync(long tenantId, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 依据订阅 ID 查询。
     /// </summary>
+    /// <param name="tenantId">租户 ID（雪花算法）。</param>
+    /// <param name="subscriptionId">订阅 ID（雪花算法）。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>订阅实体，未找到返回 null。</returns>
     Task<TenantSubscription?> FindSubscriptionByIdAsync(long tenantId, long subscriptionId, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 新增订阅。
     /// </summary>
+    /// <param name="subscription">订阅实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task AddSubscriptionAsync(TenantSubscription subscription, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 更新订阅。
     /// </summary>
+    /// <param name="subscription">订阅实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task UpdateSubscriptionAsync(TenantSubscription subscription, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 记录订阅历史。
     /// </summary>
+    /// <param name="history">订阅历史实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task AddSubscriptionHistoryAsync(TenantSubscriptionHistory history, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 获取订阅历史。
     /// </summary>
+    /// <param name="tenantId">租户 ID（雪花算法）。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>订阅历史列表。</returns>
     Task<IReadOnlyList<TenantSubscriptionHistory>> GetSubscriptionHistoryAsync(long tenantId, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 新增审核日志。
     /// </summary>
+    /// <param name="log">审核日志实体。</param>
+    /// <param name="cancellationToken">取消标记。</param>
     Task AddAuditLogAsync(TenantAuditLog log, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 查询审核日志。
     /// </summary>
+    /// <param name="tenantId">租户 ID（雪花算法）。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>审核日志列表。</returns>
     Task<IReadOnlyList<TenantAuditLog>> GetAuditLogsAsync(long tenantId, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// 持久化。
     /// </summary>
+    /// <param name="cancellationToken">取消标记。</param>
     Task SaveChangesAsync(CancellationToken cancellationToken = default);
 }