sionrui/openspec/changes/add-auto-refresh-token/proposal.md

变更：前端 HTTP 拦截器自动刷新 refreshToken 功能

为什么

当前系统的 token 过期处理机制存在缺陷：

1. 只在收到 401 错误后才尝试刷新 token
2. 导致用户看到错误提示后才发现 token 已过期
3. 影响用户体验，特别是长时间操作时

需要实现在请求前主动检查并刷新即将过期的 token，提升用户体验。

什么发生变化

在 frontend/api/axios/client.js 的请求拦截器中添加智能 token 刷新机制：

新增功能

1. 预检查机制：在每次需要认证的请求前，检查 token 是否即将过期（默认 5 分钟缓冲时间）
2. 自动刷新：如果 token 即将过期，自动使用 refreshToken 获取新 token
3. 并发控制：防止多个请求同时触发 token 刷新
4. 无缝体验：用户无需感知 token 刷新过程，请求正常进行

影响的文件

• frontend/api/axios/client.js - 核心拦截器逻辑
• frontend/api/http.js - 可能需要更新调用方式
• frontend/utils/token-manager.js - 使用现有的 isExpired() 方法

关键设计决策

1. 缓冲时间：使用 5 分钟作为 token 刷新缓冲时间（可配置）
2. 白名单：刷新 token 接口 /auth/refresh-token 不需要 token，直接跳过检查
3. 错误处理：刷新失败时清理 token 并跳转登录页
4. 状态管理：使用 Promise 锁机制防止并发刷新

影响

• 用户体验：显著提升 - 消除因 token 过期导致的请求失败
• 系统稳定性：提高 - 减少 401 错误发生频率
• 安全性：保持 - 继续使用 refreshToken 机制，安全性不变
• 性能影响：极小 - 仅在 token 即将过期时触发一次刷新请求

兼容性

• 向后兼容：不影响现有认证流程
• API 兼容：不改变后端接口契约
• 配置兼容：可配置缓冲时间，默认 5 分钟