chore: add documentation comments and stylecop rules

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

@@ -32,7 +32,10 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<IReadOnlyList<RoleTemplateDto>>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<IReadOnlyList<RoleTemplateDto>>> ListTemplates([FromQuery] bool? isActive, CancellationToken cancellationToken)
     {
+        // 1. 查询模板列表
         var result = await mediator.Send(new ListRoleTemplatesQuery { IsActive = isActive }, cancellationToken);
+
+        // 2. 返回模板集合
         return ApiResponse<IReadOnlyList<RoleTemplateDto>>.Ok(result);
     }
 
@@ -48,7 +51,10 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<RoleTemplateDto>), StatusCodes.Status404NotFound)]
     public async Task<ApiResponse<RoleTemplateDto>> GetTemplate(string templateCode, CancellationToken cancellationToken)
     {
+        // 1. 查询指定模板
         var result = await mediator.Send(new GetRoleTemplateQuery { TemplateCode = templateCode }, cancellationToken);
+
+        // 2. 返回模板或 404
         return result is null
             ? ApiResponse<RoleTemplateDto>.Error(StatusCodes.Status404NotFound, "角色模板不存在")
             : ApiResponse<RoleTemplateDto>.Ok(result);
@@ -62,7 +68,10 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<RoleTemplateDto>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<RoleTemplateDto>> CreateTemplate([FromBody, Required] CreateRoleTemplateCommand command, CancellationToken cancellationToken)
     {
+        // 1. 创建模板
         var result = await mediator.Send(command, cancellationToken);
+
+        // 2. 返回创建结果
         return ApiResponse<RoleTemplateDto>.Ok(result);
     }
 
@@ -78,8 +87,13 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
         [FromBody, Required] UpdateRoleTemplateCommand command,
         CancellationToken cancellationToken)
     {
+        // 1. 绑定模板编码
         command = command with { TemplateCode = templateCode };
+
+        // 2. 执行更新
         var result = await mediator.Send(command, cancellationToken);
+
+        // 3. 返回更新结果或 404
         return result is null
             ? ApiResponse<RoleTemplateDto>.Error(StatusCodes.Status404NotFound, "角色模板不存在")
             : ApiResponse<RoleTemplateDto>.Ok(result);
@@ -93,7 +107,10 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<bool>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<bool>> DeleteTemplate(string templateCode, CancellationToken cancellationToken)
     {
+        // 1. 删除模板
         var result = await mediator.Send(new DeleteRoleTemplateCommand { TemplateCode = templateCode }, cancellationToken);
+
+        // 2. 返回执行结果
         return ApiResponse<bool>.Ok(result);
     }
 
@@ -112,7 +129,10 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
         [FromBody, Required] CopyRoleTemplateCommand command,
         CancellationToken cancellationToken)
     {
+        // 1. 绑定模板编码
         command = command with { TemplateCode = templateCode };
+
+        // 2. 复制模板并返回角色
         var result = await mediator.Send(command, cancellationToken);
         return ApiResponse<RoleDto>.Ok(result);
     }
@@ -131,7 +151,10 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
         [FromBody] InitializeRoleTemplatesCommand? command,
         CancellationToken cancellationToken)
     {
+        // 1. 确保命令实例存在
         command ??= new InitializeRoleTemplatesCommand();
+
+        // 2. 执行初始化
         var result = await mediator.Send(command, cancellationToken);
         return ApiResponse<IReadOnlyList<RoleDto>>.Ok(result);
     }
@@ -149,7 +172,10 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<PagedResult<RoleDto>>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<PagedResult<RoleDto>>> Search([FromQuery] SearchRolesQuery query, CancellationToken cancellationToken)
     {
+        // 1. 查询角色分页
         var result = await mediator.Send(query, cancellationToken);
+
+        // 2. 返回分页数据
         return ApiResponse<PagedResult<RoleDto>>.Ok(result);
     }
 
@@ -161,7 +187,10 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<RoleDto>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<RoleDto>> Create([FromBody, Required] CreateRoleCommand command, CancellationToken cancellationToken)
     {
+        // 1. 创建角色
         var result = await mediator.Send(command, cancellationToken);
+
+        // 2. 返回创建结果
         return ApiResponse<RoleDto>.Ok(result);
     }
 
@@ -174,8 +203,13 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<RoleDto>), StatusCodes.Status404NotFound)]
     public async Task<ApiResponse<RoleDto>> Update(long roleId, [FromBody, Required] UpdateRoleCommand command, CancellationToken cancellationToken)
     {
+        // 1. 绑定角色标识
         command = command with { RoleId = roleId };
+
+        // 2. 执行更新
         var result = await mediator.Send(command, cancellationToken);
+
+        // 3. 返回更新结果或 404
         return result is null
             ? ApiResponse<RoleDto>.Error(StatusCodes.Status404NotFound, "角色不存在")
             : ApiResponse<RoleDto>.Ok(result);
@@ -189,7 +223,10 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<bool>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<bool>> Delete(long roleId, CancellationToken cancellationToken)
     {
+        // 1. 构建删除命令
         var command = new DeleteRoleCommand { RoleId = roleId };
+
+        // 2. 执行删除
         var result = await mediator.Send(command, cancellationToken);
         return ApiResponse<bool>.Ok(result);
     }
@@ -202,7 +239,10 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<bool>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<bool>> BindPermissions(long roleId, [FromBody, Required] BindRolePermissionsCommand command, CancellationToken cancellationToken)
     {
+        // 1. 绑定角色标识
         command = command with { RoleId = roleId };
+
+        // 2. 执行覆盖式授权
         var result = await mediator.Send(command, cancellationToken);
         return ApiResponse<bool>.Ok(result);
     }