Files
funjia 0cbff3ccd5 feat(plugin): 发放 SN 带 source;插件 id 收敛到 src/meta.ts
- 新增 src/meta.ts 作为 PLUGIN_ID 的唯一字面量来源(index.ts 与页面共用)。
  这个 id 同时出现在 config、自注册 manifest、菜单/路由/命令 id 前缀、
  发放请求的 source 四处,任何一处抄错都是难查的静默故障。
- 发放请求加 source: funjia.print-tag(页面与 print-tag:issue-sn 命令都加)。
  后端 callerMeta 明确建议插件填自己的 ID,否则 SN 台账里一律记成 pc,
  分不清是插件发的还是别的入口发的。已在预览里验证落到台账。
- preview/mock-api.ts 的 SN 部分改为逐位镜像真后端(库存管理系统
  backend/src/api/sn-code/):校验位算法与字符表照抄,SN 形状/正则/补位口径一致。
  实测 mock 产出的 SN 全部能通过真后端校验位算法 —— 本地调通的码切到真后端不会失效。

最终验收:typecheck 通过;插件自检 0 error;仓库 verify-repository 32 passed / 0 failed;
repo-doctor 0 error 0 warning;源码模式与产物模式预览均跑通且无控制台报错。
2026-10-04 00:01:26 +08:00

