chore: add documentation comments and stylecop rules

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

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