chore: add documentation comments and stylecop rules

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

@@ -12,17 +12,12 @@ namespace TakeoutSaaS.AdminApi.Controllers;
 /// <summary>
 /// 参数字典管理。
 /// </summary>
-/// <remarks>
-/// 初始化字典控制器。
-/// </remarks>
 /// <param name="dictionaryAppService">字典服务</param>
 [ApiVersion("1.0")]
 [Authorize]
 [Route("api/admin/v{version:apiVersion}/dictionaries")]
 public sealed class DictionaryController(IDictionaryAppService dictionaryAppService) : BaseApiController
 {
-
-
     /// <summary>
     /// 查询字典分组。
     /// </summary>
@@ -31,7 +26,10 @@ public sealed class DictionaryController(IDictionaryAppService dictionaryAppServ
     [ProducesResponseType(typeof(ApiResponse<IReadOnlyList<DictionaryGroupDto>>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<IReadOnlyList<DictionaryGroupDto>>> GetGroups([FromQuery] DictionaryGroupQuery query, CancellationToken cancellationToken)
     {
+        // 1. 查询字典分组
         var groups = await dictionaryAppService.SearchGroupsAsync(query, cancellationToken);
+
+        // 2. 返回分组列表
         return ApiResponse<IReadOnlyList<DictionaryGroupDto>>.Ok(groups);
     }
 
@@ -43,7 +41,10 @@ public sealed class DictionaryController(IDictionaryAppService dictionaryAppServ
     [ProducesResponseType(typeof(ApiResponse<DictionaryGroupDto>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<DictionaryGroupDto>> CreateGroup([FromBody] CreateDictionaryGroupRequest request, CancellationToken cancellationToken)
     {
+        // 1. 创建字典分组
         var group = await dictionaryAppService.CreateGroupAsync(request, cancellationToken);
+
+        // 2. 返回创建结果
         return ApiResponse<DictionaryGroupDto>.Ok(group);
     }
 
@@ -55,7 +56,10 @@ public sealed class DictionaryController(IDictionaryAppService dictionaryAppServ
     [ProducesResponseType(typeof(ApiResponse<DictionaryGroupDto>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<DictionaryGroupDto>> UpdateGroup(long groupId, [FromBody] UpdateDictionaryGroupRequest request, CancellationToken cancellationToken)
     {
+        // 1. 更新字典分组
         var group = await dictionaryAppService.UpdateGroupAsync(groupId, request, cancellationToken);
+
+        // 2. 返回更新结果
         return ApiResponse<DictionaryGroupDto>.Ok(group);
     }
 
@@ -67,7 +71,10 @@ public sealed class DictionaryController(IDictionaryAppService dictionaryAppServ
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<object>> DeleteGroup(long groupId, CancellationToken cancellationToken)
     {
+        // 1. 删除字典分组
         await dictionaryAppService.DeleteGroupAsync(groupId, cancellationToken);
+
+        // 2. 返回成功响应
         return ApiResponse.Success();
     }
 
@@ -79,7 +86,10 @@ public sealed class DictionaryController(IDictionaryAppService dictionaryAppServ
     [ProducesResponseType(typeof(ApiResponse<DictionaryItemDto>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<DictionaryItemDto>> CreateItem(long groupId, [FromBody] CreateDictionaryItemRequest request, CancellationToken cancellationToken)
     {
+        // 1. 绑定分组标识
         request.GroupId = groupId;
+
+        // 2. 创建字典项
         var item = await dictionaryAppService.CreateItemAsync(request, cancellationToken);
         return ApiResponse<DictionaryItemDto>.Ok(item);
     }
@@ -92,7 +102,10 @@ public sealed class DictionaryController(IDictionaryAppService dictionaryAppServ
     [ProducesResponseType(typeof(ApiResponse<DictionaryItemDto>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<DictionaryItemDto>> UpdateItem(long itemId, [FromBody] UpdateDictionaryItemRequest request, CancellationToken cancellationToken)
     {
+        // 1. 更新字典项
         var item = await dictionaryAppService.UpdateItemAsync(itemId, request, cancellationToken);
+
+        // 2. 返回更新结果
         return ApiResponse<DictionaryItemDto>.Ok(item);
     }
 
@@ -104,7 +117,10 @@ public sealed class DictionaryController(IDictionaryAppService dictionaryAppServ
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<object>> DeleteItem(long itemId, CancellationToken cancellationToken)
     {
+        // 1. 删除字典项
         await dictionaryAppService.DeleteItemAsync(itemId, cancellationToken);
+
+        // 2. 返回成功响应
         return ApiResponse.Success();
     }
 
@@ -115,7 +131,10 @@ public sealed class DictionaryController(IDictionaryAppService dictionaryAppServ
     [ProducesResponseType(typeof(ApiResponse<IReadOnlyDictionary<string, IReadOnlyList<DictionaryItemDto>>>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<IReadOnlyDictionary<string, IReadOnlyList<DictionaryItemDto>>>> BatchGet([FromBody] DictionaryBatchQueryRequest request, CancellationToken cancellationToken)
     {
+        // 1. 批量读取并命中缓存
         var dictionaries = await dictionaryAppService.GetCachedItemsAsync(request, cancellationToken);
+
+        // 2. 返回批量结果
         return ApiResponse<IReadOnlyDictionary<string, IReadOnlyList<DictionaryItemDto>>>.Ok(dictionaries);
     }
 }