/** * 预览器的**接口契约**:客户端(`preview/host.ts`)与服务端(`preview/mock-api.ts`) * 共用这一份定义。 * * ## 为什么单独一个文件 * * 这两边是同一份契约的两个实现方。如果各写各的 `AuthUser`、各写各的 * `parseAuthHeader`、各写各的令牌前缀,那么「客户端以为令牌是 `Bearer x`、 * 服务端以为就是 `x`」这类错误**不会有任何编译错误**,只会表现为 * 「登录成功但所有接口都 401」。 * * 放一个文件里,改一边就同时改了另一边。 * * ## 它不管什么 * * 这里只有**线上跑的东西**(存储键、令牌形状、响应包络、请求头解析)。 * 数据表种子、内存 CRUD 逻辑属于实现,在 `mock-api.ts` 里。 * * ## 与宿主的关系 * * 契约本身**以宿主为准**(`src/mock/auth.ts` + `src/core/http/index.ts`): * 同一个地址、同一个包络、同样的 401 语义。预览器是独立工程、拿不到宿主源码, * 所以这里是一份**手抄的副本** —— 它必然有漂移的风险,这是一处已知的取舍, * 由 `npm run verify` 的契约断言兜住最关键的几个字段。 */ /* ------------------------------------------------------------ 存储键 */ /** * 令牌存储键。 * * **刻意与宿主不同名**(宿主是 `funjia-plugin-host:token`)。两者平时确实是 * 不同的 origin(预览 5310 / 宿主 5180),但一旦有人把预览挂到宿主同源的 * 子路径下调试,同名的键就会互相覆盖 —— 表现为「预览里登录把宿主的会话踢了」, * 而且没人会往 localStorage 的键名上想。 */ export const TOKEN_KEY = "funjia-plugin-preview:token"; /** 用户信息存储键,理由同上 */ export const USER_KEY = "funjia-plugin-preview:user"; /* ------------------------------------------------------------ 令牌形状 */ /** 令牌前缀。明文自描述,肉眼能看出「这是预览 mock 签的」 */ export const TOKEN_PREFIX = "mock"; /** 令牌有效期,与宿主 mock 一致 */ export const TOKEN_TTL_MS = 2 * 60 * 60 * 1000; /* -------------------------------------------------------------- 类型 */ /** 登录用户(**不含密码**)。字段与宿主 mock 返回的 `user` 对齐 */ export interface AuthUser { id: number; name: string; account: string; role: string; dept?: string; } /** 演示账号:登录页直接列出来,省掉「文档里翻账号」这一步 */ export interface DemoAccount { account: string; password: string; role: string; } /** 统一响应包络。`code === 0` 表示成功 */ export interface ApiResult { code: number; msg: string; data: T; total?: number; } /* ------------------------------------------------------------ 约定值 */ /** * 未授权的业务码。 * * 与宿主取同一个数字,且**刻意与 HTTP 状态码同值** —— 于是客户端一句 * `result.code === 401` 就能同时覆盖「内置 mock 返回的 code」与 * 「真后端返回的 HTTP 401」(后者由请求层归一成前者)。见 `host.ts` 的 `httpCall`。 */ export const UNAUTHORIZED_CODE = 401; /** * 登录态广播的**全局事件名**(与宿主 `src/core/session.ts` 完全一致)。 * * 插件用 `ctx.event.onGlobal("user:login", ...)` 监听的就是这两条。 * 预览器也发同样的名字,插件才能在预览里验到「登出后我被通知了」。 */ export const AUTH_EVENTS = { login: "user:login", logout: "user:logout", } as const; /* -------------------------------------------------------- 请求头解析 */ /** * 从 `Authorization` 头的值里取出裸令牌。 * * **严格校验 `Bearer ` 前缀**,与真后端(和宿主 mock)同口径。 * 宽松处理会把「客户端忘了加前缀」这个 bug 藏起来 —— 而这个 bug 在 * 预览阶段暴露出来只需要一次请求,拖到接真后端那天就变成了 * 「登录明明成功、接口全 401」。 * * 只有**服务端**(`mock-api.ts`)用到它;放在这里是因为它描述的是 * 契约的校验规则,写错就两边对不上。 */ export function parseAuthHeader(raw?: string): { token: string; reason?: string } { const value = (raw || "").trim(); if (!value) return { token: "", reason: "缺少 Authorization 请求头" }; if (!/^Bearer\s+/i.test(value)) { return { token: "", reason: "Authorization 头缺少 `Bearer ` 前缀" }; } const token = value.replace(/^Bearer\s+/i, "").trim(); return token ? { token } : { token: "", reason: "Authorization 头里的令牌为空" }; }