Merge branch 'chore/comment-fix' into dev

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

@@ -1,6 +1,5 @@
 using MediatR;
 using Microsoft.AspNetCore.Authorization;
-using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using TakeoutSaaS.Application.App.Products.Commands;
 using TakeoutSaaS.Application.App.Products.Dto;
@@ -16,31 +15,31 @@ 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>
+    /// <returns>创建的商品信息。</returns>
     [HttpPost]
     [PermissionAuthorize("product:create")]
     [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);
     }
 
     /// <summary>
     /// 查询商品列表。
     /// </summary>
+    /// <returns>商品分页列表。</returns>
     [HttpGet]
     [PermissionAuthorize("product:read")]
     [ProducesResponseType(typeof(ApiResponse<PagedResult<ProductDto>>), StatusCodes.Status200OK)]
@@ -54,6 +53,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,19 +65,24 @@ public sealed class ProductsController(IMediator mediator) : BaseApiController
             SortDescending = sortDesc
         }, cancellationToken);
 
+        // 2. 返回分页结果
         return ApiResponse<PagedResult<ProductDto>>.Ok(result);
     }
 
     /// <summary>
     /// 获取商品详情。
     /// </summary>
+    /// <returns>商品详情。</returns>
     [HttpGet("{productId:long}")]
     [PermissionAuthorize("product:read")]
     [ProducesResponseType(typeof(ApiResponse<ProductDto>), StatusCodes.Status200OK)]
     [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);
@@ -86,17 +91,23 @@ public sealed class ProductsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 更新商品。
     /// </summary>
+    /// <returns>更新后的商品信息。</returns>
     [HttpPut("{productId:long}")]
     [PermissionAuthorize("product:update")]
     [ProducesResponseType(typeof(ApiResponse<ProductDto>), StatusCodes.Status200OK)]
     [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);
@@ -105,13 +116,17 @@ public sealed class ProductsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 删除商品。
     /// </summary>
+    /// <returns>删除结果。</returns>
     [HttpDelete("{productId:long}")]
     [PermissionAuthorize("product:delete")]
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status200OK)]
     [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, "商品不存在");