86 lines
4.9 KiB
Markdown
86 lines
4.9 KiB
Markdown
# Requirements Document
|
||
|
||
## Introduction
|
||
|
||
为 HoneyBox 前端 API 实现双 Token 认证机制（Access Token + Refresh Token），解决 Token 过期后用户需要重新登录的问题，提升用户体验。当 Access Token 过期时，前端可以使用 Refresh Token 自动获取新的 Token，实现无感刷新。
|
||
|
||
## Glossary
|
||
|
||
- **Access_Token**: 短期有效的 JWT 令牌，用于 API 请求认证，有效期 30 分钟
|
||
- **Refresh_Token**: 长期有效的刷新令牌，用于获取新的 Access Token，有效期 7 天
|
||
- **Token_Rotation**: Token 轮换机制，每次刷新时生成新的 Refresh Token 并废弃旧的
|
||
- **Auth_Service**: 认证服务，处理登录、Token 生成和刷新逻辑
|
||
- **Request_Manager**: 前端网络请求管理器，封装统一的请求方法
|
||
- **User_Refresh_Token**: 用户刷新令牌数据库实体，存储 Refresh Token 信息
|
||
|
||
## Requirements
|
||
|
||
### Requirement 1: 登录接口返回双 Token
|
||
|
||
**User Story:** As a 用户, I want 登录成功后获取 Access Token 和 Refresh Token, so that 我可以在 Access Token 过期后使用 Refresh Token 刷新而无需重新登录。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 用户通过微信小程序登录成功, THE Auth_Service SHALL 返回包含 accessToken、refreshToken 和 expiresIn 的响应对象
|
||
2. WHEN 用户通过手机号验证码登录成功, THE Auth_Service SHALL 返回包含 accessToken、refreshToken 和 expiresIn 的响应对象
|
||
3. THE Auth_Service SHALL 生成有效期为 30 分钟的 Access_Token
|
||
4. THE Auth_Service SHALL 生成有效期为 7 天的 Refresh_Token
|
||
5. THE Auth_Service SHALL 将 Refresh_Token 的哈希值存储到 User_Refresh_Token 表中
|
||
|
||
### Requirement 2: Token 刷新接口
|
||
|
||
**User Story:** As a 用户, I want 使用 Refresh Token 获取新的 Access Token, so that 我可以在 Access Token 过期后继续使用应用而无需重新登录。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 用户携带有效的 Refresh_Token 请求刷新接口, THE Auth_Service SHALL 返回新的 accessToken、refreshToken 和 expiresIn
|
||
2. WHEN 用户携带已过期的 Refresh_Token 请求刷新接口, THE Auth_Service SHALL 返回错误信息 "刷新令牌已过期"
|
||
3. WHEN 用户携带已撤销的 Refresh_Token 请求刷新接口, THE Auth_Service SHALL 返回错误信息 "刷新令牌已失效"
|
||
4. WHEN 用户携带无效的 Refresh_Token 请求刷新接口, THE Auth_Service SHALL 返回错误信息 "无效的刷新令牌"
|
||
5. WHEN Token 刷新成功, THE Auth_Service SHALL 撤销旧的 Refresh_Token 并生成新的 Refresh_Token（Token 轮换）
|
||
6. THE Auth_Service SHALL 记录 Token 轮换的关联关系用于安全审计
|
||
|
||
### Requirement 3: 前端自动刷新机制
|
||
|
||
**User Story:** As a 用户, I want 前端在 Access Token 过期时自动刷新, so that 我可以无感知地继续使用应用。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 前端收到 HTTP 401 响应, THE Request_Manager SHALL 自动使用 Refresh_Token 调用刷新接口
|
||
2. WHEN Token 刷新成功, THE Request_Manager SHALL 更新本地存储的 accessToken 和 refreshToken
|
||
3. WHEN Token 刷新成功, THE Request_Manager SHALL 使用新的 Access_Token 重试原始请求
|
||
4. WHEN Token 刷新失败（Refresh_Token 也过期）, THE Request_Manager SHALL 清除本地存储并跳转到登录页
|
||
5. WHILE 正在刷新 Token, THE Request_Manager SHALL 将其他请求加入队列等待刷新完成
|
||
6. WHEN Token 刷新完成, THE Request_Manager SHALL 使用新 Token 依次执行队列中的请求
|
||
|
||
### Requirement 4: Token 存储安全
|
||
|
||
**User Story:** As a 系统管理员, I want Token 安全存储, so that 用户的认证信息不会被泄露。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Auth_Service SHALL 使用 SHA256 哈希存储 Refresh_Token，不存储明文
|
||
2. THE Request_Manager SHALL 将 accessToken 和 refreshToken 存储在 uni.storage 中
|
||
3. WHEN 用户退出登录, THE Request_Manager SHALL 清除本地存储的所有 Token
|
||
4. WHEN 用户退出登录, THE Auth_Service SHALL 撤销该用户的 Refresh_Token
|
||
|
||
### Requirement 5: 数据库支持
|
||
|
||
**User Story:** As a 开发者, I want 数据库支持 Refresh Token 存储, so that 系统可以管理和验证 Refresh Token。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE User_Refresh_Token 表 SHALL 包含字段：Id、UserId、TokenHash、ExpiresAt、CreatedAt、CreatedByIp、RevokedAt、RevokedByIp、ReplacedByToken
|
||
2. THE User_Refresh_Token 表 SHALL 与 User 表建立外键关联
|
||
3. WHEN 查询 Refresh_Token 时, THE Auth_Service SHALL 同时检查是否过期和是否已撤销
|
||
|
||
### Requirement 6: 向后兼容
|
||
|
||
**User Story:** As a 开发者, I want 新的认证机制向后兼容, so that 现有的前端代码可以平滑迁移。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Auth_Service SHALL 继续支持旧的登录响应格式（仅返回 token 字符串）直到前端完全迁移
|
||
2. WHEN 前端未传递 refreshToken, THE Auth_Service SHALL 按照旧逻辑处理 401 错误
|
||
3. THE Auth_Service SHALL 继续维护 UserAccount 表中的 account_token 用于兼容旧系统
|