524 lines
21 KiB
TypeScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* 预览器的最小后端(Vite 中间件)。
*
* ## 为什么预览器需要它
*
* 插件里最常见的功能就是「拉列表、存表单」。如果预览环境一律把 http 拦掉,
* 插件作者就只能看到一堆「被拦截」的日志 —— 页面渲染对不对能验,**功能对不对验不了**。
* 这个中间件让 `ctx.http.get("/api/device/list")` 在预览里真的能拿到数据。
*
* ## 它与宿主 mock 的关系
*
* 宿主自己也有一套 mock(`src/mock/`),跑在**浏览器内**、拦的是前端请求。
* 预览器是独立工程,拿不到那套代码(也不该依赖宿主源码),所以这里**重写一份**
* —— 但只重写「数据与路由」这层,契约里的关键定义与客户端共用,见下。
*
* 代价是两份实现可能漂移。因此约定:
*
* - **接口契约以宿主为准**,这里是它的**子集**(只实现最常用的几个);
* - 响应形状、`code` 取值、401 的语义**必须一致** —— 不一致就等于骗了插件作者;
* - 契约里那几个**线上跑的东西**(存储键、令牌形状、包络、请求头解析)
* 不在这份文件里重写,而是与客户端共用 `preview/api-contract.ts`;
* - 真后端就绪后,用 `PREVIEW_API_TARGET` 把 `/api` 代理过去,
* 这份 mock 自动让位(见 `vite.preview.config.ts`)。
*
* ## 401 与宿主对齐的地方
*
* 1. 未授权同时给 **HTTP 401** 和 **`code: 401`**(宿主 http 层认后者,
* 但真后端可能只给状态码,两边都给最稳);
* 2. `Authorization` 必须是 `Bearer <token>`,**严格校验前缀** ——
* 这样「请求层忘了加前缀」会在预览阶段暴露;
* 3. 登录接口用 `code: 1` 表达密码错误(业务失败),**不用 401**
* (401 的含义是「未授权」,会被上层当成「令牌失效」去清会话)。
*/
import type { IncomingMessage, ServerResponse } from "node:http";
import {
TOKEN_PREFIX,
TOKEN_TTL_MS,
UNAUTHORIZED_CODE,
parseAuthHeader,
type ApiResult,
type AuthUser,
} from "./api-contract";
/* ------------------------------------------------------------------ 类型 */
/** 用户表里的一行 = 对外的用户 + 密码(密码**绝不**出现在响应里) */
interface MockUser extends AuthUser {
password: string;
}
type Row = Record<string, any>;
/* ------------------------------------------------------------------ 数据 */
/** 与宿主 `src/mock/auth.ts` 的演示账号保持一致 */
const USERS: MockUser[] = [
{
id: 1,
account: "funjia",
password: "funjia123",
name: "管理员",
role: "超级管理员",
dept: "信息中心",
},
{
id: 2,
account: "viewer",
password: "viewer123",
name: "巡检员",
role: "普通用户",
dept: "运维组",
},
];
/**
* 种子数据:宿主 `src/mock/db.ts` 的一小部分。
*
* 刻意**不搬全**。预览要的是「有数据可看」,不是「数据与宿主逐行一致」;
* 搬全了一份 10 行的设备表反而会让这里变成第二个需要同步维护的地方。
*/
const SEED: Record<string, Row[]> = {
device: [
{ id: 1, code: "PC-2024-0001", name: "联想 ThinkCentre M720", category: "主机", brand: "联想", status: "在租", price: 1200, owner: "市政务服务中心信息科" },
{ id: 2, code: "MN-2024-0031", name: "AOC 24B1XH", category: "显示器", brand: "AOC", status: "在租", price: 300, owner: "市政务服务中心信息科" },
{ id: 3, code: "PC-2024-0007", name: "戴尔 OptiPlex 3080", category: "主机", brand: "戴尔", status: "闲置", price: 1100, owner: "" },
{ id: 4, code: "AIO-2024-0002", name: "惠普 ProOne 400 G6", category: "一体机", brand: "惠普", status: "维修中", price: 1600, owner: "第三实验中学" },
],
notice: [
{ id: 1, title: "租赁设备季度巡检安排", level: "重要", publisher: "运维组", content: "本季度巡检覆盖全部在租设备。" },
{ id: 2, title: "系统升级通知", level: "普通", publisher: "系统管理员", content: "本周六 22:00 升级,期间暂停服务约 30 分钟。" },
],
};
/* -------------------------------------------------------------- 响应助手 */
const ok = (data: any, total?: number): ApiResult => ({
code: 0,
msg: "ok",
data,
...(total === undefined ? {} : { total }),
});
const fail = (msg: string, code = 1): ApiResult => ({ code, msg, data: null });
const unauthorized = (reason: string): ApiResult => ({
code: UNAUTHORIZED_CODE,
msg: reason || "未登录或登录已过期",
data: null,
});
/* ------------------------------------------------------------------ 令牌 */
const toPublic = (user: MockUser): AuthUser => {
const { password: _password, ...rest } = user;
return rest;
};
function signToken(userId: number, ttl: number = TOKEN_TTL_MS): string {
const exp = Date.now() + ttl;
const nonce = Math.random().toString(36).slice(2, 10);
return `${TOKEN_PREFIX}.${userId}.${exp}.${nonce}`;
}
function verifyToken(token: string): { ok: true; user: AuthUser } | { ok: false; reason: string } {
const parts = String(token || "").split(".");
if (parts.length !== 4 || parts[0] !== TOKEN_PREFIX) {
return { ok: false, reason: "令牌格式不正确" };
}
const userId = Number(parts[1]);
const exp = Number(parts[2]);
if (!Number.isFinite(userId) || !Number.isFinite(exp)) {
return { ok: false, reason: "令牌格式不正确" };
}
if (Date.now() > exp) return { ok: false, reason: "登录状态已过期,请重新登录" };
const user = USERS.find((item) => item.id === userId);
if (!user) return { ok: false, reason: "令牌对应的用户不存在" };
return { ok: true, user: toPublic(user) };
}
/* ------------------------------------------------------------------ 请求 */
function readBody(req: IncomingMessage): Promise<any> {
return new Promise((resolve) => {
let raw = "";
req.on("data", (chunk) => {
raw += chunk;
// 1MB 上限:预览后端不该被一个大 body 拖死
if (raw.length > 1024 * 1024) raw = raw.slice(0, 1024 * 1024);
});
req.on("end", () => {
try {
resolve(raw ? JSON.parse(raw) : {});
} catch {
resolve({});
}
});
req.on("error", () => resolve({}));
});
}
/* ------------------------------------------------------------------ SN 码 */
/**
* SN 码的预览后端(对应宿主后端的 `api::sn-code` 模块)。
*
* ## 为什么模板里要额外带这一段
*
* 模板自带的通用 CRUD 只覆盖 `/api/<name>/list|detail|add|update|delete`,
* 而「标签打印」插件的核心增量能力是**可选接入 SN 码接口** —— 少了这一段,
* `npm run dev` 里一打开「② SN 码」开关就是 404,本地根本验不了,
* 只能构建 → 发布 → 装进宿主 → 点一遍,一圈几分钟。
*
* ## 与真后端的关系
*
* 参数口径(`targetType` / `count` / `refId` / `refLabel` / `remark`、返回
* `{ batch, count, items }`、校验返回 `{ valid, reason, exists, record }`)、
* 前缀表、SN 形状、**校验位算法与字符表**都是从真后端
* `库存管理系统/backend/src/api/sn-code/` 逐项抄过来的 —— 所以这里生成的 SN
* 拿去真后端 `/verify` 也能过校验位。
*
* 唯一不是真的地方是**数据**:台账在进程内存里,重启即清空。
* 所以:**别看号段连不连号,只验链路**。真要对接,关掉开关或设
* `PREVIEW_API_TARGET` 指向真后端。
*/
/** 业务类型 → 号段前缀。与真后端 `services/sn-code.js` 的 `DEFAULT_PREFIX` 逐项一致 */
const SN_PREFIX: Record<string, string> = {
DEVICE: "ZP",
PART: "PJ",
LEASE: "ZL",
MAINTENANCE: "SH",
CUSTOMER: "KH",
OTHER: "SN",
};
/** 校验位字符表:真后端刻意剔除了 0/O、1/I/L 这类肉眼与扫码都易混的字符 */
const SN_CHECK_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
/**
* 校验位算法 —— **与真后端逐位相同**(`services/sn-code.js` 的 `checksumChar`)。
*
* 这里刻意照抄而不是"自己定一个":抄一致之后,预览里生成的 SN
* 拿去真后端的 `/verify` 也能过校验位,本地调出来的码不会在切到真后端时集体失效。
* 数据仍然是进程内的(不查库),但**形状与算法是真的**。
*/
function snChecksum(payload: string): string {
let acc = 0;
for (let i = 0; i < payload.length; i += 1) {
// 位置加权:避免「字母调序」这类错误也算通过
acc = (acc * 31 + payload.charCodeAt(i) * (i + 1)) % 1000003;
}
return SN_CHECK_ALPHABET[acc % SN_CHECK_ALPHABET.length];
}
/** 与真后端一致的 SN 形状:`PREFIX-YYMMDD-NNNN-C` */
function makeSn(targetType: string, seq: number): string {
const pad = (n: number, w = 2) => String(n).padStart(w, "0");
const now = new Date();
const prefix = SN_PREFIX[targetType] || SN_PREFIX.OTHER;
const payload = `${prefix}-${String(now.getFullYear()).slice(2)}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(seq, 4)}`;
return `${payload}-${snChecksum(payload)}`;
}
/** 与真后端同一套正则以判定格式 */
const SN_PATTERN = /^([A-Z0-9]{2,3})-(\d{6})-(\d{1,6})-([A-Z0-9])$/;
function issueSn(ledger: Row[], body: any, count: number): Row[] {
const targetType = String(body?.targetType || "DEVICE");
const batch = `B${Date.now().toString(36).toUpperCase()}`;
const out: Row[] = [];
for (let i = 0; i < count; i += 1) {
const sn = makeSn(targetType, ledger.length + 1);
const row: Row = {
sn,
targetType,
batch,
status: "ISSUED",
issuedAt: new Date().toISOString(),
// 真后端会记「调用来源」,插件建议填自己的 id(便于台账追溯是谁发的码)——
// 这里原样透传,好让预览里也能验到「插件有没有带上 source」
source: body?.source ? String(body.source) : null,
...(body?.refId ? { refId: body.refId } : {}),
...(body?.refLabel ? { refLabel: body.refLabel } : {}),
...(body?.remark ? { remark: body.remark } : {}),
};
ledger.push(row);
out.push(row);
}
return out;
}
/** 命中 `/api/sn-codes*` 时返回结果;不命中返回 null,交回通用流程 */
function handleSnCode(
method: string,
path: string,
query: Record<string, string>,
body: any,
store: Record<string, Row[]>
): ApiResult | null {
if (path !== "/api/sn-codes" && !path.startsWith("/api/sn-codes/")) return null;
if (!store.__sn) store.__sn = [];
const ledger = store.__sn;
if (method === "GET" && path === "/api/sn-codes/meta") {
return ok({
targetTypes: Object.keys(SN_PREFIX),
defaultPrefix: SN_PREFIX,
typicalLength: 15,
maxLength: 16,
});
}
if (method === "POST" && path === "/api/sn-codes/generate") {
return ok(issueSn(ledger, body, 1)[0]);
}
if (method === "POST" && path === "/api/sn-codes/batch") {
const count = Math.min(Math.max(1, Number(body?.count) || 1), 200);
const items = issueSn(ledger, body, count);
return ok({ items, batch: items[0]?.batch });
}
if (method === "POST" && path === "/api/sn-codes/verify") {
const text = String(body?.sn || "").trim().toUpperCase();
if (!text) return ok({ valid: false, reason: "EMPTY" });
const matched = SN_PATTERN.exec(text);
if (!matched) return ok({ valid: false, reason: "FORMAT" });
const [, prefix, date, seq, check] = matched;
// 与真后端一致:序号补齐到 4 位后再算校验位
const payload = `${prefix}-${date}-${String(Number(seq)).padStart(4, "0")}`;
if (snChecksum(payload) !== check) {
return ok({ valid: false, reason: "CHECKSUM", expectedCheck: snChecksum(payload) });
}
const record = ledger.find((row) => row.sn === text) || null;
return ok({ valid: true, exists: !!record, record });
}
if (method === "GET" && path === "/api/sn-codes") {
const pageSize = Number(query.pageSize) || 50;
let rows = ledger.slice();
for (const key of ["targetType", "status", "batch"] as const) {
if (query[key]) rows = rows.filter((row) => String(row[key]) === query[key]);
}
if (query.sn) rows = rows.filter((row) => String(row.sn).includes(query.sn));
// 看最新发放的在前,和真后端一致
rows = rows.slice().reverse();
return ok(rows.slice(0, pageSize), rows.length);
}
const voided = path.match(/^\/api\/sn-codes\/([^/]+)\/void$/);
if (method === "POST" && voided) {
const target = ledger.find((row) => row.sn === decodeURIComponent(voided[1]));
if (!target) return fail("SN 不存在");
target.status = "VOID";
target.voidedAt = new Date().toISOString();
return ok(target);
}
return null;
}
/* ------------------------------------------------------------------ 路由 */
/**
* 路由分发。
*
* `store` 由调用方传进来(而不是读模块级的变量):数据必须**每个预览进程一份**,
* 且要能被 `createPreviewApi()` 的闭包持有 —— 写成模块级单例的话,
* 多次创建中间件会共用一份脏数据。
*/
function handle(
method: string,
path: string,
query: Record<string, string>,
body: any,
store: Record<string, Row[]>,
authorization?: string
): ApiResult {
/* ---- 免登录 ---- */
if (method === "POST" && path === "/api/auth/login") {
const user = USERS.find(
(item) => item.account === String(body.account || "").trim() && item.password === body.password
);
if (!user) return fail("账号或密码不正确");
return ok({
token: signToken(user.id),
expiresIn: Math.floor(TOKEN_TTL_MS / 1000),
user: toPublic(user),
});
}
// 登出幂等且免登录:令牌已过期时也必须能登出,否则用户卡在跳不出去的状态
if (method === "POST" && path === "/api/auth/logout") return ok(true);
if (method === "GET" && path === "/api/auth/demo-accounts") {
return ok(USERS.map((u) => ({ account: u.account, password: u.password, role: u.role })));
}
/* ---- 鉴权闸门:以下一律要求合法令牌 ---- */
const parsed = parseAuthHeader(authorization);
if (parsed.reason) return unauthorized(parsed.reason);
const auth = verifyToken(parsed.token);
if (!auth.ok) return unauthorized(auth.reason);
if (method === "GET" && path === "/api/auth/me") return ok(auth.user);
/* ---- SN 码:插件专属接口,优先于通用 CRUD 匹配 ---- */
const snResult = handleSnCode(method, path, query, body, store);
if (snResult) return snResult;
/* ---- 通用 CRUD ---- */
const crud = path.match(/^\/api\/([\w-]+)\/(list|detail|add|update|delete)$/);
if (crud) {
const [, name, action] = crud;
// 集合不存在就就地创建:宿主也是这个行为(`collection()` 动态建表),
// 于是插件自带的数据表不需要先在种子里登记
if (!store[name]) store[name] = [];
const storeRows = store[name];
if (action === "list") {
const page = Number(query.page) || 1;
const pageSize = Number(query.pageSize) || 10;
const keyword = (query.keyword || "").trim().toLowerCase();
/**
* 保留字不参与等值过滤。
*
* `userId` / `pluginId` 尤其要注意:宿主会给插件请求自动附加这两个归属参数
* (见宿主 mock 的同名路由),把它们当业务字段去等值过滤会**永远筛出空集**,
* 而症状是「列表页一个插件都查不到数据」—— 很难往参数名上想。
*/
const RESERVED = ["page", "pageSize", "keyword", "userId", "pluginId"];
let matched = storeRows.slice();
for (const [key, value] of Object.entries(query)) {
if (RESERVED.includes(key)) continue;
if (value === undefined || value === null || value === "") continue;
matched = matched.filter((row) => String(row[key]) === String(value));
}
if (keyword) {
// 关键字按**第一行的字段名**搜(与宿主 `db.query` 的默认 keywordFields 一致),
// 而不是按每一行自己的字段 —— 否则字段不齐的行会搜出不一样的结果
const fields = Object.keys(matched[0] || {});
matched = matched.filter((row) =>
fields.some((field) => String((row as Row)[field] ?? "").toLowerCase().includes(keyword))
);
}
const start = (page - 1) * pageSize;
// 列表的 `data` 是**数组本身**,条数是同级的 `total` —— 与宿主一致。
// (写成 `data: { rows, total }` 是最常见的抄错,插件那边会永远拿不到行)
return ok(matched.slice(start, start + pageSize), matched.length);
}
if (action === "detail") {
return ok(storeRows.find((row) => String(row.id) === String(query.id)) || null);
}
if (action === "add") {
const nextId = storeRows.reduce((max, row) => Math.max(max, Number(row.id) || 0), 0) + 1;
const row: Row = { ...body, id: nextId, createdAt: new Date().toISOString() };
storeRows.push(row);
return ok(row);
}
if (action === "update") {
const index = storeRows.findIndex((row) => String(row.id) === String(body.id));
if (index < 0) return fail("记录不存在");
storeRows[index] = { ...storeRows[index], ...body };
return ok(storeRows[index]);
}
if (action === "delete") {
const raw = body.ids !== undefined ? body.ids : body.id;
const ids = (Array.isArray(raw) ? raw : raw === undefined ? [] : [raw]).map(String);
if (!ids.length) return fail("没有指定要删除的记录");
const before = storeRows.length;
// 整体替换而不是原地 splice:保持「store 里的数组对象」这一层的稳定性,
// detail/update 拿到的是同一份引用,语义简单
store[name] = storeRows.filter((row) => !ids.includes(String(row.id)));
return ok(before - store[name].length);
}
}
// 明确报「没有这个接口」而不是静默 404 —— 插件作者一眼就知道是路径写错了,
// 而不是后端挂了
return fail(`预览后端没有这个接口:${method} ${path}(实现见 preview/mock-api.ts)`, 404);
}
/* ------------------------------------------------------------------ 出口 */
/**
* 创建中间件。数据存在闭包里,**进程重启即重置**(预览不需要持久化)。
*/
export function createPreviewApi() {
// 深拷贝:种子数据不该被请求改到,否则第二次装载就看到脏数据了
const store: Record<string, Row[]> = JSON.parse(JSON.stringify(SEED));
/**
* 已经提醒过的空集合名。
*
* 通用 CRUD 会**动态创建**没见过的集合(宿主同行为),于是表名打错
* (`/api/devices/list` 而种子是 `device`)的表现是「接口成功、列表是空的」——
* 看起来像「没数据」,不像「表名错了」。
*
* 响应**不动**(那是契约,宿主也是这么答的),只在预览服务端的终端里提醒一句:
* 那里正是开发者跑 `npm run dev` 时盯着的窗口。用 Set 去重,只提醒一次。
*/
const warned = new Set<string>();
const seedKeys = new Set(Object.keys(SEED));
function warnIfUnknownCollection(path: string) {
const match = path.match(/^\/api\/([\w-]+)\/(list|detail)$/);
if (!match) return;
const [, name] = match;
if (seedKeys.has(name) || warned.has(name)) return;
warned.add(name);
console.warn(
`\n \x1b[33m[preview]\x1b[0m 集合 \`${name}\` 不在预览种子里,已自动建成空表(宿主也是这样)。` +
`\n 如果你以为它有数据,先检查表名拼写;种子里现有:${[...seedKeys].join(" / ")}\n`
);
}
return async function previewApiMiddleware(
req: IncomingMessage,
res: ServerResponse,
next: (err?: any) => void
): Promise<void> {
const rawUrl = req.url || "/";
const path = rawUrl.split("?")[0];
if (!path.startsWith("/api/")) return next();
const query: Record<string, string> = {};
for (const [key, value] of new URL(rawUrl, "http://127.0.0.1").searchParams) {
query[key] = value;
}
const method = (req.method || "GET").toUpperCase();
const body = method === "GET" ? {} : await readBody(req);
if (method === "GET") warnIfUnknownCollection(path);
let result: ApiResult;
try {
result = handle(method, path, query, body, store, req.headers.authorization);
} catch (error) {
result = fail(`预览后端内部错误:${(error as Error)?.message ?? error}`, 500);
}
// 未授权同时给 HTTP 状态码与业务码:真后端可能只给其一,
// 两边都给能让预览的行为最接近「两种后端都试过」
res.statusCode = result.code === UNAUTHORIZED_CODE ? UNAUTHORIZED_CODE : 200;
res.setHeader("Content-Type", "application/json; charset=utf-8");
res.setHeader("Cache-Control", "no-store");
res.end(JSON.stringify(result));
};
}