Skip to content

Mock 认证与替换边界 ​

当前策略 ​

模板阶段不连接任何真实认证服务。登录、用户信息和退出均由 src/mock/auth.ts 在浏览器本地模拟,开发和生产构建的行为一致。

演示账号:

text
账号:admin
密码:123456

Mock 会模拟短暂网络延迟,并在账号或密码错误时返回认证错误,便于验证登录页的加载和错误状态。

代码边界 ​

页面和路由守卫只调用 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、超时、取消请求和统一错误模型,供业务接入时复用。

接入业务项目 ​

模板完成后迁移具体项目时,按以下顺序接入认证:

  1. 在项目适配层定义真实接口请求和响应转换;
  2. 配置 VITE_API_URL,如需本地代理再配置 VITE_API_PROXY_URL;
  3. 根据后端约定配置 VITE_AUTH_SCHEME;
  4. 实现项目 AuthAdapter,并替换 src/adapters/auth/index.ts 的注入实现;
  5. 将项目特有的密码加密、单点登录和回调逻辑放入项目适配模块;
  6. 补充真实账号登录、用户信息、退出、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 不再读取。存储异常恢复仅清理本应用管理的键,不清空同域其他应用的数据。