feat: 新增 plugin/ 插件化形态(funjia.print-tag)+ 可选 SN 条码/二维码

把本工程的标签排版能力改造成 FunjiaUI 远端插件,放进 plugin/ 子目录,
与原独立 Web 版并存(两者功能一致,模板/版面/打印行为逐项对齐)。

- 入口从 createApp().mount() 改为 activate(ctx) + ctx.addRoute,注册 1 菜单 / 1 路由 / 2 命令
- 11 个模板的渲染收敛成 SpecTag,差异集中到 templates/registry.ts(字段/选项/默认值原样保留)
- 店铺名 / 电话从写死改为可配置,记忆在插件私有存储
- 内置二维码图片改为打包 data URL —— 远端插件没有自己的 public/
- 去掉 @headlessui/vue(换原生 select)与 Tailwind,样式类名统一 pt- 前缀避免污染宿主
- 可选接入宿主 api::sn-code:按 SN 生成真 Code 128 条码与可扫二维码;
  关闭时(默认)完全保持原静态二维码行为。领码优先贴到已排版的格子,不够才新建
- 新增 commands: print-tag:issue-sn / print-tag:render-svg(后者纯本地出图,供其它插件复用)
- code128.ts 实现真 Code 128 Set B(含校验位);二维码走 qrcode-generator(真 QR)
- 自带本地预览器(preview/mock-api.ts 补了 /api/sn-codes mock)与 deploy / verify 脚本
- verify.mjs 修掉一处误报:源码边界判据改为「解析后是否逃出工程根」,
  而不是「说明符是否以 .. 开头」(后者会把 src/components/X.vue → ../codes 误判为越界)

