docs: 提交当前注释更新

MISSING_XML_DOCS.md

@@ -1,26 +0,0 @@
-# 缺失 XML 文档注释清单（自动扫描）
-
-- 统计时间：执行脚本时基于仓库当前状态。
-- 范围：`src` 下 898 个 `.cs` 文件。
-- 发现未紧邻 `///` 文档注释的文件：93 个。
-- 分层分布：Application 64，Infrastructure 19，Core 6，Modules 4。
-
-## 详细清单（路径:行号）
-- src/Application/TakeoutSaaS.Application/App/Merchants/Dto/MerchantAuditLogDto.cs:13
-- src/Application/TakeoutSaaS.Application/App/Merchants/Dto/MerchantContractDto.cs:13
-- src/Application/TakeoutSaaS.Application/App/Merchants/Dto/MerchantDocumentDto.cs:13
-- src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/AddMerchantDocumentCommandHandler.cs:25
-- src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/CreateMerchantCategoryCommandHandler.cs:20
-- src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/CreateMerchantContractCommandHandler.cs:25
-- src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/DeleteMerchantCategoryCommandHandler.cs:16
-- src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/GetMerchantAuditLogsQueryHandler.cs:18
-- src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/GetMerchantCategoriesQueryHandler.cs:16
-- src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/GetMerchantContractsQueryHandler.cs:19
-- src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/GetMerchantDetailQueryHandler.cs:19
-- src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/GetMerchantDocumentsQueryHandler.cs:19
-- src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/ListMerchantCategoriesQueryHandler.cs:17
-- src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/ReorderMerchantCategoriesCommandHandler.cs:18
-- src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/ReviewMerchantCommandHandler.cs:23
-- src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/ReviewMerchantDocumentCommandHandler.cs:23
-- src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/UpdateMerchantContractStatusCommandHandler.cs:23
-- src/Application/TakeoutSaaS.Application/App/Merchants/MerchantMapping.cs:11

src/Application/TakeoutSaaS.Application/App/Merchants/Dto/MerchantAuditLogDto.cs

@@ -9,19 +9,40 @@ namespace TakeoutSaaS.Application.App.Merchants.Dto;
 /// </summary>
 public sealed class MerchantAuditLogDto
 {
+    /// <summary>
+    /// 日志 ID。
+    /// </summary>
     [JsonConverter(typeof(SnowflakeIdJsonConverter))]
     public long Id { get; init; }
 
+    /// <summary>
+    /// 商户 ID。
+    /// </summary>
     [JsonConverter(typeof(SnowflakeIdJsonConverter))]
     public long MerchantId { get; init; }
 
+    /// <summary>
+    /// 操作类型。
+    /// </summary>
     public MerchantAuditAction Action { get; init; }
 
+    /// <summary>
+    /// 标题。
+    /// </summary>
     public string Title { get; init; } = string.Empty;
 
+    /// <summary>
+    /// 描述。
+    /// </summary>
     public string? Description { get; init; }
 
+    /// <summary>
+    /// 操作人。
+    /// </summary>
     public string? OperatorName { get; init; }
 
+    /// <summary>
+    /// 创建时间。
+    /// </summary>
     public DateTime CreatedAt { get; init; }
 }

src/Application/TakeoutSaaS.Application/App/Merchants/Dto/MerchantContractDto.cs

@@ -9,25 +9,55 @@ namespace TakeoutSaaS.Application.App.Merchants.Dto;
 /// </summary>
 public sealed class MerchantContractDto
 {
+    /// <summary>
+    /// 合同 ID。
+    /// </summary>
     [JsonConverter(typeof(SnowflakeIdJsonConverter))]
     public long Id { get; init; }
 
+    /// <summary>
+    /// 商户 ID。
+    /// </summary>
     [JsonConverter(typeof(SnowflakeIdJsonConverter))]
     public long MerchantId { get; init; }
 
+    /// <summary>
+    /// 合同编号。
+    /// </summary>
     public string ContractNumber { get; init; } = string.Empty;
 
+    /// <summary>
+    /// 合同状态。
+    /// </summary>
     public ContractStatus Status { get; init; }
 
+    /// <summary>
+    /// 合同开始日期。
+    /// </summary>
     public DateTime StartDate { get; init; }
 
+    /// <summary>
+    /// 合同结束日期。
+    /// </summary>
     public DateTime EndDate { get; init; }
 
+    /// <summary>
+    /// 合同文件地址。
+    /// </summary>
     public string FileUrl { get; init; } = string.Empty;
 
+    /// <summary>
+    /// 签署时间。
+    /// </summary>
     public DateTime? SignedAt { get; init; }
 
+    /// <summary>
+    /// 解约时间。
+    /// </summary>
     public DateTime? TerminatedAt { get; init; }
 
+    /// <summary>
+    /// 解约原因。
+    /// </summary>
     public string? TerminationReason { get; init; }
 }

