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

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))