chore: 优化代码注释

src/Application/TakeoutSaaS.Application/Identity/Services/AdminAuthService.cs

@@ -1,6 +1,3 @@
-using System;
-using System.Threading;
-using System.Threading.Tasks;
 using Microsoft.AspNetCore.Identity;
 using TakeoutSaaS.Application.Identity.Abstractions;
 using TakeoutSaaS.Application.Identity.Contracts;
@@ -14,59 +11,75 @@ namespace TakeoutSaaS.Application.Identity.Services;
 /// <summary>
 /// 管理后台认证服务实现。
 /// </summary>
-public sealed class AdminAuthService : IAdminAuthService
+public sealed class AdminAuthService(
+    IIdentityUserRepository userRepository,
+    IPasswordHasher<IdentityUser> passwordHasher,
+    IJwtTokenService jwtTokenService,
+    IRefreshTokenStore refreshTokenStore) : IAdminAuthService
 {
-    private readonly IIdentityUserRepository _userRepository;
-    private readonly IPasswordHasher<IdentityUser> _passwordHasher;
-    private readonly IJwtTokenService _jwtTokenService;
-    private readonly IRefreshTokenStore _refreshTokenStore;
-
-    public AdminAuthService(
-        IIdentityUserRepository userRepository,
-        IPasswordHasher<IdentityUser> passwordHasher,
-        IJwtTokenService jwtTokenService,
-        IRefreshTokenStore refreshTokenStore)
-    {
-        _userRepository = userRepository;
-        _passwordHasher = passwordHasher;
-        _jwtTokenService = jwtTokenService;
-        _refreshTokenStore = refreshTokenStore;
-    }
-
+    /// <summary>
+    /// 管理后台登录：验证账号密码并生成令牌。
+    /// </summary>
+    /// <param name="request">登录请求</param>
+    /// <param name="cancellationToken">取消令牌</param>
+    /// <returns>令牌响应</returns>
+    /// <exception cref="BusinessException">账号或密码错误时抛出</exception>
     public async Task<TokenResponse> LoginAsync(AdminLoginRequest request, CancellationToken cancellationToken = default)
     {
-        var user = await _userRepository.FindByAccountAsync(request.Account, cancellationToken)
+        // 1. 根据账号查找用户
+        var user = await userRepository.FindByAccountAsync(request.Account, cancellationToken)
                    ?? throw new BusinessException(ErrorCodes.Unauthorized, "账号或密码错误");
 
-        var result = _passwordHasher.VerifyHashedPassword(user, user.PasswordHash, request.Password);
+        // 2. 验证密码（使用 ASP.NET Core Identity 的密码哈希器）
+        var result = passwordHasher.VerifyHashedPassword(user, user.PasswordHash, request.Password);
         if (result == PasswordVerificationResult.Failed)
         {
             throw new BusinessException(ErrorCodes.Unauthorized, "账号或密码错误");
         }
 
+        // 3. 构建用户档案并生成令牌
         var profile = BuildProfile(user);
-        return await _jwtTokenService.CreateTokensAsync(profile, false, cancellationToken);
+        return await jwtTokenService.CreateTokensAsync(profile, false, cancellationToken);
     }
 
+    /// <summary>
+    /// 刷新访问令牌：使用刷新令牌获取新的访问令牌和刷新令牌。
+    /// </summary>
+    /// <param name="request">刷新令牌请求</param>
+    /// <param name="cancellationToken">取消令牌</param>
+    /// <returns>新的令牌响应</returns>
+    /// <exception cref="BusinessException">刷新令牌无效、已过期或用户不存在时抛出</exception>
     public async Task<TokenResponse> RefreshTokenAsync(RefreshTokenRequest request, CancellationToken cancellationToken = default)
     {
-        var descriptor = await _refreshTokenStore.GetAsync(request.RefreshToken, cancellationToken);
+        // 1. 验证刷新令牌（检查是否存在、是否过期、是否已撤销）
+        var descriptor = await refreshTokenStore.GetAsync(request.RefreshToken, cancellationToken);
         if (descriptor == null || descriptor.ExpiresAt <= DateTime.UtcNow || descriptor.Revoked)
         {
             throw new BusinessException(ErrorCodes.Unauthorized, "RefreshToken 无效或已过期");
         }
 
-        var user = await _userRepository.FindByIdAsync(descriptor.UserId, cancellationToken)
+        // 2. 根据用户 ID 查找用户
+        var user = await userRepository.FindByIdAsync(descriptor.UserId, cancellationToken)
                    ?? throw new BusinessException(ErrorCodes.Unauthorized, "用户不存在");
 
-        await _refreshTokenStore.RevokeAsync(descriptor.Token, cancellationToken);
+        // 3. 撤销旧刷新令牌（防止重复使用）
+        await refreshTokenStore.RevokeAsync(descriptor.Token, cancellationToken);
+        
+        // 4. 生成新的令牌对
         var profile = BuildProfile(user);
-        return await _jwtTokenService.CreateTokensAsync(profile, false, cancellationToken);
+        return await jwtTokenService.CreateTokensAsync(profile, false, cancellationToken);
     }
 
+    /// <summary>
+    /// 获取用户档案。
+    /// </summary>
+    /// <param name="userId">用户 ID</param>
+    /// <param name="cancellationToken">取消令牌</param>
+    /// <returns>用户档案</returns>
+    /// <exception cref="BusinessException">用户不存在时抛出</exception>
     public async Task<CurrentUserProfile> GetProfileAsync(Guid userId, CancellationToken cancellationToken = default)
     {
-        var user = await _userRepository.FindByIdAsync(userId, cancellationToken)
+        var user = await userRepository.FindByIdAsync(userId, cancellationToken)
                    ?? throw new BusinessException(ErrorCodes.NotFound, "用户不存在");
 
         return BuildProfile(user);