src/Application/TakeoutSaaS.Application/App/Merchants/Dto/MerchantDocumentDto.cs

@@ -9,25 +9,55 @@ namespace TakeoutSaaS.Application.App.Merchants.Dto;
 /// </summary>
 public sealed class MerchantDocumentDto
 {
+    /// <summary>
+    /// 证照 ID。
+    /// </summary>
     [JsonConverter(typeof(SnowflakeIdJsonConverter))]
     public long Id { get; init; }
 
+    /// <summary>
+    /// 商户 ID。
+    /// </summary>
     [JsonConverter(typeof(SnowflakeIdJsonConverter))]
     public long MerchantId { get; init; }
 
+    /// <summary>
+    /// 证照类型。
+    /// </summary>
     public MerchantDocumentType DocumentType { get; init; }
 
+    /// <summary>
+    /// 审核状态。
+    /// </summary>
     public MerchantDocumentStatus Status { get; init; }
 
+    /// <summary>
+    /// 文件地址。
+    /// </summary>
     public string FileUrl { get; init; } = string.Empty;
 
+    /// <summary>
+    /// 证照编号。
+    /// </summary>
     public string? DocumentNumber { get; init; }
 
+    /// <summary>
+    /// 签发时间。
+    /// </summary>
     public DateTime? IssuedAt { get; init; }
 
+    /// <summary>
+    /// 过期时间。
+    /// </summary>
     public DateTime? ExpiresAt { get; init; }
 
+    /// <summary>
+    /// 备注。
+    /// </summary>
     public string? Remarks { get; init; }
 
+    /// <summary>
+    /// 创建时间。
+    /// </summary>
     public DateTime CreatedAt { get; init; }
 }

src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/AddMerchantDocumentCommandHandler.cs

