Merge branch 'chore/comment-fix' into dev

src/Api/TakeoutSaaS.MiniApi/Controllers/AuthController.cs

@@ -10,38 +10,46 @@ namespace TakeoutSaaS.MiniApi.Controllers;
 /// <summary>
 /// 小程序登录认证
 /// </summary>
-/// <remarks>
-/// 小程序登录认证
-/// </remarks>
-/// <param name="authService"></param>
+/// <remarks>提供小程序端的微信登录与 Token 刷新能力。</remarks>
+/// <param name="authService">小程序认证服务</param>
 [ApiVersion("1.0")]
 [Authorize]
 [Route("api/mini/v{version:apiVersion}/auth")]
 public sealed class AuthController(IMiniAuthService authService) : BaseApiController
 {
-
-
     /// <summary>
     /// 微信登录
     /// </summary>
+    /// <param name="request">微信登录请求。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>包含访问令牌与刷新令牌的响应。</returns>
     [HttpPost("wechat/login")]
     [AllowAnonymous]
     [ProducesResponseType(typeof(ApiResponse<TokenResponse>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<TokenResponse>> LoginWithWeChat([FromBody] WeChatLoginRequest request, CancellationToken cancellationToken)
     {
+        // 1. 调用认证服务完成微信登录
         var response = await authService.LoginWithWeChatAsync(request, cancellationToken);
+
+        // 2. 返回访问与刷新令牌
         return ApiResponse<TokenResponse>.Ok(response);
     }
 
     /// <summary>
     /// 刷新 Token
     /// </summary>
+    /// <param name="request">刷新令牌请求。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>新的访问令牌与刷新令牌。</returns>
     [HttpPost("refresh")]
     [AllowAnonymous]
     [ProducesResponseType(typeof(ApiResponse<TokenResponse>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<TokenResponse>> RefreshToken([FromBody] RefreshTokenRequest request, CancellationToken cancellationToken)
     {
+        // 1. 调用认证服务刷新 Token
         var response = await authService.RefreshTokenAsync(request, cancellationToken);
+
+        // 2. 返回新的令牌
         return ApiResponse<TokenResponse>.Ok(response);
     }
 }

src/Api/TakeoutSaaS.MiniApi/Controllers/FilesController.cs

@@ -1,6 +1,4 @@
-using System.Linq;
 using Microsoft.AspNetCore.Authorization;
-using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using TakeoutSaaS.Application.Storage.Abstractions;
 using TakeoutSaaS.Application.Storage.Contracts;
@@ -19,34 +17,41 @@ namespace TakeoutSaaS.MiniApi.Controllers;
 [Route("api/mini/v{version:apiVersion}/files")]
 public sealed class FilesController(IFileStorageService fileStorageService) : BaseApiController
 {
-    private readonly IFileStorageService _fileStorageService = fileStorageService;
-
     /// <summary>
     /// 上传图片或文件。
     /// </summary>
+    /// <param name="file">上传文件。</param>
+    /// <param name="type">上传类型。</param>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>上传结果，包含访问链接等信息。</returns>
     [HttpPost("upload")]
     [RequestFormLimits(MultipartBodyLengthLimit = 30 * 1024 * 1024)]
     [ProducesResponseType(typeof(ApiResponse<FileUploadResponse>), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ApiResponse<FileUploadResponse>), StatusCodes.Status400BadRequest)]
     public async Task<ApiResponse<FileUploadResponse>> Upload([FromForm] IFormFile? file, [FromForm] string? type, CancellationToken cancellationToken)
     {
+        // 1. 校验文件有效性
         if (file == null || file.Length == 0)
         {
             return ApiResponse<FileUploadResponse>.Error(ErrorCodes.BadRequest, "文件不能为空");
         }
 
+        // 2. 解析上传类型
         if (!UploadFileTypeParser.TryParse(type, out var uploadType))
         {
             return ApiResponse<FileUploadResponse>.Error(ErrorCodes.BadRequest, "上传类型不合法");
         }
 
+        // 3. 提取请求来源
         var origin = Request.Headers["Origin"].FirstOrDefault() ?? Request.Headers["Referer"].FirstOrDefault();
         await using var stream = file.OpenReadStream();
 
-        var result = await _fileStorageService.UploadAsync(
+        // 4. 调用存储服务执行上传
+        var result = await fileStorageService.UploadAsync(
             new UploadFileRequest(uploadType, stream, file.FileName, file.ContentType ?? string.Empty, file.Length, origin),
             cancellationToken);
 
+        // 5. 返回上传结果
         return ApiResponse<FileUploadResponse>.Ok(result);
     }
 }

src/Api/TakeoutSaaS.MiniApi/Controllers/HealthController.cs

@@ -1,6 +1,4 @@
-using System;
 using Microsoft.AspNetCore.Authorization;
-using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using TakeoutSaaS.Shared.Abstractions.Results;
 using TakeoutSaaS.Shared.Web.Api;
@@ -23,7 +21,10 @@ public class HealthController : BaseApiController
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status200OK)]
     public ApiResponse<object> Get()
     {
+        // 1. 构造健康状态
         var payload = new { status = "OK", service = "MiniApi", time = DateTime.UtcNow };
+
+        // 2. 返回健康响应
         return ApiResponse<object>.Ok(payload);
     }
 }

src/Api/TakeoutSaaS.MiniApi/Controllers/MeController.cs

@@ -1,8 +1,4 @@
-using System;
-using System.Threading;
-using System.Threading.Tasks;
 using Microsoft.AspNetCore.Authorization;
-using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using TakeoutSaaS.Application.Identity.Abstractions;
 using TakeoutSaaS.Application.Identity.Contracts;
@@ -16,31 +12,31 @@ namespace TakeoutSaaS.MiniApi.Controllers;
 /// <summary>
 /// 当前用户信息
 /// </summary>
-/// <remarks>
-/// 
-/// </remarks>
-/// <param name="authService"></param>
+/// <remarks>提供小程序端当前用户档案查询。</remarks>
+/// <param name="authService">小程序认证服务</param>
 [ApiVersion("1.0")]
 [Authorize]
 [Route("api/mini/v{version:apiVersion}/me")]
 public sealed class MeController(IMiniAuthService authService) : BaseApiController
 {
-
-
     /// <summary>
     /// 获取用户档案
     /// </summary>
+    /// <param name="cancellationToken">取消标记。</param>
+    /// <returns>当前用户档案信息。</returns>
     [HttpGet]
     [ProducesResponseType(typeof(ApiResponse<CurrentUserProfile>), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ApiResponse<CurrentUserProfile>), StatusCodes.Status401Unauthorized)]
     public async Task<ApiResponse<CurrentUserProfile>> Get(CancellationToken cancellationToken)
     {
+        // 1. 从 JWT 中解析用户标识
         var userId = User.GetUserId();
         if (userId == 0)
         {
             return ApiResponse<CurrentUserProfile>.Error(ErrorCodes.Unauthorized, "Token 缺少有效的用户标识");
         }
 
+        // 2. 查询用户档案并返回
         var profile = await authService.GetProfileAsync(userId, cancellationToken);
         return ApiResponse<CurrentUserProfile>.Ok(profile);
     }