已发布到插件仓库:funjia.print-tag@1.0.0
This commit is contained in:
2026-10-03 23:48:32 +08:00
parent 1896d1032b
commit ef41d98838
43 changed files with 8835 additions and 0 deletions
+597
View File
@@ -0,0 +1,597 @@
#!/usr/bin/env node
/**
* 插件自检 —— 在 deploy 之前把「必然会在别处报错」的问题在这里拦下。
*
* ## 为什么需要它
*
* 这个工程里有一批值**必须严格一致**,一旦不一致,报错点离原因很远:
*
* | 不一致 | 你看到的现象 | 真正的原因 |
* | ---- | ---- | ---- |
* | `artifact` 与仓库条目对不上 | 发布脚本说「找不到产物」 | 两处各写了一遍文件名 |
* | `globalKey` 与产物全局名对不上 | 脚本加载成功、插件不出现 | 宿主无从认领 |
* | `kind` 与 artifact 后缀对不上 | 宿主按 IIFE 插标签、拿到 ESM 源码 | 后缀是给人看的,得自己保证 |
* | 版本号硬编码进源码 | 发了新版本却显示旧版本 | 版本该由索引在运行时注入 |
*
* 前三条在 `vite.config.ts` 里已经拦了一部分(构建时才炸),
* 本脚本的价值是**在构建之前**、并且**跨工程**(连仓库的 `repo.config.json` 一起看)。
*
* ## 用法
*
* npm run verify
* npm run verify -- --repo ../funjia-plugin-repository # 顺带校验仓库条目
* PLUGIN_REPO=../funjia-plugin-repository npm run verify
*/
import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
import { dirname, join, relative, resolve, sep } from "node:path";
import { fileURLToPath } from "node:url";
const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
/* ------------------------------------------------------------------ 输出 */
let errors = 0;
let warnings = 0;
const ok = (m) => console.log(` OK ${m}`);
const bad = (m) => {
errors += 1;
console.log(` FAIL ${m}`);
};
const warn = (m) => {
warnings += 1;
console.log(` WARN ${m}`);
};
const info = (m) => console.log(` ${m}`);
const step = (m) => console.log(`\n${m}`);
/* ------------------------------------------------------------------ 入参 */
function parseArgs(argv) {
const out = { repo: process.env.PLUGIN_REPO || null };
for (let i = 0; i < argv.length; i += 1) {
if (argv[i] === "--repo") out.repo = argv[i + 1];
}
return out;
}
const args = parseArgs(process.argv.slice(2));
/* ------------------------------------------------------------- 组 A:清单 */
step("组 A · plugin.config.json");
const cfgFile = join(root, "plugin.config.json");
if (!existsSync(cfgFile)) {
console.error(`找不到 ${cfgFile} —— 这个文件是插件元数据的唯一真源。`);
process.exit(1);
}
let cfg;
try {
cfg = JSON.parse(readFileSync(cfgFile, "utf8"));
} catch (e) {
console.error(`plugin.config.json 不是合法 JSON:${e.message}`);
process.exit(1);
}
// 这四项缺任何一个,构建或发布就一定失败,所以在这里就说清楚
for (const key of ["id", "name", "version", "kind", "artifact"]) {
if (!cfg[key] || typeof cfg[key] !== "string") bad(`缺少必填字段 ${key}`);
}
if (errors === 0) ok("必填字段齐全(id / name / version / kind / artifact)");
if (cfg.kind && !["iife", "esm"].includes(cfg.kind)) {
bad(`kind = ${JSON.stringify(cfg.kind)},只允许 "iife" 或 "esm"(没有 builtin)`);
} else if (cfg.kind) {
ok(`kind = ${cfg.kind}`);
}
/**
* 版本号必须是「数字点分」。
*
* 因为仓库按点分段比大小(`1.10.0 > 1.9.0`),写了 `v1.0` 或 `1.0.0-beta`
* 之后排序就会静默错位 —— 不是报错,是「更新提示不出现」,更难查。
*/
if (cfg.version && !/^\d+(\.\d+)*$/.test(cfg.version)) {
bad(`version = ${JSON.stringify(cfg.version)},应为数字点分(如 1.0.0)`);
} else if (cfg.version) {
ok(`version = ${cfg.version}`);
}
/**
* 命名建议(只警告,不拦):`<组织>.<模块>`。
*
* 这不是洁癖:`id` 是安装/卸载/事件前缀共用的唯一键,带上组织前缀才不会
* 和别人的插件撞车。仓库里所有官方示例都遵循这个形状。
*/
if (cfg.id && !/^[a-z0-9]+(?:-[a-z0-9]+)*(?:\.[a-z0-9]+(?:-[a-z0-9]+)*)+$/.test(cfg.id)) {
warn(`id = ${JSON.stringify(cfg.id)} 不像 <组织>.<模块>(全小写、连字符、至少一个点)`);
} else if (cfg.id) {
ok(`id = ${cfg.id}(符合 <组织>.<模块>)`);
}
/* --------------------------------------------------- artifact / kind 一致 */
if (cfg.artifact) {
const shapeOk = /^[A-Za-z0-9_.-]+\.(iife|es)\.js$/.test(cfg.artifact);
if (!shapeOk) {
bad(`artifact = ${JSON.stringify(cfg.artifact)},应为 "<Name>.iife.js" 或 "<Name>.es.js"`);
} else {
ok(`artifact = ${cfg.artifact}`);
// 后缀必须与 kind 对上:宿主是「按 kind 决定装载方式」的,
// 后缀写错不会立刻炸 —— 而是按错误的方式去装,现象是插件不出现。
const suffix = cfg.artifact.endsWith(".iife.js") ? "iife" : "esm";
if (cfg.kind && suffix !== cfg.kind) {
bad(
`artifact 后缀(${cfg.artifact})暗示 ${suffix},但 kind = ${cfg.kind} —— 两者必须一致;` +
`发布后宿主会按 kind 去装,后缀只在这里被校验`
);
} else if (cfg.kind) {
ok(`artifact 后缀与 kind 一致(${cfg.kind})`);
}
}
}
if (cfg.style && !cfg.style.endsWith(".css")) {
bad(`style = ${JSON.stringify(cfg.style)} 应以 .css 结尾`);
} else if (cfg.style) {
ok(`style = ${cfg.style}`);
}
/* ------------------------------------------------------------ globalKey */
/**
* `globalKey` 会被 rollup 直接写进产物当全局变量名,所以必须是合法标识符。
* 走 `window.FunjiaPlugin.register()` 自注册通道的插件其实不依赖它,
* 但 rollup 仍然需要这个名字(`lib.name`),所以不能省。
*/
if (cfg.globalKey) {
if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(cfg.globalKey)) {
bad(`globalKey = ${JSON.stringify(cfg.globalKey)} 不是合法 JS 标识符`);
} else {
ok(`globalKey = ${cfg.globalKey}`);
}
} else if (cfg.kind === "iife") {
warn("未声明 globalKey:构建会按 id 推断一个,但老生态(window.<key>)认领通道就用不了");
} else {
ok("esm 形态无需 globalKey");
}
/* ------------------------------------------------------- 组 B:源码边界 */
step("组 B · 源码边界");
/**
* 剥掉注释再扫描。
*
* **必须做这一步**:文档注释里天然会出现反面示例,比如
*
* ```
* * - ❌ `import { x } from "../../src/…"` —— 绝不能引宿主内部实现
* ```
*
* 不剥注释的话,这条「说明什么叫违规」的注释本身会被判成违规,
* 于是自检脚本永远报一个假错 —— 而假错比没有错更糟:真错会被一起忽略。
*
* 行注释用 `[^:]\/\/` 而非裸 `\/\/`,是为了不误伤 `https://` 这类串里的双斜杠。
*/
function stripComments(text) {
return text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/[^\n]*/g, "$1");
}
const srcDir = join(root, "src");
const entryFile = join(srcDir, "index.ts");
if (!existsSync(entryFile)) {
bad("找不到 src/index.ts —— 构建入口");
} else {
const entry = readFileSync(entryFile, "utf8");
/**
* 自注册是本模板推荐的认领方式:产物全局名可以与插件 id 完全不同
* (产物叫 HelloBundle,插件 id 是 acme.hello),一个脚本也能塞多个插件。
*/
if (entry.includes("FunjiaPlugin.register")) {
ok("src/index.ts 走自注册通道(window.FunjiaPlugin.register)");
} else if (cfg.globalKey && entry.includes("export default")) {
warn("未发现 window.FunjiaPlugin.register:将依赖 window.<globalKey> 认领(老生态通道)");
} else {
bad(
"src/index.ts 既没有 window.FunjiaPlugin.register,也不确定有默认导出 —— " +
"宿主可能加载成功但认领不到插件"
);
}
/* ---------------- 版本号硬编码 ---------------- */
// 版本由仓库索引在运行时注入(ctx.plugin.version)。硬编码的后果是
// 「发了 0.2.0,界面上还显示 0.1.0」,而且换了 id 复制工程时会连版本一起带过去。
if (cfg.version) {
const offenders = [];
const walk = (dir) => {
for (const name of readdirSync(dir)) {
const p = join(dir, name);
if (statSync(p).isDirectory()) {
walk(p);
continue;
}
if (!/\.(ts|js|vue|tsx|jsx)$/.test(name)) continue;
const text = stripComments(readFileSync(p, "utf8"));
if (text.includes(cfg.version)) offenders.push(p.slice(root.length + 1));
}
};
walk(srcDir);
if (offenders.length > 0) {
bad(
`源码里出现了 version 字面量 ${cfg.version}(${offenders.join(", ")})—— ` +
`版本应取 ctx.plugin.version,让仓库索引当唯一真源`
);
} else {
ok(`源码未硬编码版本 ${cfg.version}(改用 ctx.plugin.version)`);
}
}
/* ---------------- 不许引宿主内部实现 ---------------- */
// 引了宿主源码,宿主重构一次插件就整体失效。要能力就走 ctx(天然向前兼容)。
//
// ⚠️ 判据是「**解析后是否逃出工程根**」,不是「说明符是不是以 .. 开头」。
// 模板原始版把两者当成一回事(只白名单 `../sdk` / `../runtime` / `../pages`),
// 于是任何把代码分到子目录的插件(`src/components/X.vue` 里 `import "../codes"`)
// 都会被误报成「引了工程外部模块」—— 报错点看着吓人,其实什么毛病都没有。
// 改成真正做一次路径解析,`..` 只在真的越出 root 时才算泄漏。
const leaked = [];
const scanImports = (dir) => {
for (const name of readdirSync(dir)) {
const p = join(dir, name);
if (statSync(p).isDirectory()) {
scanImports(p);
continue;
}
if (!/\.(ts|js|vue|tsx|jsx)$/.test(name)) continue;
const text = stripComments(readFileSync(p, "utf8"));
for (const m of text.matchAll(/from\s+["']([^"']+)["']/g)) {
const spec = m[1];
// 裸说明符(vue / qrcode-generator / funjiaui)走打包器解析,不属于本组管辖
if (!spec.startsWith(".")) continue;
const resolved = resolve(dirname(p), spec);
const inside = resolved === root || resolved.startsWith(root + sep);
if (!inside) leaked.push(`${relative(root, p)} → ${spec}`);
}
}
};
scanImports(srcDir);
if (leaked.length > 0) {
bad(`发现了指向工程外部的 import(插件不能依赖宿主实现):\n ${leaked.join("\n ")}`);
} else {
ok("没有引用工程外部的模块(插件保持独立交付物)");
}
}
/* ------------------------------------------------- 组 C:构建产物(可选) */
step("组 C · 构建产物");
const distDir = join(root, "dist");
if (!existsSync(distDir)) {
info("dist/ 还不存在 —— 先 npm run build,或忽略(本组只是额外确认)");
} else {
const artifactPath = cfg.artifact ? join(distDir, cfg.artifact) : null;
if (artifactPath && existsSync(artifactPath)) {
const kb = (statSync(artifactPath).size / 1024).toFixed(1);
ok(`dist/${cfg.artifact} 存在(${kb} KB)`);
} else if (artifactPath) {
bad(`dist/${cfg.artifact} 不存在 —— artifact 名字与构建输出对不上`);
}
if (cfg.style) {
if (existsSync(join(distDir, cfg.style))) {
ok(`dist/${cfg.style} 存在`);
} else if (existsSync(artifactPath || "")) {
// 组件里没写 <style> 时 vite 不会产出 CSS —— 此时应把 style 从配置里去掉,
// 否则宿主会去注入一个 404 的样式表。
warn(`dist/${cfg.style} 不存在,但配置里声明了 style —— 页面若无 <style> 请去掉该字段`);
}
}
/* ---------------- external 是否真的生效 ---------------- */
// 这是插件构建后果最严重的一类错误:Vue 被内联进产物,宿主里就有了两份 Vue 实例,
// 症状是「页面画得出来、但完全点不动」,而且**不报任何错**。
// `npm run preview` 能直接看出来(点一下页面按钮就知道),这里补一道静态判断,
// 好在构建之后、交付之前就拦住。
if (artifactPath && existsSync(artifactPath)) {
const text = readFileSync(artifactPath, "utf8");
const sizeKb = statSync(artifactPath).size / 1024;
// Vue 3 运行时压缩后也在 90KB 上下,而一个普通插件不该有这么重
const VUE_RUNTIME_KB = 60;
if (sizeKb > VUE_RUNTIME_KB) {
warn(
`产物 ${sizeKb.toFixed(1)} KB,偏大 —— 若非有意为之,检查 vue / funjiaui 是不是被内联了` +
`(内联 = 宿主里两份 Vue = 页面点不动,且不报错)`
);
}
if (cfg.kind === "iife") {
// IIFE 的 external 会变成「把全局当参数传进去」,压缩后形如 `}(vue);`
const head = text.slice(0, 240);
const tail = text.slice(-240);
if (/[(,]vue\)|\.vue\)/.test(tail) || /function\s*\(\s*vue\s*\)/.test(head)) {
ok("IIFE 产物把 vue 当外部依赖(可见 }(vue) / function(vue)),没内联");
} else {
warn("IIFE 产物里没找到对全局 vue 的外部引用 —— 确认 vue 是否被内联进来了");
}
} else if (cfg.kind === "esm") {
if (/from\s*["']vue["']/.test(text)) {
ok('ESM 产物保留了裸说明符 from "vue"(交给宿主 import map 解析)');
} else {
warn('ESM 产物里没看到 from "vue" —— 确认 vue 是否被内联进来了');
}
}
}
}
/* ------------------------------------------- 组 D:与仓库条目交叉校验 */
step("组 D · 与仓库条目交叉校验");
const repoDir = args.repo ? resolve(root, args.repo) : null;
if (!repoDir) {
info("未指定仓库路径,跳过(--repo <路径> 或 PLUGIN_REPO 环境变量可开启)");
} else {
const repoCfgFile = join(repoDir, "repo.config.json");
if (!existsSync(repoCfgFile)) {
bad(`在 ${repoCfgFile} 找不到 repo.config.json —— 仓库路径对吗?`);
} else {
const repoCfg = JSON.parse(readFileSync(repoCfgFile, "utf8"));
const entry = (repoCfg.plugins || []).find((p) => p.id === cfg.id);
if (!entry) {
info(`仓库清单里还没有 ${cfg.id} —— 首次 deploy 时会自动加进去`);
} else {
const pairs = [
["artifact", cfg.artifact, entry.artifact],
["kind", cfg.kind, entry.kind],
["globalKey", cfg.globalKey, entry.globalKey],
];
let drifted = 0;
for (const [field, mine, theirs] of pairs) {
// 一边没写就不算「漂移」(globalKey 对 ESM 形态本来就没有)
if (mine === undefined || theirs === undefined) continue;
if (mine !== theirs) {
bad(`仓库条目 ${cfg.id} 的 ${field} = ${JSON.stringify(theirs)},本工程是 ${JSON.stringify(mine)}`);
drifted += 1;
}
}
if (drifted === 0) ok(`仓库条目 ${cfg.id} 的 artifact / kind / globalKey 与本工程一致`);
// 版本漂移不算错:本地改了版本还没 deploy 是正常的开发中间态
if (entry.version !== cfg.version) {
info(`版本待发布:本工程 ${cfg.version},仓库当前 ${entry.version}(deploy 后会更新)`);
}
}
}
}
/* ------------------------------------------------------ 组 E:本地预览 */
step("组 E · 本地预览");
const previewDir = join(root, "preview");
const previewCfg = join(root, "vite.preview.config.ts");
const REQUIRED_PREVIEW_FILES = [
"index.html",
"artifact.html",
"main-source.ts",
"main-artifact.ts",
"App.vue",
"mount.ts",
"host.ts",
"contract.ts",
"loaders.ts",
"runtime.ts",
"shims/funjiaui.ts",
"style.css",
// 预览的接口能力:契约(两侧共用)+ 最小后端
"api-contract.ts",
"mock-api.ts",
];
if (!existsSync(previewDir)) {
bad("找不到 preview/ —— npm run dev / npm run preview 会起不来");
} else if (!existsSync(previewCfg)) {
bad("找不到 vite.preview.config.ts —— 预览服务器没有配置");
} else {
const missing = REQUIRED_PREVIEW_FILES.filter((f) => !existsSync(join(previewDir, f)));
if (missing.length > 0) {
bad(`预览缺少文件:${missing.join("、")}`);
} else {
ok(`预览资产齐全(${REQUIRED_PREVIEW_FILES.length} 个文件 + vite.preview.config.ts)`);
}
/* ---------------- import map 必须在 head 里静态声明 ---------------- */
// 这是最容易踩、又最难查的一条:模块加载开始之后再插入 import map,
// 浏览器会**静默忽略**它 —— 不报错,只是 ESM 产物里的 "vue" 解析不了。
for (const page of ["index.html", "artifact.html"]) {
const file = join(previewDir, page);
if (!existsSync(file)) continue;
const html = readFileSync(file, "utf8");
const mapAt = html.indexOf('type="importmap"');
const moduleAt = html.indexOf('type="module"');
if (mapAt < 0) {
bad(`${page} 里没有 import map —— ESM 产物里的裸说明符 "vue" 会解析失败`);
} else if (moduleAt >= 0 && mapAt > moduleAt) {
bad(
`${page} 的 import map 排在了 <script type="module"> 之后 —— ` +
`浏览器会静默忽略它(不报错,只是不生效)`
);
} else {
ok(`${page} 的 import map 静态声明在 module 脚本之前`);
}
}
/* ---------------- 契约必须先于插件源码求值 ---------------- */
// ESM 按 import 声明顺序求值。插件源码一旦先跑,它的 register 就没有队列可落,
// 报出来的是「找不到 window.FunjiaPlugin」—— 看着像环境问题,其实是顺序问题。
const mainSourceFile = join(previewDir, "main-source.ts");
if (existsSync(mainSourceFile)) {
const text = readFileSync(mainSourceFile, "utf8");
const atContract = text.indexOf('"./contract"');
const atPlugin = text.indexOf('"../src/index"');
if (atContract < 0) {
bad("main-source.ts 没有 import ./contract —— 插件自注册会落空");
} else if (atPlugin >= 0 && atContract > atPlugin) {
bad(
"main-source.ts 里 ../src/index 排在 ./contract 之前 —— " +
"插件源码求值时契约还没装,会误报「找不到 window.FunjiaPlugin」"
);
} else {
ok("main-source.ts 先 import 契约、后 import 插件源码(顺序正确)");
}
}
/* ---------------- funjiaui 桩要覆盖实际用到的名字 ---------------- */
// 桩和用法脱节的代价很具体:预览里报 "does not provide an export named …",
// 而宿主里其实是好的 —— 白查一轮。所以在这里对齐。
const shimFile = join(previewDir, "shims/funjiaui.ts");
if (existsSync(shimFile)) {
const shimText = readFileSync(shimFile, "utf8");
const shimExports = new Set();
for (const m of shimText.matchAll(/export\s+(?:const|function|class)\s+([A-Za-z0-9_$]+)/g)) {
shimExports.add(m[1]);
}
for (const m of shimText.matchAll(/export\s*\{([^}]+)\}/g)) {
for (const part of m[1].split(",")) {
const name = part.trim().split(/\s+as\s+/).pop().trim();
if (name) shimExports.add(name);
}
}
const usedFromFunjiaui = new Set();
const collectFunjiauiUsage = (dir) => {
for (const name of readdirSync(dir)) {
const p = join(dir, name);
if (statSync(p).isDirectory()) {
collectFunjiauiUsage(p);
continue;
}
if (!/\.(ts|js|vue|tsx|jsx)$/.test(name)) continue;
const text = stripComments(readFileSync(p, "utf8"));
for (const m of text.matchAll(/import\s*(?:type\s*)?\{([^}]+)\}\s*from\s*["']funjiaui["']/g)) {
for (const part of m[1].split(",")) {
const nm = part.trim().split(/\s+as\s+/)[0].trim();
if (nm) usedFromFunjiaui.add(nm);
}
}
}
};
collectFunjiauiUsage(srcDir);
if (usedFromFunjiaui.size === 0) {
ok("源码没有 import funjiaui(预览桩仍在位,备用)");
} else {
const gaps = [...usedFromFunjiaui].filter((n) => !shimExports.has(n));
if (gaps.length > 0) {
bad(
`源码从 "funjiaui" 导入了预览桩里没有的名字:${gaps.join("、")} —— ` +
`预览会报「does not provide an export named」,请补进 preview/shims/funjiaui.ts`
);
} else {
ok(`源码用到的 ${usedFromFunjiaui.size} 个 funjiaui 导出都在预览桩里`);
}
}
}
/* ---------------- 接口契约:客户端与服务端必须共用一份 ---------------- */
//
// 预览的 `/api` 有两个实现方:`mock-api.ts`(服务端)与 `host.ts`(客户端)。
// 它们各写一份 `parseAuthHeader`、各写一份令牌前缀的话,「客户端以为令牌是
// `Bearer x`、服务端以为就是 `x`」这类错误**不会有任何编译错误** ——
// 只会表现为「登录成功但所有接口都 401」,而且要到接真后端时才暴露。
// 所以这里钉住:定义只能有一处,两侧都必须 import 它。
{
const contractFile = join(previewDir, "api-contract.ts");
const mockFile = join(previewDir, "mock-api.ts");
const hostFile = join(previewDir, "host.ts");
if (!existsSync(contractFile)) {
bad("找不到 preview/api-contract.ts —— 接口契约没有唯一真源,两侧会各自漂移");
} else {
const contractText = stripComments(readFileSync(contractFile, "utf8"));
// 契约里必须有的东西。少一个,某一侧就会自己补一份本地定义
const REQUIRED_EXPORTS = [
"TOKEN_KEY",
"USER_KEY",
"TOKEN_PREFIX",
"TOKEN_TTL_MS",
"UNAUTHORIZED_CODE",
"AUTH_EVENTS",
"parseAuthHeader",
];
const missingExports = REQUIRED_EXPORTS.filter(
(name) => !new RegExp(`export\\s+(?:const|function|interface|type)\\s+${name}\\b`).test(contractText)
);
if (missingExports.length > 0) {
bad(`api-contract.ts 缺少导出:${missingExports.join("、")}`);
} else {
ok(`接口契约导出了 ${REQUIRED_EXPORTS.length} 项关键定义(存储键 / 令牌 / 401 / 请求头解析)`);
}
// ⚠️ `UNAUTHORIZED_CODE` 必须是 **401**:它同时承担「业务码」与
// 「与 HTTP 状态码同值」两个角色,客户端那句 `code === 401` 才能一条覆盖两条路径。
const codeMatch = contractText.match(/UNAUTHORIZED_CODE\s*=\s*(\d+)/);
if (!codeMatch) {
bad("api-contract.ts 里找不到 UNAUTHORIZED_CODE 的取值");
} else if (codeMatch[1] !== "401") {
bad(
`UNAUTHORIZED_CODE 是 ${codeMatch[1]},必须是 401 —— ` +
`与 HTTP 状态码同值才能让客户端一条判断覆盖 mock 与真后端两条路径`
);
} else {
ok("UNAUTHORIZED_CODE = 401(与 HTTP 状态码同值)");
}
// 两侧都必须 import 契约,而不是各写各的
for (const [file, label] of [
[mockFile, "mock-api.ts(服务端)"],
[hostFile, "host.ts(客户端)"],
]) {
if (!existsSync(file)) continue;
const text = readFileSync(file, "utf8");
if (!/from\s+["']\.\/api-contract["']/.test(text)) {
bad(`${label} 没有从 ./api-contract 取契约 —— 这里会出现第二份定义`);
} else {
ok(`${label} 从 ./api-contract 取契约`);
}
// 本地再声明一遍 = 漂移的开始,直接拦掉
if (/\bfunction\s+parseAuthHeader\b/.test(stripComments(text))) {
bad(`${label} 自己又写了一份 parseAuthHeader —— 请求头的校验规则会出现两个版本`);
}
}
}
/* ---------------- 预览服务器要真的把后端接上 ---------------- */
const previewCfgText = existsSync(previewCfg) ? readFileSync(previewCfg, "utf8") : "";
if (!/createPreviewApi/.test(previewCfgText)) {
bad(
"vite.preview.config.ts 没有接上 createPreviewApi —— " +
"预览里 ctx.http 会 404,插件作者会以为是自己代码写错了"
);
} else {
ok("vite.preview.config.ts 已接上内置后端(/api 有应答)");
}
if (!/PREVIEW_API_TARGET/.test(previewCfgText)) {
warn("vite.preview.config.ts 里没有 PREVIEW_API_TARGET —— 预览无法切到真后端");
} else {
ok("vite.preview.config.ts 支持 PREVIEW_API_TARGET 代理到真后端");
}
}
}
/* ------------------------------------------------------------------ 汇总 */
console.log("");
console.log(
(errors === 0 ? "OK " : "FAIL ") +
`summary: ${errors} error(s), ${warnings} warning(s) (${cfg.id || "unknown"}@${cfg.version || "?"})`
);
process.exit(errors === 0 ? 0 : 1);