chore: add documentation comments and stylecop rules

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

@@ -16,16 +16,11 @@ namespace TakeoutSaaS.AdminApi.Controllers;
 /// <summary>
 /// 支付记录管理。
 /// </summary>
-/// <remarks>
-/// 初始化控制器。
-/// </remarks>
 [ApiVersion("1.0")]
 [Authorize]
 [Route("api/admin/v{version:apiVersion}/payments")]
 public sealed class PaymentsController(IMediator mediator) : BaseApiController
 {
-
-
     /// <summary>
     /// 创建支付记录。
     /// </summary>
@@ -34,7 +29,10 @@ public sealed class PaymentsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<PaymentDto>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<PaymentDto>> Create([FromBody] CreatePaymentCommand command, CancellationToken cancellationToken)
     {
+        // 1. 创建支付记录
         var result = await mediator.Send(command, cancellationToken);
+
+        // 2. 返回创建结果
         return ApiResponse<PaymentDto>.Ok(result);
     }
 
@@ -53,6 +51,7 @@ public sealed class PaymentsController(IMediator mediator) : BaseApiController
         [FromQuery] bool sortDesc = true,
         CancellationToken cancellationToken = default)
     {
+        // 1. 组装查询参数并执行查询
         var result = await mediator.Send(new SearchPaymentsQuery
         {
             OrderId = orderId,
@@ -63,6 +62,7 @@ public sealed class PaymentsController(IMediator mediator) : BaseApiController
             SortDescending = sortDesc
         }, cancellationToken);
 
+        // 2. 返回分页结果
         return ApiResponse<PagedResult<PaymentDto>>.Ok(result);
     }
 
@@ -75,7 +75,10 @@ public sealed class PaymentsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status404NotFound)]
     public async Task<ApiResponse<PaymentDto>> Detail(long paymentId, CancellationToken cancellationToken)
     {
+        // 1. 查询支付记录详情
         var result = await mediator.Send(new GetPaymentByIdQuery { PaymentId = paymentId }, cancellationToken);
+
+        // 2. 返回详情或 404
         return result == null
             ? ApiResponse<PaymentDto>.Error(ErrorCodes.NotFound, "支付记录不存在")
             : ApiResponse<PaymentDto>.Ok(result);
@@ -90,11 +93,16 @@ public sealed class PaymentsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status404NotFound)]
     public async Task<ApiResponse<PaymentDto>> Update(long paymentId, [FromBody] UpdatePaymentCommand command, CancellationToken cancellationToken)
     {
+        // 1. 确保命令包含支付记录标识
         if (command.PaymentId == 0)
         {
             command = command with { PaymentId = paymentId };
         }
+
+        // 2. 执行更新
         var result = await mediator.Send(command, cancellationToken);
+
+        // 3. 返回更新结果或 404
         return result == null
             ? ApiResponse<PaymentDto>.Error(ErrorCodes.NotFound, "支付记录不存在")
             : ApiResponse<PaymentDto>.Ok(result);
@@ -109,7 +117,10 @@ public sealed class PaymentsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status404NotFound)]
     public async Task<ApiResponse<object>> Delete(long paymentId, CancellationToken cancellationToken)
     {
+        // 1. 执行删除
         var success = await mediator.Send(new DeletePaymentCommand { PaymentId = paymentId }, cancellationToken);
+
+        // 2. 返回结果或 404
         return success
             ? ApiResponse<object>.Ok(null)
             : ApiResponse<object>.Error(ErrorCodes.NotFound, "支付记录不存在");