外观
Mock 认证与替换边界
当前策略
模板阶段不连接任何真实认证服务。登录、用户信息和退出均由 src/mock/auth.ts 在浏览器本地模拟,开发和生产构建的行为一致。
演示账号:
text
账号:admin
密码:123456Mock 会模拟短暂网络延迟,并在账号或密码错误时返回认证错误,便于验证登录页的加载和错误状态。
代码边界
页面和路由守卫只调用 src/api/auth.ts 暴露的三个稳定函数:
ts
fetchLogin(params)
fetchGetUserInfo()
fetchLogout(context?)src/api/auth.ts 只转发给 src/adapters/auth 中注入的 AuthAdapter。通用模板固定注入 mockAuthAdapter,它再调用 src/mock/auth.ts。接入具体项目时,应在项目分支实现新的 AuthAdapter 并只替换注入点,把后端响应转换成模板使用的 LoginResponse 和 UserInfo,不要让登录页、Store 或路由守卫感知项目接口字段。
会话约束
- 密码只存在于登录表单,不写入 Pinia、LocalStorage 或 SessionStorage;
- 只持久化
isLogin、accessToken和refreshToken; - redirect 只接受以单个
/开头的站内地址,避免开放重定向; - 退出流程始终清理本地会话,即使未来的远端退出请求失败;
- HTTP 层仍保留 401、403、超时、取消请求和统一错误模型,供业务接入时复用。
接入业务项目
模板完成后迁移具体项目时,按以下顺序接入认证:
- 在项目适配层定义真实接口请求和响应转换;
- 配置
VITE_API_URL,如需本地代理再配置VITE_API_PROXY_URL; - 根据后端约定配置
VITE_AUTH_SCHEME; - 实现项目
AuthAdapter,并替换src/adapters/auth/index.ts的注入实现; - 将项目特有的密码加密、单点登录和回调逻辑放入项目适配模块;
- 补充真实账号登录、用户信息、退出、401 和 403 的集成测试。
项目专属认证能力不进入通用模板主流程。
用户角色和操作权限的规范化、加载状态及旧 buttons 字段兼容方式见权限规则。
退出与重新登录
UI 统一调用 src/services/auth.ts 的 signOut()。同一会话的重复调用共用退出任务;开始退出时取消旧请求、使初始化任务失效,并暂停普通 HTTP 请求。远端退出失败或超过 10 秒仍会清理本地状态。新登录拥有独立会话标识,旧退出和旧用户信息、菜单、权限刷新结果不能覆盖新会话。Token 轮换继续使用 setToken();重新登录或切换账号必须调用 establishSession()。
真实适配器的退出请求需要透传 context.requestScope,允许该请求在退出阶段发送。模板的 Mock 实现无需额外处理:
ts
import http from '@/utils/http'
import type { AuthAdapter } from '@/adapters/auth'
const logout: AuthAdapter['logout'] = async (context) => {
await http.post<void>({
url: '/auth/logout',
requestScope: context?.requestScope,
retry: false,
showErrorMessage: false
})
}退出会清空认证、授权、菜单、iframe 路由、锁屏密码、搜索历史和当前标签状态,销毁旧会话的页面缓存。保留主题、语言、布局等偏好,以及待确认归属的标签列表;重新获取用户身份后,仅同账号可恢复仍有效的标签,其他账号或归属不明的标签会全部清除。用户 ID 0 也按有效身份处理。
项目的业务 Store、Socket、轮询可注册清理回调:
ts
import { registerSessionCleanup } from '@/utils/session'
const unregister = registerSessionCleanup(() => {
businessStore.$reset()
socket.close()
clearInterval(pollingTimer)
})
// 注册对象销毁时调用 unregister(),避免重复注册。回调必须可重复执行,并在同步部分释放账号状态、停止任务;允许异步收尾,异步失败会被诊断记录捕获,但不会阻塞下一次登录。项目异步业务任务也应检查会话标识或使用 AbortSignal,避免晚返回的数据写入新账号。
iframe 缓存使用应用命名空间;旧的无命名空间 iframeRoutes 不再读取。存储异常恢复仅清理本应用管理的键,不清空同域其他应用的数据。