## ADDED Requirements ### Requirement: 请求前自动检查并刷新 token 系统 MUST 在发送需要认证的 HTTP 请求前,主动检查访问令牌是否即将过期,如果即将过期则自动使用 refreshToken 刷新,避免因 token 过期导致请求失败。 #### Scenario: Token 即将过期时自动刷新 - **GIVEN** 用户已登录且 accessToken 将在 3 分钟后过期 - **WHEN** 发起需要认证的 API 请求 - **THEN** 系统自动使用 refreshToken 调用刷新接口 - **AND** 刷新成功后使用新的 accessToken 发送原请求 - **AND** 用户无感知,请求正常完成 #### Scenario: Token 正常情况下不触发刷新 - **GIVEN** 用户已登录且 accessToken 将在 30 分钟后过期 - **WHEN** 发起需要认证的 API 请求 - **THEN** 系统检查 token 未过期 - **AND** 直接使用当前 token 发送请求 - **AND** 不调用刷新接口 #### Scenario: 白名单接口跳过 token 检查 - **GIVEN** 用户已登录 - **WHEN** 访问以下接口: - `/auth/login`(登录) - `/auth/refresh-token`(刷新 token) - `/auth/register`(注册) - `/auth/send-sms-code`(发送短信) - **THEN** 系统跳过 token 过期检查 - **AND** 不添加 Authorization 头 #### Scenario: 防止并发刷新 token - **GIVEN** 用户已登录且 token 即将过期 - **WHEN** 同时发起 3 个需要认证的请求 - **THEN** 只有一个请求触发 token 刷新 - **AND** 其他 2 个请求等待刷新完成后使用新 token - **AND** 刷新接口只被调用一次 #### Scenario: 刷新失败时清理状态 - **GIVEN** 用户已登录且 token 已过期 - **WHEN** 发起需要认证的请求 - **AND** 调用 refreshToken 接口返回 401(refreshToken 也无效) - **THEN** 系统自动清理 localStorage 中的所有 token - **AND** 跳转到登录页要求用户重新登录 - **AND** 拒绝所有后续请求直到重新登录 #### Scenario: 自定义缓冲时间 - **GIVEN** 系统配置 token 刷新缓冲时间为 10 分钟 - **WHEN** accessToken 将在 12 分钟后过期 - **THEN** 系统认为 token 仍然有效 - **WHEN** accessToken 将在 8 分钟后过期 - **THEN** 系统自动触发 token 刷新 ## MODIFIED Requirements ### Requirement: 请求拦截器增强 现有的请求拦截器 MUST 增强为支持 token 预检查和自动刷新功能。 #### Scenario: 拦截器新增预检查逻辑 - **GIVEN** 用户已登录且系统配置了自动刷新功能 - **WHEN** 发起需要认证的 HTTP 请求 - **THEN** 拦截器在添加 Authorization 头之前检查 token 过期时间 - **AND** 如果 token 即将过期,启动异步刷新流程 - **AND** 刷新完成后使用新 token 添加到请求头 - **AND** 继续发送原始请求 **Modified Behavior**: - 在添加 Authorization 头之前,先检查 token 是否即将过期 - 如果即将过期且不在刷新过程中,则启动异步刷新流程 - 刷新完成后继续添加 Authorization 头并发送请求 - 使用 Promise 机制确保所有等待刷新的请求按顺序执行 **Backward Compatibility**: - 现有的 401 错误处理机制保持不变 - 如果预检查失败(如 refreshToken 无效),仍然会触发 401 处理 - 所有现有接口调用方式保持不变