@@ -22,6 +22,12 @@ public sealed class AddMerchantDocumentCommandHandler(
     ICurrentUserAccessor currentUserAccessor)
     : IRequestHandler<AddMerchantDocumentCommand, MerchantDocumentDto>
 {
+    /// <summary>
+    /// 处理上传商户证照请求。
+    /// </summary>
+    /// <param name="request">上传命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>证照 DTO。</returns>
     public async Task<MerchantDocumentDto> Handle(AddMerchantDocumentCommand request, CancellationToken cancellationToken)
     {
         // 1. 获取租户并查询商户

src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/CreateMerchantCategoryCommandHandler.cs

@@ -17,6 +17,12 @@ public sealed class CreateMerchantCategoryCommandHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<CreateMerchantCategoryCommand, MerchantCategoryDto>
 {
+    /// <summary>
+    /// 处理创建商户类目请求。
+    /// </summary>
+    /// <param name="request">创建命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>类目 DTO。</returns>
     public async Task<MerchantCategoryDto> Handle(CreateMerchantCategoryCommand request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文

src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/CreateMerchantContractCommandHandler.cs

@@ -22,6 +22,12 @@ public sealed class CreateMerchantContractCommandHandler(
     ICurrentUserAccessor currentUserAccessor)
     : IRequestHandler<CreateMerchantContractCommand, MerchantContractDto>
 {
+    /// <summary>
+    /// 处理创建商户合同请求。
+    /// </summary>
+    /// <param name="request">创建命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>合同 DTO。</returns>
     public async Task<MerchantContractDto> Handle(CreateMerchantContractCommand request, CancellationToken cancellationToken)
     {
         // 1. 校验时间

src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/DeleteMerchantCategoryCommandHandler.cs

@@ -13,6 +13,12 @@ public sealed class DeleteMerchantCategoryCommandHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<DeleteMerchantCategoryCommand, bool>
 {
+    /// <summary>
+    /// 处理删除类目请求。
+    /// </summary>
+    /// <param name="request">删除命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>执行结果。</returns>
     public async Task<bool> Handle(DeleteMerchantCategoryCommand request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文

src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/GetMerchantAuditLogsQueryHandler.cs

@@ -15,6 +15,12 @@ public sealed class GetMerchantAuditLogsQueryHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<GetMerchantAuditLogsQuery, PagedResult<MerchantAuditLogDto>>
 {
+    /// <summary>
+    /// 查询商户审核日志列表。
+    /// </summary>
+    /// <param name="request">查询请求。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>分页结果。</returns>
     public async Task<PagedResult<MerchantAuditLogDto>> Handle(GetMerchantAuditLogsQuery request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文并查询日志

src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/GetMerchantCategoriesQueryHandler.cs

@@ -13,6 +13,12 @@ public sealed class GetMerchantCategoriesQueryHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<GetMerchantCategoriesQuery, IReadOnlyList<string>>
 {
+    /// <summary>
+    /// 查询启用的商户类目名称列表。
+    /// </summary>
+    /// <param name="request">查询请求。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>类目名称集合。</returns>
     public async Task<IReadOnlyList<string>> Handle(GetMerchantCategoriesQuery request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文并读取类目

src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/GetMerchantContractsQueryHandler.cs

@@ -16,6 +16,12 @@ public sealed class GetMerchantContractsQueryHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<GetMerchantContractsQuery, IReadOnlyList<MerchantContractDto>>
 {
+    /// <summary>
+    /// 查询商户合同列表。
+    /// </summary>
+    /// <param name="request">查询请求。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>合同 DTO 列表。</returns>
     public async Task<IReadOnlyList<MerchantContractDto>> Handle(GetMerchantContractsQuery request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文并校验商户存在

src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/GetMerchantDetailQueryHandler.cs

@@ -16,6 +16,12 @@ public sealed class GetMerchantDetailQueryHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<GetMerchantDetailQuery, MerchantDetailDto>
 {
+    /// <summary>
+    /// 查询商户详情，包括证照和合同。
+    /// </summary>
+    /// <param name="request">查询请求。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>商户详情 DTO。</returns>
     public async Task<MerchantDetailDto> Handle(GetMerchantDetailQuery request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文并查询商户

src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/GetMerchantDocumentsQueryHandler.cs

@@ -16,6 +16,12 @@ public sealed class GetMerchantDocumentsQueryHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<GetMerchantDocumentsQuery, IReadOnlyList<MerchantDocumentDto>>
 {
+    /// <summary>
+    /// 查询商户证照列表。
+    /// </summary>
+    /// <param name="request">查询请求。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>证照 DTO 列表。</returns>
     public async Task<IReadOnlyList<MerchantDocumentDto>> Handle(GetMerchantDocumentsQuery request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文并校验商户存在

src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/ListMerchantCategoriesQueryHandler.cs

@@ -14,6 +14,12 @@ public sealed class ListMerchantCategoriesQueryHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<ListMerchantCategoriesQuery, IReadOnlyList<MerchantCategoryDto>>
 {
+    /// <summary>
+    /// 列出所有类目。
+    /// </summary>
+    /// <param name="request">查询请求。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>类目 DTO 列表。</returns>
     public async Task<IReadOnlyList<MerchantCategoryDto>> Handle(ListMerchantCategoriesQuery request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文

src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/ReorderMerchantCategoriesCommandHandler.cs

@@ -15,6 +15,12 @@ public sealed class ReorderMerchantCategoriesCommandHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<ReorderMerchantCategoriesCommand, bool>
 {
+    /// <summary>
+    /// 调整类目排序。
+    /// </summary>
+    /// <param name="request">排序命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>执行结果。</returns>
     public async Task<bool> Handle(ReorderMerchantCategoriesCommand request, CancellationToken cancellationToken)
     {
         // 1. 获取租户并查询类目

src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/ReviewMerchantCommandHandler.cs

@@ -20,6 +20,12 @@ public sealed class ReviewMerchantCommandHandler(
     ICurrentUserAccessor currentUserAccessor)
     : IRequestHandler<ReviewMerchantCommand, MerchantDto>
 {
+    /// <summary>
+    /// 审核商户。
+    /// </summary>
+    /// <param name="request">审核命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>商户 DTO。</returns>
     public async Task<MerchantDto> Handle(ReviewMerchantCommand request, CancellationToken cancellationToken)
     {
         // 1. 读取商户

src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/ReviewMerchantDocumentCommandHandler.cs

@@ -20,6 +20,12 @@ public sealed class ReviewMerchantDocumentCommandHandler(
     ICurrentUserAccessor currentUserAccessor)
     : IRequestHandler<ReviewMerchantDocumentCommand, MerchantDocumentDto>
 {
+    /// <summary>
+    /// 审核商户证照。
+    /// </summary>
+    /// <param name="request">审核命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>证照 DTO。</returns>
     public async Task<MerchantDocumentDto> Handle(ReviewMerchantDocumentCommand request, CancellationToken cancellationToken)
     {
         // 1. 读取证照

src/Application/TakeoutSaaS.Application/App/Merchants/Handlers/UpdateMerchantContractStatusCommandHandler.cs

@@ -20,6 +20,12 @@ public sealed class UpdateMerchantContractStatusCommandHandler(
     ICurrentUserAccessor currentUserAccessor)
     : IRequestHandler<UpdateMerchantContractStatusCommand, MerchantContractDto>
 {
+    /// <summary>
+    /// 更新合同状态。
+    /// </summary>
+    /// <param name="request">状态变更命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>合同 DTO。</returns>
     public async Task<MerchantContractDto> Handle(UpdateMerchantContractStatusCommand request, CancellationToken cancellationToken)
     {
         // 1. 查询合同

src/Application/TakeoutSaaS.Application/App/Merchants/MerchantMapping.cs

@@ -8,6 +8,11 @@ namespace TakeoutSaaS.Application.App.Merchants;
 /// </summary>
 internal static class MerchantMapping
 {
+    /// <summary>
+    /// 将商户实体映射为 DTO。
+    /// </summary>
+    /// <param name="merchant">商户实体。</param>
+    /// <returns>商户 DTO。</returns>
     public static MerchantDto ToDto(Merchant merchant) => new()
     {
         Id = merchant.Id,
@@ -23,6 +28,11 @@ internal static class MerchantMapping
         CreatedAt = merchant.CreatedAt
     };
 
+    /// <summary>
+    /// 将商户证照实体映射为 DTO。
+    /// </summary>
+    /// <param name="document">证照实体。</param>
+    /// <returns>证照 DTO。</returns>
     public static MerchantDocumentDto ToDto(MerchantDocument document) => new()
     {
         Id = document.Id,
@@ -37,6 +47,11 @@ internal static class MerchantMapping
         CreatedAt = document.CreatedAt
     };
 
+    /// <summary>
+    /// 将商户合同实体映射为 DTO。
+    /// </summary>
+    /// <param name="contract">合同实体。</param>
+    /// <returns>合同 DTO。</returns>
     public static MerchantContractDto ToDto(MerchantContract contract) => new()
     {
         Id = contract.Id,
@@ -51,6 +66,11 @@ internal static class MerchantMapping
         TerminationReason = contract.TerminationReason
     };
 
+    /// <summary>
+    /// 将商户审核日志实体映射为 DTO。
+    /// </summary>
+    /// <param name="log">审核日志实体。</param>
+    /// <returns>审核日志 DTO。</returns>
     public static MerchantAuditLogDto ToDto(MerchantAuditLog log) => new()
     {
         Id = log.Id,
@@ -62,6 +82,11 @@ internal static class MerchantMapping
         CreatedAt = log.CreatedAt
     };
 
+    /// <summary>
+    /// 将商户分类实体映射为 DTO。
+    /// </summary>
+    /// <param name="category">分类实体。</param>
+    /// <returns>分类 DTO。</returns>
     public static MerchantCategoryDto ToDto(MerchantCategory category) => new()
     {
         Id = category.Id,
@@ -71,12 +96,27 @@ internal static class MerchantMapping
         CreatedAt = category.CreatedAt
     };
 
+    /// <summary>
+    /// 将证照集合映射为 DTO 集合。
+    /// </summary>
+    /// <param name="documents">证照集合。</param>
+    /// <returns>证照 DTO 列表。</returns>
     public static IReadOnlyList<MerchantDocumentDto> ToDocumentDtos(IEnumerable<MerchantDocument> documents)
         => documents.Select(ToDto).ToList();
 
+    /// <summary>
+    /// 将合同集合映射为 DTO 集合。
+    /// </summary>
+    /// <param name="contracts">合同集合。</param>
+    /// <returns>合同 DTO 列表。</returns>
     public static IReadOnlyList<MerchantContractDto> ToContractDtos(IEnumerable<MerchantContract> contracts)
         => contracts.Select(ToDto).ToList();
 
+    /// <summary>
+    /// 将分类集合映射为 DTO 集合。
+    /// </summary>
+    /// <param name="categories">分类集合。</param>
+    /// <returns>分类 DTO 列表。</returns>
     public static IReadOnlyList<MerchantCategoryDto> ToCategoryDtos(IEnumerable<MerchantCategory> categories)
         => categories.Select(ToDto).ToList();
 }