docs: 完善参数注释与StyleCop配置

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

@@ -1,7 +1,6 @@
 using System.ComponentModel.DataAnnotations;
 using MediatR;
 using Microsoft.AspNetCore.Authorization;
-using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using TakeoutSaaS.Application.Identity.Commands;
 using TakeoutSaaS.Application.Identity.Contracts;
@@ -26,49 +25,48 @@ public sealed class PermissionsController(IMediator mediator) : BaseApiControlle
     /// <remarks>
     /// 示例：GET /api/admin/v1/permissions?keyword=order&amp;page=1&amp;pageSize=20
     /// </remarks>
+    /// <param name="query">查询条件。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>权限的分页结果。</returns>
     [HttpGet]
     [PermissionAuthorize("identity:permission:read")]
     [ProducesResponseType(typeof(ApiResponse<PagedResult<PermissionDto>>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<PagedResult<PermissionDto>>> Search([FromQuery] SearchPermissionsQuery query, CancellationToken cancellationToken)
     {
-        // 1. 查询权限分页
         var result = await mediator.Send(query, cancellationToken);
-
-        // 2. 返回分页数据
         return ApiResponse<PagedResult<PermissionDto>>.Ok(result);
     }
 
     /// <summary>
     /// 创建权限。
     /// </summary>
+    /// <param name="command">创建命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>创建的权限。</returns>
     [HttpPost]
     [PermissionAuthorize("identity:permission:create")]
     [ProducesResponseType(typeof(ApiResponse<PermissionDto>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<PermissionDto>> Create([FromBody, Required] CreatePermissionCommand command, CancellationToken cancellationToken)
     {
-        // 1. 创建权限
         var result = await mediator.Send(command, cancellationToken);
-
-        // 2. 返回创建结果
         return ApiResponse<PermissionDto>.Ok(result);
     }
 
     /// <summary>
     /// 更新权限。
     /// </summary>
+    /// <param name="permissionId">权限 ID。</param>
+    /// <param name="command">更新命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>更新后的权限，未找到时返回 404。</returns>
     [HttpPut("{permissionId:long}")]
     [PermissionAuthorize("identity:permission:update")]
     [ProducesResponseType(typeof(ApiResponse<PermissionDto>), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ApiResponse<PermissionDto>), StatusCodes.Status404NotFound)]
     public async Task<ApiResponse<PermissionDto>> Update(long permissionId, [FromBody, Required] UpdatePermissionCommand command, CancellationToken cancellationToken)
     {
-        // 1. 绑定权限标识
         command = command with { PermissionId = permissionId };
-
-        // 2. 执行更新
         var result = await mediator.Send(command, cancellationToken);
-
-        // 3. 返回更新结果或 404
         return result is null
             ? ApiResponse<PermissionDto>.Error(StatusCodes.Status404NotFound, "权限不存在")
             : ApiResponse<PermissionDto>.Ok(result);
@@ -77,15 +75,15 @@ public sealed class PermissionsController(IMediator mediator) : BaseApiControlle
     /// <summary>
     /// 删除权限。
     /// </summary>
+    /// <param name="permissionId">权限 ID。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>删除结果。</returns>
     [HttpDelete("{permissionId:long}")]
     [PermissionAuthorize("identity:permission:delete")]
     [ProducesResponseType(typeof(ApiResponse<bool>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<bool>> Delete(long permissionId, CancellationToken cancellationToken)
     {
-        // 1. 构建删除命令
         var command = new DeletePermissionCommand { PermissionId = permissionId };
-
-        // 2. 执行删除
         var result = await mediator.Send(command, cancellationToken);
         return ApiResponse<bool>.Ok(result);
     }