refactor:规范代码格式和注释

src/Hua.Todo.Application/Data/TodoDbContext.cs

@@ -3,14 +3,28 @@ using Hua.Todo.Core.Entities;
 
 namespace Hua.Todo.Application.Data;
 
+/// <summary>
+/// 应用程序数据库上下文（EF Core）。
+/// </summary>
 public class TodoDbContext : DbContext
 {
+    /// <summary>
+    /// 创建 <see cref="TodoDbContext"/>。
+    /// </summary>
+    /// <param name="options">数据库上下文配置。</param>
     public TodoDbContext(DbContextOptions<TodoDbContext> options) : base(options)
     {
     }
 
+    /// <summary>
+    /// 任务集合。
+    /// </summary>
     public DbSet<TaskEntity> Tasks { get; set; }
 
+    /// <summary>
+    /// 配置实体模型映射。
+    /// </summary>
+    /// <param name="modelBuilder">模型构建器。</param>
     protected override void OnModelCreating(ModelBuilder modelBuilder)
     {
         base.OnModelCreating(modelBuilder);

src/Hua.Todo.Application/DynamicApi/DynamicApiExtensions.cs

@@ -2,8 +2,16 @@ using Microsoft.AspNetCore.Builder;
 
 namespace Hua.Todo.Application.DynamicApi;
 
+/// <summary>
+/// Dynamic API 中间件扩展方法。
+/// </summary>
 public static class DynamicApiExtensions
 {
+    /// <summary>
+    /// 注册 Dynamic API 中间件。
+    /// </summary>
+    /// <param name="builder">应用构建器。</param>
+    /// <returns>应用构建器。</returns>
     public static IApplicationBuilder UseDynamicApi(this IApplicationBuilder builder)
     {
         return builder.UseMiddleware<DynamicApiMiddleware>();

src/Hua.Todo.Application/DynamicApi/DynamicApiMiddleware.cs

@@ -6,6 +6,10 @@ using Hua.Todo.Application.Interfaces;
 
 namespace Hua.Todo.Application.DynamicApi;
 
+/// <summary>
+/// Dynamic API 中间件。
+/// 根据路由约定将 <see cref="IDynamicApiService"/> 的接口方法映射为 HTTP API（/api/{service}/...）。
+/// </summary>
 public class DynamicApiMiddleware
 {
     private readonly RequestDelegate _next;
@@ -44,12 +48,21 @@ public class DynamicApiMiddleware
         }
     }
 
+    /// <summary>
+    /// 创建 <see cref="DynamicApiMiddleware"/>。
+    /// </summary>
+    /// <param name="next">管道中的下一个中间件。</param>
+    /// <param name="serviceProvider">应用根服务容器。</param>
     public DynamicApiMiddleware(RequestDelegate next, IServiceProvider serviceProvider)
     {
         _next = next;
         _serviceProvider = serviceProvider;
     }
 
+    /// <summary>
+    /// 处理当前请求并尝试进行 Dynamic API 分发。
+    /// </summary>
+    /// <param name="context">HTTP 上下文。</param>
     public async Task InvokeAsync(HttpContext context)
     {
         var path = context.Request.Path.Value ?? string.Empty;

src/Hua.Todo.Application/DynamicApi/HttpAttributes.cs

@@ -1,14 +1,27 @@
 namespace Hua.Todo.Application.DynamicApi;
 
 [AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
+/// <summary>
+/// 标记方法为 HTTP GET。
+/// </summary>
 public class HttpGetAttribute : Attribute
 {
+    /// <summary>
+    /// 可选路由模板。
+    /// </summary>
     public string? Route { get; set; }
 
+    /// <summary>
+    /// 创建 <see cref="HttpGetAttribute"/>。
+    /// </summary>
     public HttpGetAttribute()
     {
     }
 
+    /// <summary>
+    /// 创建 <see cref="HttpGetAttribute"/>。
+    /// </summary>
+    /// <param name="route">路由模板。</param>
     public HttpGetAttribute(string route)
     {
         Route = route;
@@ -16,14 +29,27 @@ public class HttpGetAttribute : Attribute
 }
 
 [AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
+/// <summary>
+/// 标记方法为 HTTP POST。
+/// </summary>
 public class HttpPostAttribute : Attribute
 {
+    /// <summary>
+    /// 可选路由模板。
+    /// </summary>
     public string? Route { get; set; }
 
+    /// <summary>
+    /// 创建 <see cref="HttpPostAttribute"/>。
+    /// </summary>
     public HttpPostAttribute()
     {
     }
 
+    /// <summary>
+    /// 创建 <see cref="HttpPostAttribute"/>。
+    /// </summary>
+    /// <param name="route">路由模板。</param>
     public HttpPostAttribute(string route)
     {
         Route = route;
@@ -31,14 +57,27 @@ public class HttpPostAttribute : Attribute
 }
 
 [AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
+/// <summary>
+/// 标记方法为 HTTP PUT。
+/// </summary>
 public class HttpPutAttribute : Attribute
 {
+    /// <summary>
+    /// 可选路由模板。
+    /// </summary>
     public string? Route { get; set; }
 
+    /// <summary>
+    /// 创建 <see cref="HttpPutAttribute"/>。
+    /// </summary>
     public HttpPutAttribute()
     {
     }
 
+    /// <summary>
+    /// 创建 <see cref="HttpPutAttribute"/>。
+    /// </summary>
+    /// <param name="route">路由模板。</param>
     public HttpPutAttribute(string route)
     {
         Route = route;
@@ -46,14 +85,27 @@ public class HttpPutAttribute : Attribute
 }
 
 [AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
+/// <summary>
+/// 标记方法为 HTTP DELETE。
+/// </summary>
 public class HttpDeleteAttribute : Attribute
 {
+    /// <summary>
+    /// 可选路由模板。
+    /// </summary>
     public string? Route { get; set; }
 
+    /// <summary>
+    /// 创建 <see cref="HttpDeleteAttribute"/>。
+    /// </summary>
     public HttpDeleteAttribute()
     {
     }
 
+    /// <summary>
+    /// 创建 <see cref="HttpDeleteAttribute"/>。
+    /// </summary>
+    /// <param name="route">路由模板。</param>
     public HttpDeleteAttribute(string route)
     {
         Route = route;
@@ -61,14 +113,27 @@ public class HttpDeleteAttribute : Attribute
 }
 
 [AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
+/// <summary>
+/// 标记方法为 HTTP PATCH。
+/// </summary>
 public class HttpPatchAttribute : Attribute
 {
+    /// <summary>
+    /// 可选路由模板。
+    /// </summary>
     public string? Route { get; set; }
 
+    /// <summary>
+    /// 创建 <see cref="HttpPatchAttribute"/>。
+    /// </summary>
     public HttpPatchAttribute()
     {
     }
 
+    /// <summary>
+    /// 创建 <see cref="HttpPatchAttribute"/>。
+    /// </summary>
+    /// <param name="route">路由模板。</param>
     public HttpPatchAttribute(string route)
     {
         Route = route;

src/Hua.Todo.Application/DynamicApi/ParameterBindingAttributes.cs

@@ -1,11 +1,17 @@
 namespace Hua.Todo.Application.DynamicApi;
 
 [AttributeUsage(AttributeTargets.Parameter, AllowMultiple = false)]
+/// <summary>
+/// 指示参数从 QueryString 绑定。
+/// </summary>
 public class FromQueryAttribute : Attribute
 {
 }
 
 [AttributeUsage(AttributeTargets.Parameter, AllowMultiple = false)]
+/// <summary>
+/// 指示参数从 Request Body 绑定。
+/// </summary>
 public class FromBodyAttribute : Attribute
 {
 }

src/Hua.Todo.Application/DynamicApi/RemoteServiceAttribute.cs

@@ -1,8 +1,17 @@
 namespace Hua.Todo.Application.DynamicApi;
 
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface | AttributeTargets.Method, AllowMultiple = false)]
+/// <summary>
+/// 标记服务/方法是否允许通过 Dynamic API 暴露。
+/// </summary>
 public class RemoteServiceAttribute : Attribute
 {
+    /// <summary>
+    /// 是否启用远程访问。
+    /// </summary>
     public bool IsEnabled { get; set; } = true;
+    /// <summary>
+    /// 是否启用元数据输出。
+    /// </summary>
     public bool IsMetadataEnabled { get; set; } = true;
 }

src/Hua.Todo.Application/Interfaces/IDynamicApiService.cs

@@ -1,5 +1,9 @@
 namespace Hua.Todo.Application.Interfaces;
 
+/// <summary>
+/// Dynamic API 服务标记接口。
+/// 实现该接口的服务会被 Dynamic API 中间件发现并按约定暴露为 HTTP API。
+/// </summary>
 public interface IDynamicApiService
 {
 }

src/Hua.Todo.Application/Interfaces/ITaskService.cs

@@ -2,15 +2,67 @@ using Hua.Todo.Application.Models;
 
 namespace Hua.Todo.Application.Interfaces;
 
+/// <summary>
+/// 任务管理服务接口
+/// </summary>
 public interface ITaskService : IDynamicApiService
 {
+    /// <summary>
+    /// 获取所有任务
+    /// </summary>
+    /// <returns>包含所有任务的列表</returns>
     Task<List<TaskDto>> GetAllTasksAsync();
+
+    /// <summary>
+    /// 根据 ID 获取任务
+    /// </summary>
+    /// <param name="id">任务唯一标识符</param>
+    /// <returns>匹配的任务 DTO，如果未找到则返回 null</returns>
     Task<TaskDto?> GetTaskByIdAsync(int id);
+
+    /// <summary>
+    /// 获取未完成的任务
+    /// </summary>
+    /// <returns>未完成任务的列表</returns>
     Task<List<TaskDto>> GetActiveTasksAsync();
+
+    /// <summary>
+    /// 获取已完成的任务
+    /// </summary>
+    /// <returns>已完成任务的列表</returns>
     Task<List<TaskDto>> GetCompletedTasksAsync();
+
+    /// <summary>
+    /// 创建新任务
+    /// </summary>
+    /// <param name="dto">创建任务所需的数据传输对象</param>
+    /// <returns>创建成功的任务 DTO</returns>
     Task<TaskDto> CreateTaskAsync(CreateTaskDto dto);
+
+    /// <summary>
+    /// 更新任务信息
+    /// </summary>
+    /// <param name="dto">包含更新信息的任务数据传输对象</param>
+    /// <returns>更新后的任务 DTO</returns>
     Task<TaskDto> UpdateTaskAsync(UpdateTaskDto dto);
+
+    /// <summary>
+    /// 切换任务完成状态
+    /// </summary>
+    /// <param name="id">任务唯一标识符</param>
+    /// <returns>更新状态后的任务 DTO</returns>
     Task<TaskDto> ToggleCompleteAsync(int id);
+
+    /// <summary>
+    /// 删除任务
+    /// </summary>
+    /// <param name="id">要删除的任务唯一标识符</param>
     Task DeleteTaskAsync(int id);
+
+    /// <summary>
+    /// 获取子任务列表
+    /// </summary>
+    /// <param name="parentTaskId">父任务唯一标识符</param>
+    /// <returns>该父任务下的所有子任务列表</returns>
     Task<List<TaskDto>> GetSubTasksAsync(int parentTaskId);
 }

src/Hua.Todo.Application/Models/TaskModels.cs

@@ -3,45 +3,112 @@ using System.Text.Json.Serialization;
 
 namespace Hua.Todo.Application.Models;
 
+/// <summary>
+/// 创建任务请求 DTO。
+/// </summary>
 public class CreateTaskDto
 {
+    /// <summary>
+    /// 任务标题。
+    /// </summary>
     public string Title { get; set; } = string.Empty;
 
     [JsonConverter(typeof(JsonStringEnumConverter))]
+    /// <summary>
+    /// 任务优先级。
+    /// </summary>
     public TaskPriority Priority { get; set; } = TaskPriority.Medium;
 
+    /// <summary>
+    /// 父任务 ID（用于创建子任务）。
+    /// </summary>
     public int? ParentTaskId { get; set; }
 }
 
+/// <summary>
+/// 更新任务请求 DTO。
+/// </summary>
 public class UpdateTaskDto
 {
+    /// <summary>
+    /// 任务 ID。
+    /// </summary>
     public int Id { get; set; }
 
+    /// <summary>
+    /// 新标题（可选）。
+    /// </summary>
     public string? Title { get; set; }
 
     [JsonConverter(typeof(JsonStringEnumConverter))]
+    /// <summary>
+    /// 新优先级（可选）。
+    /// </summary>
     public TaskPriority? Priority { get; set; }
 }
 
+/// <summary>
+/// 任务返回 DTO。
+/// </summary>
 public class TaskDto
 {
+    /// <summary>
+    /// 任务 ID。
+    /// </summary>
     public int Id { get; set; }
+    /// <summary>
+    /// 任务标题。
+    /// </summary>
     public string Title { get; set; } = string.Empty;
 
     [JsonConverter(typeof(JsonStringEnumConverter))]
+    /// <summary>
+    /// 任务优先级。
+    /// </summary>
     public TaskPriority Priority { get; set; }
 
+    /// <summary>
+    /// 是否已完成。
+    /// </summary>
     public bool IsCompleted { get; set; }
+    /// <summary>
+    /// 创建时间（UTC）。
+    /// </summary>
     public DateTime CreatedAt { get; set; }
+    /// <summary>
+    /// 更新时间（UTC）。
+    /// </summary>
     public DateTime UpdatedAt { get; set; }
+    /// <summary>
+    /// 父任务 ID（可选）。
+    /// </summary>
     public int? ParentTaskId { get; set; }
+    /// <summary>
+    /// 子任务列表。
+    /// </summary>
     public List<TaskDto> SubTasks { get; set; } = new();
 }
 
+/// <summary>
+/// 通用 API 响应包装。
+/// </summary>
+/// <typeparam name="T">数据类型。</typeparam>
 public class ApiResponse<T>
 {
+    /// <summary>
+    /// 是否成功。
+    /// </summary>
     public bool Success { get; set; }
+    /// <summary>
+    /// 返回数据（可选）。
+    /// </summary>
     public T? Data { get; set; }
+    /// <summary>
+    /// 提示信息。
+    /// </summary>
     public string Message { get; set; } = string.Empty;
+    /// <summary>
+    /// 错误列表。
+    /// </summary>
     public List<string> Errors { get; set; } = new();
 }

src/Hua.Todo.Application/Repositories/TaskRepository.cs

@@ -5,15 +5,26 @@ using Hua.Todo.Core.Interfaces;
 
 namespace Hua.Todo.Application.Repositories;
 
+/// <summary>
+/// 任务仓储实现（EF Core）。
+/// </summary>
 public class TaskRepository : ITaskRepository
 {
     private readonly TodoDbContext _context;
 
+    /// <summary>
+    /// 创建 <see cref="TaskRepository"/>。
+    /// </summary>
+    /// <param name="context">数据库上下文。</param>
     public TaskRepository(TodoDbContext context)
     {
         _context = context;
     }
 
+    /// <summary>
+    /// 获取所有任务。
+    /// </summary>
+    /// <returns>包含所有任务实体的列表。</returns>
     public async Task<List<TaskEntity>> GetAllAsync()
     {
         return await _context.Tasks
@@ -21,6 +32,11 @@ public class TaskRepository : ITaskRepository
             .ToListAsync();
     }
 
+    /// <summary>
+    /// 根据 ID 获取任务。
+    /// </summary>
+    /// <param name="id">任务 ID。</param>
+    /// <returns>匹配的任务实体；如果不存在则返回 null。</returns>
     public async Task<TaskEntity?> GetByIdAsync(int id)
     {
         return await _context.Tasks
@@ -28,6 +44,10 @@ public class TaskRepository : ITaskRepository
             .FirstOrDefaultAsync(t => t.Id == id);
     }
 
+    /// <summary>
+    /// 获取未完成任务列表。
+    /// </summary>
+    /// <returns>未完成的任务实体列表。</returns>
     public async Task<List<TaskEntity>> GetActiveTasksAsync()
     {
         return await _context.Tasks
@@ -36,6 +56,10 @@ public class TaskRepository : ITaskRepository
             .ToListAsync();
     }
 
+    /// <summary>
+    /// 获取已完成任务列表。
+    /// </summary>
+    /// <returns>已完成的任务实体列表。</returns>
     public async Task<List<TaskEntity>> GetCompletedTasksAsync()
     {
         return await _context.Tasks
@@ -44,6 +68,11 @@ public class TaskRepository : ITaskRepository
             .ToListAsync();
     }
 
+    /// <summary>
+    /// 新增一个任务。
+    /// </summary>
+    /// <param name="taskEntity">要添加的任务实体。</param>
+    /// <returns>已持久化的任务实体（包含生成的 ID）。</returns>
     public async Task<TaskEntity> AddAsync(TaskEntity taskEntity)
     {
         _context.Tasks.Add(taskEntity);
@@ -51,6 +80,11 @@ public class TaskRepository : ITaskRepository
         return taskEntity;
     }
 
+    /// <summary>
+    /// 更新现有任务信息。
+    /// </summary>
+    /// <param name="taskEntity">要更新的任务实体。</param>
+    /// <returns>更新后的任务实体。</returns>
     public async Task<TaskEntity> UpdateAsync(TaskEntity taskEntity)
     {
         taskEntity.UpdatedAt = DateTime.UtcNow;
@@ -59,6 +93,11 @@ public class TaskRepository : ITaskRepository
         return taskEntity;
     }
 
+    /// <summary>
+    /// 根据 ID 删除任务。
+    /// </summary>
+    /// <param name="id">要删除的任务 ID。</param>
+    /// <returns>表示删除操作的任务。</returns>
     public async Task DeleteAsync(int id)
     {
         var task = await _context.Tasks.FindAsync(id);
@@ -69,6 +108,11 @@ public class TaskRepository : ITaskRepository
         }
     }
 
+    /// <summary>
+    /// 获取指定父任务的子任务列表。
+    /// </summary>
+    /// <param name="parentTaskId">父任务 ID。</param>
+    /// <returns>子任务实体的列表。</returns>
     public async Task<List<TaskEntity>> GetSubTasksAsync(int parentTaskId)
     {
         return await _context.Tasks

src/Hua.Todo.Application/ServiceCollectionExtensions.cs

@@ -9,8 +9,17 @@ using ITaskService = Hua.Todo.Application.Interfaces.ITaskService;
 
 namespace Hua.Todo.Application;
 
+/// <summary>
+/// 应用层依赖注入扩展。
+/// </summary>
 public static class ServiceCollectionExtensions
 {
+    /// <summary>
+    /// 注册应用层服务与 EF Core DbContext。
+    /// </summary>
+    /// <param name="services">服务集合。</param>
+    /// <param name="connectionString">数据库连接字符串。</param>
+    /// <returns>服务集合。</returns>
     public static IServiceCollection AddApplicationServices(this IServiceCollection services, string connectionString)
     {
         services.AddDbContext<TodoDbContext>(options => 

src/Hua.Todo.Application/Services/TaskService.cs

@@ -5,39 +5,68 @@ using Hua.Todo.Core.Interfaces;
 
 namespace Hua.Todo.Application.Services;
 
+/// <summary>
+/// 任务管理服务实现
+/// </summary>
 public class TaskService : ITaskService
 {
     private readonly ITaskRepository _taskRepository;
 
+    /// <summary>
+    /// 初始化任务管理服务的新实例
+    /// </summary>
+    /// <param name="taskRepository">任务仓储接口</param>
     public TaskService(ITaskRepository taskRepository)
     {
         _taskRepository = taskRepository;
     }
 
+    /// <summary>
+    /// 获取所有任务
+    /// </summary>
+    /// <returns>所有任务的 DTO 列表</returns>
     public async Task<List<TaskDto>> GetAllTasksAsync()
     {
         var tasks = await _taskRepository.GetAllAsync();
         return tasks.Select(MapToDto).ToList();
     }
 
+    /// <summary>
+    /// 根据 ID 获取任务详情
+    /// </summary>
+    /// <param name="id">任务 ID</param>
+    /// <returns>找到的任务 DTO，如果不存在则返回 null</returns>
     public async Task<TaskDto?> GetTaskByIdAsync(int id)
     {
         var task = await _taskRepository.GetByIdAsync(id);
         return task != null ? MapToDto(task) : null;
     }
 
+    /// <summary>
+    /// 获取所有未完成的任务
+    /// </summary>
+    /// <returns>未完成任务的 DTO 列表</returns>
     public async Task<List<TaskDto>> GetActiveTasksAsync()
     {
         var allTasks = await _taskRepository.GetAllAsync();
         return allTasks.Where(t => !t.IsCompleted).Select(MapToDto).ToList();
     }
 
+    /// <summary>
+    /// 获取所有已完成的任务
+    /// </summary>
+    /// <returns>已完成任务的 DTO 列表</returns>
     public async Task<List<TaskDto>> GetCompletedTasksAsync()
     {
         var allTasks = await _taskRepository.GetAllAsync();
         return allTasks.Where(t => t.IsCompleted).Select(MapToDto).ToList();
     }
 
+    /// <summary>
+    /// 创建新任务
+    /// </summary>
+    /// <param name="dto">任务创建 DTO</param>
+    /// <returns>新创建的任务 DTO</returns>
     public async Task<TaskDto> CreateTaskAsync(CreateTaskDto dto)
     {
         var task = new TaskEntity
@@ -54,6 +83,12 @@ public class TaskService : ITaskService
         return MapToDto(createdTask);
     }
 
+    /// <summary>
+    /// 更新现有任务
+    /// </summary>
+    /// <param name="dto">包含更新内容的 DTO</param>
+    /// <returns>更新后的任务 DTO</returns>
+    /// <exception cref="KeyNotFoundException">当任务 ID 不存在时抛出</exception>
     public async Task<TaskDto> UpdateTaskAsync(UpdateTaskDto dto)
     {
         var task = await _taskRepository.GetByIdAsync(dto.Id);
@@ -78,6 +113,12 @@ public class TaskService : ITaskService
         return MapToDto(updatedTask);
     }
 
+    /// <summary>
+    /// 切换任务的完成状态
+    /// </summary>
+    /// <param name="id">任务 ID</param>
+    /// <returns>状态切换后的任务 DTO</returns>
+    /// <exception cref="KeyNotFoundException">当任务 ID 不存在时抛出</exception>
     public async Task<TaskDto> ToggleCompleteAsync(int id)
     {
         var task = await _taskRepository.GetByIdAsync(id);
@@ -93,6 +134,11 @@ public class TaskService : ITaskService
         return MapToDto(updatedTask);
     }
 
+    /// <summary>
+    /// 删除指定 ID 的任务
+    /// </summary>
+    /// <param name="id">任务 ID</param>
+    /// <exception cref="KeyNotFoundException">当任务 ID 不存在时抛出</exception>
     public async Task DeleteTaskAsync(int id)
     {
         var task = await _taskRepository.GetByIdAsync(id);
@@ -104,12 +150,20 @@ public class TaskService : ITaskService
         await _taskRepository.DeleteAsync(id);
     }
 
+    /// <summary>
+    /// 获取指定父任务的所有子任务
+    /// </summary>
+    /// <param name="parentTaskId">父任务 ID</param>
+    /// <returns>子任务的 DTO 列表</returns>
     public async Task<List<TaskDto>> GetSubTasksAsync(int parentTaskId)
     {
         var allTasks = await _taskRepository.GetAllAsync();
         return allTasks.Where(t => t.ParentTaskId == parentTaskId).Select(MapToDto).ToList();
     }
 
+    /// <summary>
+    /// 实体转 DTO 映射方法
+    /// </summary>
     private TaskDto MapToDto(TaskEntity task)
     {
         return new TaskDto