docs: 完善身份模块文档注释与字段说明

src/Application/TakeoutSaaS.Application/Identity/Handlers/AssignUserRolesCommandHandler.cs

@@ -13,6 +13,12 @@ public sealed class AssignUserRolesCommandHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<AssignUserRolesCommand, bool>
 {
+    /// <summary>
+    /// 处理用户角色分配请求。
+    /// </summary>
+    /// <param name="request">分配命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>执行结果。</returns>
     public async Task<bool> Handle(AssignUserRolesCommand request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文

src/Application/TakeoutSaaS.Application/Identity/Handlers/BindRolePermissionsCommandHandler.cs

@@ -13,6 +13,12 @@ public sealed class BindRolePermissionsCommandHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<BindRolePermissionsCommand, bool>
 {
+    /// <summary>
+    /// 处理角色权限绑定请求。
+    /// </summary>
+    /// <param name="request">绑定命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>执行结果。</returns>
     public async Task<bool> Handle(BindRolePermissionsCommand request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文

src/Application/TakeoutSaaS.Application/Identity/Handlers/CreatePermissionCommandHandler.cs

@@ -15,6 +15,12 @@ public sealed class CreatePermissionCommandHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<CreatePermissionCommand, PermissionDto>
 {
+    /// <summary>
+    /// 处理创建权限请求。
+    /// </summary>
+    /// <param name="request">创建命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>创建后的权限 DTO。</returns>
     public async Task<PermissionDto> Handle(CreatePermissionCommand request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文

src/Application/TakeoutSaaS.Application/Identity/Handlers/CreateRoleCommandHandler.cs

@@ -17,6 +17,12 @@ public sealed class CreateRoleCommandHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<CreateRoleCommand, RoleDto>
 {
+    /// <summary>
+    /// 处理创建角色请求。
+    /// </summary>
+    /// <param name="request">创建命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>创建后的角色 DTO。</returns>
     public async Task<RoleDto> Handle(CreateRoleCommand request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文

src/Application/TakeoutSaaS.Application/Identity/Handlers/DeletePermissionCommandHandler.cs

@@ -13,6 +13,12 @@ public sealed class DeletePermissionCommandHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<DeletePermissionCommand, bool>
 {
+    /// <summary>
+    /// 处理删除权限请求。
+    /// </summary>
+    /// <param name="request">删除命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>执行结果。</returns>
     public async Task<bool> Handle(DeletePermissionCommand request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文

src/Application/TakeoutSaaS.Application/Identity/Handlers/DeleteRoleCommandHandler.cs

@@ -13,6 +13,12 @@ public sealed class DeleteRoleCommandHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<DeleteRoleCommand, bool>
 {
+    /// <summary>
+    /// 处理删除角色请求。
+    /// </summary>
+    /// <param name="request">删除命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>执行结果。</returns>
     public async Task<bool> Handle(DeleteRoleCommand request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文

src/Application/TakeoutSaaS.Application/Identity/Handlers/DeleteRoleTemplateCommandHandler.cs

@@ -10,6 +10,12 @@ namespace TakeoutSaaS.Application.Identity.Handlers;
 public sealed class DeleteRoleTemplateCommandHandler(IRoleTemplateRepository roleTemplateRepository)
     : IRequestHandler<DeleteRoleTemplateCommand, bool>
 {
+    /// <summary>
+    /// 处理删除角色模板请求。
+    /// </summary>
+    /// <param name="request">删除命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>执行结果。</returns>
     public async Task<bool> Handle(DeleteRoleTemplateCommand request, CancellationToken cancellationToken)
     {
         // 1. 查询模板

src/Application/TakeoutSaaS.Application/Identity/Handlers/MenuMapper.cs

@@ -9,6 +9,11 @@ namespace TakeoutSaaS.Application.Identity.Handlers;
 /// </summary>
 internal static class MenuMapper
 {
+    /// <summary>
+    /// 将菜单实体映射为 DTO。
+    /// </summary>
+    /// <param name="entity">菜单实体。</param>
+    /// <returns>菜单定义 DTO。</returns>
     public static MenuDefinitionDto ToDto(MenuDefinition entity)
     {
         // 1. 解析权限字段
@@ -42,6 +47,11 @@ internal static class MenuMapper
         };
     }
 
+    /// <summary>
+    /// 将 DTO 字段填充到实体。
+    /// </summary>
+    /// <param name="entity">菜单实体。</param>
+    /// <param name="dto">菜单 DTO。</param>
     public static void FillEntity(MenuDefinition entity, MenuDefinitionDto dto)
     {
         // 1. 赋值基础字段
@@ -65,6 +75,14 @@ internal static class MenuMapper
             : JsonSerializer.Serialize(dto.AuthList);
     }
 
+    /// <summary>
+    /// 构建或更新菜单实体并返回 DTO。
+    /// </summary>
+    /// <param name="existing">已存在的菜单实体。</param>
+    /// <param name="tenantId">租户 ID。</param>
+    /// <param name="name">菜单名称。</param>
+    /// <param name="payload">菜单 DTO 载荷。</param>
+    /// <returns>菜单定义 DTO。</returns>
     public static MenuDefinitionDto FromCommand(MenuDefinition? existing, long tenantId, string name, MenuDefinitionDto payload)
     {
         // 1. 构造实体
@@ -81,11 +99,21 @@ internal static class MenuMapper
         return ToDto(entity);
     }
 
+    /// <summary>
+    /// 将权限/角色集合合并为存储字符串。
+    /// </summary>
+    /// <param name="codes">编码集合。</param>
+    /// <returns>逗号分隔字符串。</returns>
     public static string JoinCodes(IEnumerable<string> codes)
     {
         return string.Join(',', codes.Where(x => !string.IsNullOrWhiteSpace(x)).Select(x => x.Trim()).Distinct(StringComparer.OrdinalIgnoreCase));
     }
 
+    /// <summary>
+    /// 将逗号分隔编码拆分为集合。
+    /// </summary>
+    /// <param name="codes">编码字符串。</param>
+    /// <returns>编码数组。</returns>
     public static string[] SplitCodes(string? codes)
     {
         if (string.IsNullOrWhiteSpace(codes))

src/Application/TakeoutSaaS.Application/Identity/Handlers/PermissionTreeQueryHandler.cs

@@ -14,6 +14,12 @@ public sealed class PermissionTreeQueryHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<PermissionTreeQuery, IReadOnlyList<PermissionTreeDto>>
 {
+    /// <summary>
+    /// 构建权限树。
+    /// </summary>
+    /// <param name="request">查询参数。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>权限树列表。</returns>
     public async Task<IReadOnlyList<PermissionTreeDto>> Handle(PermissionTreeQuery request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文并查询权限

src/Application/TakeoutSaaS.Application/Identity/Handlers/SearchPermissionsQueryHandler.cs

@@ -15,6 +15,12 @@ public sealed class SearchPermissionsQueryHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<SearchPermissionsQuery, PagedResult<PermissionDto>>
 {
+    /// <summary>
+    /// 执行权限分页查询。
+    /// </summary>
+    /// <param name="request">查询参数。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>分页结果。</returns>
     public async Task<PagedResult<PermissionDto>> Handle(SearchPermissionsQuery request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文并查询权限

src/Application/TakeoutSaaS.Application/Identity/Handlers/SearchRolesQueryHandler.cs

@@ -15,6 +15,12 @@ public sealed class SearchRolesQueryHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<SearchRolesQuery, PagedResult<RoleDto>>
 {
+    /// <summary>
+    /// 执行角色分页查询。
+    /// </summary>
+    /// <param name="request">查询参数。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>分页结果。</returns>
     public async Task<PagedResult<RoleDto>> Handle(SearchRolesQuery request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文并查询角色

src/Application/TakeoutSaaS.Application/Identity/Handlers/UpdatePermissionCommandHandler.cs

@@ -14,6 +14,12 @@ public sealed class UpdatePermissionCommandHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<UpdatePermissionCommand, PermissionDto?>
 {
+    /// <summary>
+    /// 执行权限更新。
+    /// </summary>
+    /// <param name="request">更新命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>更新后的权限 DTO 或 null。</returns>
     public async Task<PermissionDto?> Handle(UpdatePermissionCommand request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文并查询权限

src/Application/TakeoutSaaS.Application/Identity/Handlers/UpdateRoleCommandHandler.cs

@@ -14,6 +14,12 @@ public sealed class UpdateRoleCommandHandler(
     ITenantProvider tenantProvider)
     : IRequestHandler<UpdateRoleCommand, RoleDto?>
 {
+    /// <summary>
+    /// 执行角色更新。
+    /// </summary>
+    /// <param name="request">更新命令。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>更新后的角色 DTO 或 null。</returns>
     public async Task<RoleDto?> Handle(UpdateRoleCommand request, CancellationToken cancellationToken)
     {
         // 1. 获取租户上下文并查询角色