AGSS/Controllers/Admin/AdminRoleControllers.cs

@@ -6,20 +6,42 @@ using Microsoft.AspNetCore.Mvc;
 
 namespace AGSS.Controllers.Admin;
 
+/// <summary>
+/// 控制器类，用于管理角色相关的操作，包括添加角色、分配角色给用户以及通过角色查询用户。
+/// 该控制器仅限具有"Admin"角色的用户访问。
+/// </summary>
 [Authorize(Roles = "Admin")]
 [Route("api/v1/[controller]/[action]")]
 public class AdminRoleControllers:ControllerBase
 {
-    
+    /// <summary>
+    /// 角色管理器，用于处理角色相关的操作，如创建、查询等。
+    /// 此角色管理器实例主要用于与RoleModel类型的实体进行交互，
+    /// 支持添加新角色、为用户分配角色等功能。
+    /// </summary>
     private readonly RoleManager<RoleModel> _roleManager;
+
+    /// <summary>
+    /// 用户管理器实例，用于处理用户相关的操作如添加角色、查询用户等。
+    /// 此实例通过依赖注入的方式在构造函数中初始化，并在整个控制器生命周期内可用。
+    /// </summary>
     private readonly UserManager<UserModel> _userManager; // Assuming UserModel is the type of user
 
+    /// <summary>
+    /// 管理员角色控制器，用于处理与角色相关的操作，如添加角色、分配角色给用户以及通过角色查询用户。
+    /// 该控制器下的所有方法都需要管理员权限才能访问。
+    /// </summary>
     public AdminRoleControllers(RoleManager<RoleModel> roleManager, UserManager<UserModel> userManager)
     {
         _roleManager = roleManager;
         _userManager = userManager;
     }
 
+    /// <summary>
+    /// 添加新角色
+    /// </summary>
+    /// <param name="role">要添加的角色信息</param>
+    /// <returns>返回操作结果，包含状态码、消息和数据</returns>
     [HttpPost]
     public async Task<IActionResult> AddRole([FromBody] RoleModel role)
     {
@@ -40,6 +62,13 @@ public class AdminRoleControllers:ControllerBase
             return Ok(new ReturnTemplate(StatusCodes.Status500InternalServerError,"创建失败","Failed to create role: " + string.Join(", ", result.Errors.Select(e => e.Description))));
         }
     }
+
+    /// <summary>
+    /// 为指定用户分配角色
+    /// </summary>
+    /// <param name="userId">用户的唯一标识符</param>
+    /// <param name="roleName">要分配的角色名称</param>
+    /// <returns>返回一个包含操作结果的ReturnTemplate对象，其中Code表示状态码，Msg表示消息，Data表示附加数据（如果有的话）</returns>
     [HttpPost]
     public async Task<IActionResult> EndowRole(string userId, string roleName)
     {
@@ -67,10 +96,11 @@ public class AdminRoleControllers:ControllerBase
     }
 
 
-/// <summary>
-/// 通过角色查询用户，支持分页
-/// </summary>
-/// <returns></returns>
+    /// <summary>
+    /// 通过角色查询用户，支持分页
+    /// </summary>
+    /// <param name="request">包含角色名称、页码和每页大小的请求对象</param>
+    /// <returns>返回包含总用户数和当前页用户的响应对象</returns>
     [HttpPost]
     public async Task<IActionResult> SearchUserFromRole([FromBody] SearchUserFromRoleRequest request)
     {
@@ -102,16 +132,45 @@ public class AdminRoleControllers:ControllerBase
         return Ok(new ReturnTemplate(200, "查询成功", response));
     }
 
+    /// <summary>
+    /// 用于通过角色名称查询用户列表的请求模型。支持分页功能。
+    /// </summary>
     public class SearchUserFromRoleRequest
     {
+        /// <summary>
+        /// 表示角色的名称。此属性用于指定或获取与用户管理相关的角色名称。
+        /// 在进行角色分配、查询等操作时，需要提供正确的角色名称以确保操作的成功执行。
+        /// </summary>
         public string RoleName { get; set; }
+
+        /// <summary>
+        /// 表示当前请求的页码，默认为1。用于分页查询用户时指定从哪一页开始获取数据。
+        /// </summary>
         public int Page { get; set; } = 1;
+
+        /// <summary>
+        /// 每页显示的用户数量。默认值为10。
+        /// 该属性用于分页查询中指定每一页应包含的用户条目数。
+        /// </summary>
         public int PageSize { get; set; } = 10;
     }
 
+    /// <summary>
+    /// 表示通过角色查询用户后返回的响应数据。
+    /// 该类用于封装查询结果，包括总用户数和分页后的用户列表。
+    /// </summary>
     public class SearchUserFromRoleResponse
     {
+        /// <summary>
+        /// 表示属于特定角色的用户总数。
+        /// </summary>
+        /// <remarks>此属性用于分页查询中，返回匹配给定角色名称的所有用户的数量。</remarks>
         public int TotalCount { get; set; }
+
+        /// <summary>
+        /// 表示属于特定角色的用户列表。该属性用于存储和返回在给定角色下的所有用户。
+        /// </summary>
+        /// <remarks>此列表通常作为查询结果的一部分，例如通过角色名搜索用户时返回的数据。</remarks>
         public List<UserModel> Users { get; set; }
     }
 }

AGSS/Controllers/User/UserControllers.cs

@@ -8,21 +8,34 @@ using Microsoft.AspNetCore.Mvc;
 
 namespace AGSS.Controllers.User;
 
+/// <summary>
+/// 用户控制器，提供与用户相关的API接口。
+/// </summary>
+/// <remarks>此控制器需要授权才能访问其方法。</remarks>
 [Authorize]
 [Route("api/v1/[controller]/[action]")]
 public class UserControllers:ControllerBase
-{ 
-  
+{
+    /// <summary>
+    /// 用户服务实例，用于执行与用户相关的操作。
+    /// 该服务提供了一系列方法来处理用户的查询和更新等操作，
+    /// 包括但不限于获取用户详细信息、修改用户资料等功能。
+    /// </summary>
     private readonly UserService _userService;
 
+    /// <summary>
+    /// 用户控制器，提供用户相关操作的API接口。
+    /// </summary>
     public UserControllers(UserService userService, UserManager<UserModel> userManager)
     {
         _userService = userService;
        }
 
-   
- 
 
+    /// <summary>
+    /// 获取当前登录用户的个人信息。
+    /// </summary>
+    /// <returns>返回一个包含状态码、消息和用户信息的ReturnTemplate对象。如果成功，状态码为200；如果失败，状态码为500。</returns>
     [HttpGet]
     public async Task<IActionResult> My()
     {