docs: 完善AdminApi控制器注释和代码规范

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

@@ -25,6 +25,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <remarks>
     /// 示例：GET /api/admin/v1/roles/templates
     /// </remarks>
+    /// <returns>角色模板列表。</returns>
     [HttpGet("templates")]
     [PermissionAuthorize("identity:role:read")]
     [ProducesResponseType(typeof(ApiResponse<IReadOnlyList<RoleTemplateDto>>), StatusCodes.Status200OK)]
@@ -43,6 +44,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <remarks>
     /// 示例：GET /api/admin/v1/roles/templates/tenant-admin
     /// </remarks>
+    /// <returns>角色模板详情。</returns>
     [HttpGet("templates/{templateCode}")]
     [PermissionAuthorize("identity:role:read")]
     [ProducesResponseType(typeof(ApiResponse<RoleTemplateDto>), StatusCodes.Status200OK)]
@@ -61,6 +63,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 创建角色模板。
     /// </summary>
+    /// <returns>创建的角色模板信息。</returns>
     [HttpPost("templates")]
     [PermissionAuthorize("role-template:create")]
     [ProducesResponseType(typeof(ApiResponse<RoleTemplateDto>), StatusCodes.Status200OK)]
@@ -76,6 +79,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 更新角色模板。
     /// </summary>
+    /// <returns>更新后的角色模板信息。</returns>
     [HttpPut("templates/{templateCode}")]
     [PermissionAuthorize("role-template:update")]
     [ProducesResponseType(typeof(ApiResponse<RoleTemplateDto>), StatusCodes.Status200OK)]
@@ -100,6 +104,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 删除角色模板。
     /// </summary>
+    /// <returns>删除结果。</returns>
     [HttpDelete("templates/{templateCode}")]
     [PermissionAuthorize("role-template:delete")]
     [ProducesResponseType(typeof(ApiResponse<bool>), StatusCodes.Status200OK)]
@@ -119,6 +124,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// 示例：POST /api/admin/v1/roles/templates/store-manager/copy
     /// Body: { "roleName": "新区店长" }
     /// </remarks>
+    /// <returns>创建的角色信息。</returns>
     [HttpPost("templates/{templateCode}/copy")]
     [PermissionAuthorize("identity:role:create")]
     [ProducesResponseType(typeof(ApiResponse<RoleDto>), StatusCodes.Status200OK)]
@@ -142,6 +148,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// 示例：POST /api/admin/v1/roles/templates/init
     /// Body: { "templateCodes": ["tenant-admin","store-manager","store-staff"] }
     /// </remarks>
+    /// <returns>创建的角色列表。</returns>
     [HttpPost("templates/init")]
     [PermissionAuthorize("identity:role:create")]
     [ProducesResponseType(typeof(ApiResponse<IReadOnlyList<RoleDto>>), StatusCodes.Status200OK)]
@@ -165,6 +172,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// GET /api/admin/v1/roles?keyword=ops&amp;page=1&amp;pageSize=20
     /// Header: Authorization: Bearer &lt;JWT&gt; + X-Tenant-Id
     /// </remarks>
+    /// <returns>角色分页结果。</returns>
     [HttpGet]
     [PermissionAuthorize("identity:role:read")]
     [ProducesResponseType(typeof(ApiResponse<PagedResult<RoleDto>>), StatusCodes.Status200OK)]
@@ -180,6 +188,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 创建角色。
     /// </summary>
+    /// <returns>创建的角色信息。</returns>
     [HttpPost]
     [PermissionAuthorize("identity:role:create")]
     [ProducesResponseType(typeof(ApiResponse<RoleDto>), StatusCodes.Status200OK)]
@@ -195,6 +204,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 更新角色。
     /// </summary>
+    /// <returns>更新后的角色信息。</returns>
     [HttpPut("{roleId:long}")]
     [PermissionAuthorize("identity:role:update")]
     [ProducesResponseType(typeof(ApiResponse<RoleDto>), StatusCodes.Status200OK)]
@@ -216,6 +226,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 删除角色。
     /// </summary>
+    /// <returns>删除结果。</returns>
     [HttpDelete("{roleId:long}")]
     [PermissionAuthorize("identity:role:delete")]
     [ProducesResponseType(typeof(ApiResponse<bool>), StatusCodes.Status200OK)]
@@ -232,6 +243,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 绑定角色权限（覆盖式）。
     /// </summary>
+    /// <returns>是否绑定成功。</returns>
     [HttpPut("{roleId:long}/permissions")]
     [PermissionAuthorize("identity:role:bind-permission")]
     [ProducesResponseType(typeof(ApiResponse<bool>), StatusCodes.Status200OK)]