HaniBlindBox/.kiro/specs/refresh-token/requirements.md

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 用于兼容旧系统