166 lines
6.0 KiB
Markdown
166 lines
6.0 KiB
Markdown
# Implementation Plan: Token 刷新机制 & 图形验证码
|
||
|
||
## Overview
|
||
|
||
本任务清单实现两个安全增强功能：Token 刷新机制和图形验证码。采用增量开发方式，先完成后端 API，再更新前端。
|
||
|
||
## Tasks
|
||
|
||
- [x] 1. 创建 RefreshToken 数据库实体和迁移
|
||
- [x] 1.1 创建 RefreshToken 实体类
|
||
- 在 `Entities/` 目录创建 `RefreshToken.cs`
|
||
- 包含 Id, AdminUserId, TokenHash, ExpiresAt, CreatedAt, CreatedByIp, RevokedAt, RevokedByIp, ReplacedByToken 字段
|
||
- 添加 IsExpired, IsRevoked, IsActive 计算属性
|
||
- _Requirements: 13.2_
|
||
- [x] 1.2 更新 AdminDbContext 配置
|
||
- 添加 DbSet<RefreshToken>
|
||
- 配置实体映射和索引
|
||
- _Requirements: 13.2_
|
||
- [x] 1.3 创建数据库迁移脚本
|
||
- 创建 `Data/Migrations/add_refresh_tokens.sql`
|
||
- 包含表创建和索引
|
||
- _Requirements: 13.2_
|
||
|
||
- [x] 2. 实现验证码服务
|
||
- [x] 2.1 创建验证码服务接口和实现
|
||
- 创建 `Services/ICaptchaService.cs` 接口
|
||
- 创建 `Services/CaptchaService.cs` 实现
|
||
- 使用 SkiaSharp 或 System.Drawing 生成图片
|
||
- 生成 4-6 位字母数字验证码
|
||
- 添加干扰线和噪点
|
||
- _Requirements: 14.2, 14.3_
|
||
- [x] 2.2 创建验证码请求/响应模型
|
||
- 创建 `Models/Auth/CaptchaResponse.cs`
|
||
- 包含 CaptchaKey 和 CaptchaImage (base64)
|
||
- _Requirements: 14.8_
|
||
- [x] 2.3 实现验证码缓存存储
|
||
- 使用 IMemoryCache 存储验证码
|
||
- 设置 5 分钟过期时间
|
||
- 实现验证后立即删除
|
||
- _Requirements: 14.3, 14.6_
|
||
- [x] 2.4 编写验证码服务单元测试
|
||
- 测试验证码格式（4-6位字母数字）
|
||
- 测试验证码过期机制
|
||
- 测试单次使用约束
|
||
- **Property 10: Captcha code characteristics**
|
||
- **Validates: Requirements 14.2**
|
||
|
||
- [x] 3. 扩展认证服务支持 Token 刷新
|
||
- [x] 3.1 创建 Token 刷新相关模型
|
||
- 扩展 `LoginRequest` 添加 CaptchaKey, CaptchaCode
|
||
- 扩展 `LoginResponse` 改 Token 为 AccessToken，添加 RefreshToken
|
||
- 创建 `RefreshTokenRequest.cs` 和 `RefreshTokenResponse.cs`
|
||
- _Requirements: 13.1_
|
||
- [x] 3.2 扩展 IAuthService 接口
|
||
- 添加 RefreshTokenAsync 方法
|
||
- 添加 RevokeTokenAsync 方法
|
||
- 添加 RevokeAllTokensAsync 方法
|
||
- _Requirements: 13.4, 13.6, 13.8_
|
||
- [x] 3.3 实现 RefreshToken 生成和存储
|
||
- 生成安全随机 Token
|
||
- 哈希后存储到数据库
|
||
- 设置 7 天过期时间
|
||
- _Requirements: 13.1, 13.2_
|
||
- [x] 3.4 实现 Token 刷新逻辑
|
||
- 验证 RefreshToken 有效性
|
||
- 生成新的 AccessToken
|
||
- 可选：轮换 RefreshToken
|
||
- _Requirements: 13.4, 13.5_
|
||
- [x] 3.5 实现 Token 撤销逻辑
|
||
- 单个 Token 撤销（登出）
|
||
- 用户所有 Token 撤销（强制下线）
|
||
- _Requirements: 13.6, 13.8_
|
||
- [x] 3.6 修改登录逻辑集成验证码
|
||
- 验证码校验优先于密码校验
|
||
- 验证码错误不增加登录失败次数
|
||
- 登录成功后生成双 Token
|
||
- _Requirements: 14.4, 14.5, 13.1_
|
||
- [x] 3.7 编写认证服务单元测试
|
||
- 测试验证码校验优先级
|
||
- 测试 Token 刷新逻辑
|
||
- 测试 Token 撤销逻辑
|
||
- **Property 12: Captcha validation before password check**
|
||
- **Validates: Requirements 14.4, 14.5**
|
||
- _Note: Tests written but xUnit discovery issue needs investigation_
|
||
|
||
- [x] 4. 更新 AuthController API
|
||
- [x] 4.1 添加验证码获取接口
|
||
- `POST /api/admin/auth/captcha`
|
||
- 返回 CaptchaKey 和 Base64 图片
|
||
- _Requirements: 14.8_
|
||
- [x] 4.2 添加 Token 刷新接口
|
||
- `POST /api/admin/auth/refresh`
|
||
- 接收 RefreshToken，返回新 Token
|
||
- _Requirements: 13.4_
|
||
- [x] 4.3 修改登录接口
|
||
- 接收验证码参数
|
||
- 返回双 Token
|
||
- _Requirements: 13.1, 14.4_
|
||
- [x] 4.4 修改登出接口
|
||
- 撤销 RefreshToken
|
||
- _Requirements: 13.6_
|
||
- [x] 4.5 添加强制下线接口（可选）
|
||
- `POST /api/admin/auth/revoke-all`
|
||
- 撤销用户所有 Token
|
||
- _Requirements: 13.8_
|
||
|
||
- [x] 5. Checkpoint - 后端功能验证
|
||
- 确保所有后端 API 正常工作
|
||
- 使用 Postman/Swagger 测试接口
|
||
- 确保所有测试通过，如有问题请询问用户
|
||
|
||
- [x] 6. 更新前端 Token 管理
|
||
- [x] 6.1 扩展 auth.ts 工具函数
|
||
- 添加 AccessToken/RefreshToken 分离存储
|
||
- 添加 Token 过期时间存储
|
||
- 实现 isTokenExpiringSoon() 函数
|
||
- _Requirements: 13.3_
|
||
- [x] 6.2 扩展 auth API
|
||
- 添加 getCaptcha() 接口
|
||
- 添加 refreshToken() 接口
|
||
- 更新 login() 请求/响应类型
|
||
- _Requirements: 13.1, 14.8_
|
||
- [x] 6.3 增强请求拦截器
|
||
- 实现自动 Token 刷新
|
||
- 防止并发刷新（Promise 锁）
|
||
- 401 错误时尝试刷新
|
||
- _Requirements: 13.3, 13.4_
|
||
- [x] 6.4 编写前端工具函数测试
|
||
- 测试 isTokenExpiringSoon() 边界条件
|
||
- **Property 3: Token expiration detection**
|
||
- **Validates: Requirements 13.3**
|
||
|
||
- [x] 7. 更新登录页面
|
||
- [x] 7.1 添加验证码组件
|
||
- 显示验证码图片
|
||
- 添加刷新按钮
|
||
- 绑定验证码输入框
|
||
- _Requirements: 14.1, 14.7_
|
||
- [x] 7.2 更新登录表单
|
||
- 添加验证码字段验证规则
|
||
- 登录前获取验证码
|
||
- 登录失败后刷新验证码
|
||
- _Requirements: 14.4, 14.5_
|
||
- [x] 7.3 更新 user store
|
||
- 存储双 Token
|
||
- 更新登出逻辑
|
||
- _Requirements: 13.1, 13.6_
|
||
|
||
- [x] 8. 实现账号禁用时撤销 Token
|
||
- [x] 8.1 修改 AdminUserService
|
||
- 禁用账号时调用 RevokeAllTokensAsync
|
||
- _Requirements: 13.7_
|
||
|
||
- [x] 9. Final Checkpoint - 完整功能验证
|
||
- 测试完整登录流程（验证码 → 登录 → 双Token）
|
||
- 测试 Token 自动刷新
|
||
- 测试登出和强制下线
|
||
- 确保所有测试通过，如有问题请询问用户
|
||
|
||
## Notes
|
||
|
||
- 所有任务都是必须完成的，包括测试任务
|
||
- 每个任务都引用了具体的需求条款以便追溯
|
||
- Checkpoint 任务用于阶段性验证，确保增量开发的稳定性
|
||
- 验证码图片生成推荐使用 SkiaSharp（跨平台）或 System.Drawing.Common
|