chore: add documentation comments and stylecop rules

src/Api/TakeoutSaaS.AdminApi/Controllers/MerchantsController.cs

@@ -16,16 +16,11 @@ namespace TakeoutSaaS.AdminApi.Controllers;
 /// <summary>
 /// 商户管理。
 /// </summary>
-/// <remarks>
-/// 初始化控制器。
-/// </remarks>
 [ApiVersion("1.0")]
 [Authorize]
 [Route("api/admin/v{version:apiVersion}/merchants")]
 public sealed class MerchantsController(IMediator mediator) : BaseApiController
 {
-
-
     /// <summary>
     /// 创建商户。
     /// </summary>
@@ -34,7 +29,10 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<MerchantDto>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<MerchantDto>> Create([FromBody] CreateMerchantCommand command, CancellationToken cancellationToken)
     {
+        // 1. 创建商户
         var result = await mediator.Send(command, cancellationToken);
+
+        // 2. 返回创建结果
         return ApiResponse<MerchantDto>.Ok(result);
     }
 
@@ -52,6 +50,7 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
         [FromQuery] bool sortDesc = true,
         CancellationToken cancellationToken = default)
     {
+        // 1. 组装查询参数并执行查询
         var result = await mediator.Send(new SearchMerchantsQuery
         {
             Status = status,
@@ -60,6 +59,8 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
             SortBy = sortBy,
             SortDescending = sortDesc
         }, cancellationToken);
+
+        // 2. 返回分页结果
         return ApiResponse<PagedResult<MerchantDto>>.Ok(result);
     }
 
@@ -72,12 +73,16 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status404NotFound)]
     public async Task<ApiResponse<MerchantDto>> Update(long merchantId, [FromBody] UpdateMerchantCommand command, CancellationToken cancellationToken)
     {
+        // 1. 绑定商户标识
         if (command.MerchantId == 0)
         {
             command = command with { MerchantId = merchantId };
         }
 
+        // 2. 执行更新
         var result = await mediator.Send(command, cancellationToken);
+
+        // 3. 返回更新结果或 404
         return result == null
             ? ApiResponse<MerchantDto>.Error(ErrorCodes.NotFound, "商户不存在")
             : ApiResponse<MerchantDto>.Ok(result);
@@ -92,7 +97,10 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status404NotFound)]
     public async Task<ApiResponse<object>> Delete(long merchantId, CancellationToken cancellationToken)
     {
+        // 1. 执行删除
         var success = await mediator.Send(new DeleteMerchantCommand { MerchantId = merchantId }, cancellationToken);
+
+        // 2. 返回删除结果或 404
         return success
             ? ApiResponse<object>.Ok(null)
             : ApiResponse<object>.Error(ErrorCodes.NotFound, "商户不存在");
@@ -107,7 +115,10 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status404NotFound)]
     public async Task<ApiResponse<MerchantDto>> Detail(long merchantId, CancellationToken cancellationToken)
     {
+        // 1. 查询商户概览
         var result = await mediator.Send(new GetMerchantByIdQuery { MerchantId = merchantId }, cancellationToken);
+
+        // 2. 返回结果或 404
         return result == null
             ? ApiResponse<MerchantDto>.Error(ErrorCodes.NotFound, "商户不存在")
             : ApiResponse<MerchantDto>.Ok(result);
@@ -121,7 +132,10 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<MerchantDetailDto>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<MerchantDetailDto>> FullDetail(long merchantId, CancellationToken cancellationToken)
     {
+        // 1. 查询商户详细资料
         var result = await mediator.Send(new GetMerchantDetailQuery(merchantId), cancellationToken);
+
+        // 2. 返回详情
         return ApiResponse<MerchantDetailDto>.Ok(result);
     }
 
@@ -136,7 +150,10 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
         [FromBody] AddMerchantDocumentCommand body,
         CancellationToken cancellationToken)
     {
+        // 1. 绑定商户标识
         var command = body with { MerchantId = merchantId };
+
+        // 2. 创建证照记录
         var result = await mediator.Send(command, cancellationToken);
         return ApiResponse<MerchantDocumentDto>.Ok(result);
     }
@@ -149,7 +166,10 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<IReadOnlyList<MerchantDocumentDto>>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<IReadOnlyList<MerchantDocumentDto>>> Documents(long merchantId, CancellationToken cancellationToken)
     {
+        // 1. 查询证照列表
         var result = await mediator.Send(new GetMerchantDocumentsQuery(merchantId), cancellationToken);
+
+        // 2. 返回证照集合
         return ApiResponse<IReadOnlyList<MerchantDocumentDto>>.Ok(result);
     }
 
@@ -165,7 +185,10 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
         [FromBody] ReviewMerchantDocumentCommand body,
         CancellationToken cancellationToken)
     {
+        // 1. 绑定商户与证照标识
         var command = body with { MerchantId = merchantId, DocumentId = documentId };
+
+        // 2. 执行审核
         var result = await mediator.Send(command, cancellationToken);
         return ApiResponse<MerchantDocumentDto>.Ok(result);
     }
@@ -181,7 +204,10 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
         [FromBody] CreateMerchantContractCommand body,
         CancellationToken cancellationToken)
     {
+        // 1. 绑定商户标识
         var command = body with { MerchantId = merchantId };
+
+        // 2. 创建合同
         var result = await mediator.Send(command, cancellationToken);
         return ApiResponse<MerchantContractDto>.Ok(result);
     }
@@ -194,7 +220,10 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<IReadOnlyList<MerchantContractDto>>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<IReadOnlyList<MerchantContractDto>>> Contracts(long merchantId, CancellationToken cancellationToken)
     {
+        // 1. 查询合同列表
         var result = await mediator.Send(new GetMerchantContractsQuery(merchantId), cancellationToken);
+
+        // 2. 返回合同集合
         return ApiResponse<IReadOnlyList<MerchantContractDto>>.Ok(result);
     }
 
@@ -210,7 +239,10 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
         [FromBody] UpdateMerchantContractStatusCommand body,
         CancellationToken cancellationToken)
     {
+        // 1. 绑定商户与合同标识
         var command = body with { MerchantId = merchantId, ContractId = contractId };
+
+        // 2. 更新合同状态
         var result = await mediator.Send(command, cancellationToken);
         return ApiResponse<MerchantContractDto>.Ok(result);
     }
@@ -223,7 +255,10 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<MerchantDto>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<MerchantDto>> Review(long merchantId, [FromBody] ReviewMerchantCommand body, CancellationToken cancellationToken)
     {
+        // 1. 绑定商户标识
         var command = body with { MerchantId = merchantId };
+
+        // 2. 执行审核
         var result = await mediator.Send(command, cancellationToken);
         return ApiResponse<MerchantDto>.Ok(result);
     }
@@ -240,7 +275,10 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
         [FromQuery] int pageSize = 20,
         CancellationToken cancellationToken = default)
     {
+        // 1. 查询审核日志
         var result = await mediator.Send(new GetMerchantAuditLogsQuery(merchantId, page, pageSize), cancellationToken);
+
+        // 2. 返回日志分页
         return ApiResponse<PagedResult<MerchantAuditLogDto>>.Ok(result);
     }
 
@@ -252,7 +290,10 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<IReadOnlyList<string>>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<IReadOnlyList<string>>> Categories(CancellationToken cancellationToken)
     {
+        // 1. 查询可选类目
         var result = await mediator.Send(new GetMerchantCategoriesQuery(), cancellationToken);
+
+        // 2. 返回类目列表
         return ApiResponse<IReadOnlyList<string>>.Ok(result);
     }
 }