chore: add documentation comments and stylecop rules

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

@@ -16,16 +16,11 @@ namespace TakeoutSaaS.AdminApi.Controllers;
 /// <summary>
 /// 商品管理。
 /// </summary>
-/// <remarks>
-/// 初始化控制器。
-/// </remarks>
 [ApiVersion("1.0")]
 [Authorize]
 [Route("api/admin/v{version:apiVersion}/products")]
 public sealed class ProductsController(IMediator mediator) : BaseApiController
 {
-
-
     /// <summary>
     /// 创建商品。
     /// </summary>
@@ -34,7 +29,10 @@ public sealed class ProductsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<ProductDto>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<ProductDto>> Create([FromBody] CreateProductCommand command, CancellationToken cancellationToken)
     {
+        // 1. 创建商品
         var result = await mediator.Send(command, cancellationToken);
+
+        // 2. 返回创建结果
         return ApiResponse<ProductDto>.Ok(result);
     }
 
@@ -54,6 +52,7 @@ public sealed class ProductsController(IMediator mediator) : BaseApiController
         [FromQuery] bool sortDesc = true,
         CancellationToken cancellationToken = default)
     {
+        // 1. 组装查询参数并执行查询
         var result = await mediator.Send(new SearchProductsQuery
         {
             StoreId = storeId,
@@ -65,6 +64,7 @@ public sealed class ProductsController(IMediator mediator) : BaseApiController
             SortDescending = sortDesc
         }, cancellationToken);
 
+        // 2. 返回分页结果
         return ApiResponse<PagedResult<ProductDto>>.Ok(result);
     }
 
@@ -77,7 +77,10 @@ public sealed class ProductsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status404NotFound)]
     public async Task<ApiResponse<ProductDto>> Detail(long productId, CancellationToken cancellationToken)
     {
+        // 1. 查询商品详情
         var result = await mediator.Send(new GetProductByIdQuery { ProductId = productId }, cancellationToken);
+
+        // 2. 返回详情或 404
         return result == null
             ? ApiResponse<ProductDto>.Error(ErrorCodes.NotFound, "商品不存在")
             : ApiResponse<ProductDto>.Ok(result);
@@ -92,11 +95,16 @@ public sealed class ProductsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status404NotFound)]
     public async Task<ApiResponse<ProductDto>> Update(long productId, [FromBody] UpdateProductCommand command, CancellationToken cancellationToken)
     {
+        // 1. 确保命令包含商品标识
         if (command.ProductId == 0)
         {
             command = command with { ProductId = productId };
         }
+
+        // 2. 执行更新
         var result = await mediator.Send(command, cancellationToken);
+
+        // 3. 返回更新结果或 404
         return result == null
             ? ApiResponse<ProductDto>.Error(ErrorCodes.NotFound, "商品不存在")
             : ApiResponse<ProductDto>.Ok(result);
@@ -111,7 +119,10 @@ public sealed class ProductsController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status404NotFound)]
     public async Task<ApiResponse<object>> Delete(long productId, CancellationToken cancellationToken)
     {
+        // 1. 执行删除
         var success = await mediator.Send(new DeleteProductCommand { ProductId = productId }, cancellationToken);
+
+        // 2. 返回结果或 404
         return success
             ? ApiResponse<object>.Ok(null)
             : ApiResponse<object>.Error(ErrorCodes.NotFound, "商品不存在");