@oj-module/cli 0.2.54 → 0.2.57

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oj-module/cli",
   "type": "module",
-  "version": "0.2.54",
+  "version": "0.2.57",
   "description": "React Antd 模块工程命令行工具（含预构建宿主 shell-dist）",
   "license": "MIT",
   "exports": {
@@ -49,7 +49,7 @@
   ],
   "dependencies": {
     "@faker-js/faker": "^10.4.0",
-    "@oj-module/runtime": "0.2.54",
+    "@oj-module/runtime": "0.2.57",
     "@redocly/cli": "^2.51.0",
     "@tailwindcss/vite": "^4.3.0",
     "cac": "^6.7.14",

package/shell-dist/assets/{index-e_Mp2mb5.js → index-CImwskAz.js}

@@ -276,9 +276,30 @@ function buildShellChildren() {
 * 路由表；随后 SPA 登录（不刷新页面）菜单回来了，但 /system/* 仍不在路由表里，
 * 直达恒落 catch-all 404「返回首页」，须硬刷新才恢复。
 */
+/**
+* 宿主路由根（Boot 建表与登录后重登记共用同一形状，children 按当前角色快照生成）。
+*
+* 路由根只渲染容器（Outlet），整站 chrome 由模块自带的 ContainerLayout 提供；
+* 宿主不叠加自己的 Layout chrome，避免「宿主侧栏 + 模块侧栏」双层嵌套。
+* element 里同时挂 LayoutEffects（暗色类/动态标题/NProgress，与 App 链同源，偏差 4）
+* 与页面级 ErrorBoundary（模块路由不经 runtime LayoutRoot，缺它时渲染抛错整页白屏）。
+*/
+function buildShellRoot() {
+	return {
+		path: "/",
+		id: SHELL_ROOT_ID,
+		element: /* @__PURE__ */ jsxs(ErrorBoundary, {
+			FallbackComponent: PageError,
+			children: [/* @__PURE__ */ jsx(LayoutEffects, {}), /* @__PURE__ */ jsx(Outlet, {})]
+		}),
+		children: buildShellChildren()
+	};
+}
 function repatchShellRoutes() {
 	if (!shellRouter) return;
-	shellRouter.patchRoutes(SHELL_ROOT_ID, buildShellChildren());
+	const internal = shellRouter._internalSetRoutes;
+	if (internal) internal.call(shellRouter, [buildShellRoot()]);
+	else shellRouter.patchRoutes(SHELL_ROOT_ID, buildShellChildren());
 	const { pathname, search } = shellRouter.state.location;
 	shellRouter.navigate(`${pathname}${search}`, { replace: true }).catch(() => {});
 }
@@ -313,7 +334,7 @@ function Boot() {
 		(async () => {
 			try {
 				if (typeof navigator !== "undefined" && /wxwork/i.test(navigator.userAgent) && location.pathname.endsWith("/login") && !new URLSearchParams(location.search).get("wecom_ticket")) {
-					window.location.assign(resolveApiBase() + "/auth/wecom/login");
+					window.location.assign(`${resolveApiBase()}/auth/wecom/login`);
 					return;
 				}
 				ensureI18n();
@@ -348,15 +369,7 @@ function Boot() {
 				await hydrateUser();
 				await loadAll(manifest);
 				if (cancelled) return;
-				shellRouter = createBrowserRouter([{
-					path: "/",
-					id: SHELL_ROOT_ID,
-					element: /* @__PURE__ */ jsxs(ErrorBoundary, {
-						FallbackComponent: PageError,
-						children: [/* @__PURE__ */ jsx(LayoutEffects, {}), /* @__PURE__ */ jsx(Outlet, {})]
-					}),
-					children: buildShellChildren()
-				}], { 
+				shellRouter = createBrowserRouter([buildShellRoot()], { 
 				/**
 				* 子路径部署（oj `mounts: [{ prefix: /oj, web: dist, spa: true }]`）：
 				* 不设 basename 时 react-router 看到的是含前缀的 `/oj/wiki/...`，

package/shell-dist/assets/runtime.js

@@ -304,10 +304,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.2.54",
+			"version": "0.2.57",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-11-02 18:04:24"
+		"lastBuildTime": "2026-11-03 11:30:53"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));
@@ -365,9 +365,9 @@ var init_preferences$3 = __esmMin((() => {
 		accordion: true,
 		enableFooter: true,
 		fixedFooter: true,
-		companyName: "Condor Hero",
-		companyWebsite: "http://github.com/condorheroblog/",
-		copyrightDate: "2023",
+		companyName: "Omni Solution",
+		companyWebsite: "http://github.com/everpan",
+		copyrightDate: "2026",
 		ICPNumber: "",
 		ICPLink: ""
 	};

package/shell-dist/index.html

@@ -5,8 +5,8 @@
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<link rel="icon" href="/favicon.ico" />
 		<title>React Antd Admin · Shell</title>
-		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-Php0JD1/JaEf2vFUnNnXaQ=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
-		<script type="importmap" nonce="Php0JD1/JaEf2vFUnNnXaQ==">{
+		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-p8IkoQDMiluaMnE2ANd5og=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
+		<script type="importmap" nonce="p8IkoQDMiluaMnE2ANd5og==">{
   "imports": {
     "react": "/assets/react.js",
     "react/jsx-runtime": "/assets/jsx-runtime.js",
@@ -130,7 +130,7 @@
 			.boot-skeleton:after{content:"";width:18px;height:18px;margin-left:8px;border:2px solid #d9d9d9;border-top-color:#1677ff;border-radius:50%;animation:bs-spin .8s linear infinite}
 			@keyframes bs-spin{to{transform:rotate(360deg)}}
 		</style>
-		<script nonce="Php0JD1/JaEf2vFUnNnXaQ==" data-ojm-entry="/assets/index-e_Mp2mb5.js">(function(){try{var ua=(navigator.userAgent||"").toLowerCase(),p=location.pathname;while(p.length>1&&p.charAt(p.length-1)==="/")p=p.slice(0,-1);if(ua.indexOf("wxwork")>=0&&p.slice(-6)==="/login"&&!new URLSearchParams(location.search).get("wecom_ticket")){var a=(typeof window.__OJ_API_BASE__==="string"&&window.__OJ_API_BASE__.trim())||"/api";while(a.length>1&&a.charAt(a.length-1)==="/")a=a.slice(0,-1);location.replace(a+"/auth/wecom/login");return}}catch(e){}var s=document.createElement("script");s.type="module";s.src=document.currentScript.getAttribute("data-ojm-entry");document.head.appendChild(s);})();</script>
+		<script nonce="p8IkoQDMiluaMnE2ANd5og==" data-ojm-entry="/assets/index-CImwskAz.js">(function(){try{var ua=(navigator.userAgent||"").toLowerCase(),p=location.pathname;while(p.length>1&&p.charAt(p.length-1)==="/")p=p.slice(0,-1);if(ua.indexOf("wxwork")>=0&&p.slice(-6)==="/login"&&!new URLSearchParams(location.search).get("wecom_ticket")){var a=(typeof window.__OJ_API_BASE__==="string"&&window.__OJ_API_BASE__.trim())||"/api";while(a.length>1&&a.charAt(a.length-1)==="/")a=a.slice(0,-1);location.replace(a+"/auth/wecom/login");return}}catch(e){}var s=document.createElement("script");s.type="module";s.src=document.currentScript.getAttribute("data-ojm-entry");document.head.appendChild(s);})();</script>
 	</head>
 	<body>
 		<div id="root"><div class="boot-skeleton">加载中…</div></div>

package/shell-dist/versions.json

@@ -7,9 +7,9 @@
   "react-router": "7.18.2",
   "react-router/dom": "7.18.2",
   "@tanstack/react-query": "5.102.8",
-  "@oj-module/runtime": "0.2.54",
-  "@oj-module/runtime/contract": "0.2.54",
-  "@oj-module/runtime/contract/errors": "0.2.54",
+  "@oj-module/runtime": "0.2.57",
+  "@oj-module/runtime/contract": "0.2.57",
+  "@oj-module/runtime/contract/errors": "0.2.57",
   "@plane/kit": "0.1.20",
   "@plane/editor": "0.1.20",
   "antd": "6.6.1",

package/src/__tests__/layout.test.ts

@@ -111,7 +111,7 @@ describe("resolveLayout / 历史布局", () => {
 	it("web/<name>/entry.ts 识别为 flat，web 产物落 build/（框架根仓约定不变），api 产物归 dist/api", () => {
 		const root = newRoot();
 		writeFile(root, "web/home/entry.ts", "export default {};\n");
-		writeFile(root, "web/home/__client/api.ts", "export {};\n");
+		writeFile(root, "web/home/__client/index.ts", "export {};\n");
 
 		const layout = resolveLayout(root);
 		expect(layout.kind).toBe("flat");
@@ -177,3 +177,32 @@ describe("路径取值函数", () => {
 		expect(webSrcOf(layout, "wiki")).toBe(join(layout.modulesSrc, "wiki", "web"));
 	});
 });
+
+/**
+ * 聚合容器：src/app 同时有 web 侧（多根前端模块）与 api 下多个后端模块。
+ * 模块身份取 api 下那层目录名（= URL 前缀），与平铺 src/<name>/api 并存且互不干扰。
+ */
+describe("resolveLayout / 聚合容器（src/app/api/<name>）", () => {
+	it("api 子目录各自成模块，web 侧仍是 app 模块", () => {
+		const root = newRoot();
+		writeFile(root, "src/app/api/system/manifest.yaml", "name: system\nversion: 0.1.0\n");
+		writeFile(root, "src/app/api/system/users/api.ts", "export default { get() {} };\n");
+		writeFile(root, "src/app/api/notification/manifest.yaml", "name: notification\nversion: 0.1.0\n");
+		writeFile(root, "src/app/web/entry.ts", "export default {};\n");
+		const layout = resolveLayout(root);
+		const mods = scanModules(layout);
+
+		expect(mods.map(m => m.name)).toEqual(["app", "notification", "system"]);
+		expect(mods.find(m => m.name === "system")?.apiSrc).toBe(join(root, "src/app/api/system"));
+		expect(mods.find(m => m.name === "system")?.webSrc).toBeUndefined();
+		expect(apiSrcOf(layout, "system")).toBe(join(root, "src/app/api/system"));
+		expect(webSrcOf(layout, "app")).toBe(join(root, "src/app/web"));
+	});
+
+	it("同名后端模块重复（旧 src/system/api + 新 src/app/api/system）→ 明确报错", () => {
+		const root = newRoot();
+		writeFile(root, "src/system/api/manifest.yaml", "name: system\nversion: 0.1.0\n");
+		writeFile(root, "src/app/api/system/manifest.yaml", "name: system\nversion: 0.1.0\n");
+		expect(() => resolveLayout(root)).toThrowError(/模块名重复：system/);
+	});
+});

package/src/__tests__/templates-schema-columns.test.ts

@@ -0,0 +1,99 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { parse } from "yaml";
+
+/**
+ * BDD：模板后端「迁移落库的列」必须在所属模块 schema.yaml 的列白名单里声明。
+ *
+ * 为什么要这条：oj 的 SQL 构造器是二进制内的 Rust 实现，select/insert/update 的列会**先**按
+ * schema.yaml 校验，列在库里但不在白名单时，SQL 还没发就被拒成
+ * `unknown column 'x' in <site>`（site 随语句位置变：join on / insert values / update sets …）。
+ * 线上表现是端点 500、日志里没有 SQL，看起来像「列不存在」，实际是声明漏了。
+ *
+ * 真实事故（2026-11）：_platform 0017 加了 users.employee_no，schema.yaml 漏声明，
+ * /system/departments（选人列表依赖 /system/users）整页 500。
+ *
+ * 校验面取 `ALTER TABLE … ADD COLUMN`：已有表新增列的唯一入口，也是最容易「只写迁移、
+ * 忘了补声明」的一类。整表声明由 t-2（租户定性）与表数快照兜底。
+ */
+
+const templatesRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../templates");
+const srcRoot = join(templatesRoot, "src");
+
+interface ColumnDecl {
+	type?: string
+	[key: string]: unknown
+}
+
+interface SchemaDoc {
+	tables?: Record<string, { columns?: Record<string, ColumnDecl> }>
+}
+
+/** `ALTER TABLE <表> ADD [COLUMN] <列>`（忽略方言专属文件，sqlite 基础件是唯一真相） */
+const ADD_COLUMN_RE = /ALTER\s+TABLE\s+[`"']?(\w+)[`"']?\s+ADD\s+(?:COLUMN\s+)?[`"']?(\w+)[`"']?/gi;
+
+function walk(dir: string, out: string[] = []): string[] {
+	for (const entry of readdirSync(dir)) {
+		const full = join(dir, entry);
+		if (statSync(full).isDirectory())
+			walk(full, out);
+		else
+			out.push(full);
+	}
+	return out;
+}
+
+/** 表名 → 声明的列集合（跨模块同名表由 templates-tenant-scope 的 S002 断言拦，这里取并集） */
+function loadDeclaredColumns(files: string[]): Map<string, Set<string>> {
+	const declared = new Map<string, Set<string>>();
+	for (const file of files.filter(f => f.endsWith("schema.yaml"))) {
+		const doc = parse(readFileSync(file, "utf-8")) as SchemaDoc | null;
+		for (const [table, decl] of Object.entries(doc?.tables ?? {}))
+			declared.set(table, new Set(Object.keys(decl.columns ?? {})));
+	}
+	return declared;
+}
+
+/** 基础迁移文件：`migrations/*.sql`，排除 `<名>.mysql.sql` / `<名>.pg.sql` */
+function isBaseMigration(file: string): boolean {
+	return /[/\\]migrations[/\\][^/\\]+\.sql$/.test(file) && !/\.(?:mysql|pg)\.sql$/.test(file);
+}
+
+describe("templates 后端 schema.yaml 列白名单", () => {
+	it("s-1 迁移里 ADD COLUMN 的列都在 schema.yaml 有声明（漏声明 = 构造器拒查）", () => {
+		const files = walk(srcRoot);
+		const declared = loadDeclaredColumns(files);
+		const violations: string[] = [];
+
+		for (const file of files.filter(isBaseMigration)) {
+			for (const m of readFileSync(file, "utf-8").matchAll(ADD_COLUMN_RE)) {
+				const [, table, column] = m;
+				const where = relative(templatesRoot, file);
+				const cols = declared.get(table);
+				if (!cols) {
+					violations.push(`${where}: 表 ${table} 未在任何 schema.yaml 声明`);
+					continue;
+				}
+				if (!cols.has(column)) {
+					violations.push(
+						`${where}: ${table}.${column} 未在 schema.yaml 声明`
+						+ `（构造器会拒为 unknown column '${column}' in on '${table}'；补到 owning 模块的 tables.${table}.columns）`,
+					);
+				}
+			}
+		}
+
+		expect(violations).toEqual([]);
+	});
+
+	it("s-2 回归锚点：0017 三方言迁移齐备，users.employee_no 已声明为 text", () => {
+		const migDir = join(srcRoot, "app", "api", "_platform", "migrations");
+		for (const file of ["0017__users_employee_no.sql", "0017__users_employee_no.mysql.sql", "0017__users_employee_no.pg.sql"])
+			expect(existsSync(join(migDir, file)), `缺迁移 ${file}`).toBe(true);
+
+		const schema = parse(readFileSync(join(srcRoot, "app", "api", "_platform", "schema.yaml"), "utf-8")) as SchemaDoc;
+		expect(schema.tables?.users?.columns?.employee_no).toMatchObject({ type: "text" });
+	});
+});

package/src/__tests__/vendor-devkit.test.ts

@@ -0,0 +1,87 @@
+// BDD：devkit 全链路落地与文档同步（计划 docs/plans/20261103-1020-vendor-devkit-sync）。
+// vendor 装/升 oj 后把 bin/devkit 文档**覆盖同步**进 .claude/skills/oj-api-dev/（R2/R3/R4）；
+// init 步骤 4 走同一出口（R5，global.d.ts 模板变体保护）；ojm devkit 4b 现状回归（R1）。
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { initProject } from "../init";
+import { syncOjDevkit } from "../vendor";
+
+/* eslint-disable test/prefer-lowercase-title -- 计划编号是验收锚点 */
+let root: string;
+
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "ojm-devkit-sync-"));
+});
+
+afterEach(() => {
+	rmSync(root, { recursive: true, force: true });
+});
+
+/** 模拟 @oj-bin/oj postinstall 落盘的 bin/devkit（版本标记进内容以断言覆盖方向） */
+function makeDevkit(version: string, dir = join(root, "bin", "devkit")): void {
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(join(dir, "SKILL.md"), `# oj-api-dev skill ${version}\n`);
+	writeFileSync(join(dir, "api-manual.md"), `manual ${version}\n`);
+	// 旧 init 清单之外的文件——按目录扫描（R6）应收进来
+	writeFileSync(join(dir, "scenarios.md"), `scenarios ${version}\n`);
+	writeFileSync(join(dir, "global.d.ts"), `// devkit ${version}\n`);
+}
+
+const skillOf = (name: string) => join(root, ".claude/skills/oj-api-dev", name);
+
+describe("syncOjDevkit（vendor/init 共用同步出口）", () => {
+	it("R2/R6 bin/devkit 齐备 → 全部 .md 同步进 skill 目录（含旧清单外文件；global.d.ts 不进）", () => {
+		makeDevkit("v2");
+		const r = syncOjDevkit(root, join(root, "bin"), () => {});
+		expect(r.ok).toBe(true);
+		expect(r.files.sort()).toEqual(["SKILL.md", "api-manual.md", "scenarios.md"]);
+		expect(readFileSync(skillOf("SKILL.md"), "utf-8")).toContain("v2");
+		expect(readFileSync(skillOf("scenarios.md"), "utf-8")).toContain("v2");
+		expect(existsSync(skillOf("global.d.ts"))).toBe(false);
+	});
+
+	it("R3 同步是覆盖语义：oj 升级后旧 skill 内容被当前版本刷新（非首拷赢）", () => {
+		makeDevkit("v1");
+		syncOjDevkit(root, join(root, "bin"), () => {});
+		writeFileSync(join(root, "bin", "devkit", "SKILL.md"), "# oj-api-dev skill v2\n");
+		syncOjDevkit(root, join(root, "bin"), () => {});
+		expect(readFileSync(skillOf("SKILL.md"), "utf-8")).toContain("v2");
+	});
+
+	it("R3 bin/devkit 缺 SKILL.md → ok:false，skill 目录不创建、不抛错", () => {
+		const r = syncOjDevkit(root, join(root, "bin"), () => {});
+		expect(r.ok).toBe(false);
+		expect(existsSync(join(root, ".claude/skills/oj-api-dev"))).toBe(false);
+	});
+});
+
+describe("ojm init 集成（注入 ojInstaller 模拟 vendor 落盘）", () => {
+	it("R1/R5 init 后两侧 skill 都在：oj devkit 同步 + ojm devkit 六文件", async () => {
+		await initProject(root, {
+			yes: true,
+			seal: async () => "ENC[test]",
+			ojInstaller: async (binDir) => {
+				makeDevkit("v1", join(binDir, "devkit"));
+			},
+		});
+		expect(readFileSync(join(root, ".claude/skills/oj-api-dev/SKILL.md"), "utf-8")).toBe("# oj-api-dev skill v1\n");
+		expect(existsSync(join(root, ".claude/skills/oj-api-dev/scenarios.md"))).toBe(true);
+		for (const name of ["SKILL.md", "manual.md", "README.md", "wecom-daikaifa.md", "wecom-internal-app.md", "publish-walkthrough.md"])
+			expect(existsSync(join(root, ".claude/skills/ojm-module-dev", name)), name).toBe(true);
+	});
+
+	it("R5 工程 global.d.ts 保模板变体：devkit 同名文件不覆盖（init/vendor 均不碰）", async () => {
+		await initProject(root, {
+			yes: true,
+			seal: async () => "ENC[test]",
+			ojInstaller: async (binDir) => {
+				makeDevkit("v1", join(binDir, "devkit"));
+			},
+		});
+		const rootGlobal = readFileSync(join(root, "global.d.ts"), "utf-8");
+		expect(rootGlobal).not.toContain("// devkit v1");
+		expect(rootGlobal).toContain(".route");
+	});
+});

package/src/alias-paths.ts

@@ -20,18 +20,18 @@ import type { ProjectLayout } from "./layout";
 import fs from "node:fs";
 import path from "node:path";
 import { parse } from "yaml";
-import { tryResolveLayout } from "./layout";
+import { scanModules, tryResolveLayout } from "./layout";
 
 /** 生成物文件名（工程根）。`src/tsconfig.json` 以 `../tsconfig.paths.json` 引用 */
 export const ALIAS_PATHS_FILE = "tsconfig.paths.json";
 
 /** 生成物头注释：tsconfig 允许注释，且这是唯一会被 `ojm` 覆写的 tsconfig */
 const HEADER = [
-	"// 由 ojm 生成：ojm init / ojm build / ojm dev 会按 src/*/api/manifest.yaml 重写本文件，请勿手改。",
+	"// 由 ojm 生成：ojm init / ojm build / ojm dev 会按模块清单重写本文件，请勿手改。",
 	"//",
-	"// oj 别名 `#/<模块名>/…` 锚在目标模块根（本布局下即 src/<模块名>/api）。tsconfig 的",
-	"// paths 只能静态全局映射，且每条规则的替换值只允许一个 `*`（`./src/*/api/*` 会被 TS",
-	"// 以 TS5062 拒掉），故按模块逐条枚举。",
+	"// oj 别名 `#/<模块名>/…` 锚在目标模块根（src/<模块名>/api 或 src/app/api/<模块名>）。",
+	"// tsconfig 的 paths 只能静态全局映射，且每条规则的替换值只允许一个 `*`（`./src/*/api/*`",
+	"// 会被 TS 以 TS5062 拒掉），故按模块逐条枚举。",
 ].join("\n");
 
 /** 读模块根 manifest 的 `name`（oj 的模块身份）；读不到/格式坏时回落到目录名 */
@@ -58,14 +58,13 @@ export function aliasPathEntries(layout: ProjectLayout): Record<string, string[]
 	if (layout.kind !== "module-root")
 		return {};
 	const entries: Record<string, string[]> = {};
-	for (const mod of fs.readdirSync(layout.modulesSrc, { withFileTypes: true })) {
-		if (!mod.isDirectory() || mod.name.startsWith("."))
+	// 以扫描结果为准：既覆盖平铺 src/<name>/api，也覆盖聚合容器 src/app/api/<name>
+	for (const mod of scanModules(layout)) {
+		if (!mod.apiSrc)
 			continue;
-		const apiDir = path.join(layout.modulesSrc, mod.name, "api");
-		if (!fs.existsSync(path.join(apiDir, "manifest.yaml")))
-			continue;
-		const name = manifestName(apiDir, mod.name);
-		entries[`#/${name}/*`] = [`./${path.posix.join("src", mod.name, "api", "*")}`];
+		const name = manifestName(mod.apiSrc, mod.name);
+		const rel = path.relative(layout.projectRoot, mod.apiSrc).split(path.sep).join("/");
+		entries[`#/${name}/*`] = [`./${rel}/*`];
 	}
 	return entries;
 }

package/src/build/backend.ts

@@ -0,0 +1,131 @@
+// 后端构建编排（SRP 拆分自 build.ts，2026-11-03，计划 docs/plans/20261103-0930）：
+// 编排 `bin/oj build` 生成 api/dist 产物——别名投影、能力闸门、密封值试解、
+// 宿主 versions.json 双落点都在这一段，前端构建见 module-build.ts。
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { ALIAS_PATHS_FILE, syncAliasPaths } from "../alias-paths";
+import { resolveConfigPath, tryResolveLayout } from "../layout";
+import { requireModuleRootCapability } from "../oj-caps";
+import { resolveOjBin } from "../vendor";
+import { resolveShellDist } from "../versions";
+
+/**
+ * 构建后端（api/src 存在时编排 `bin/oj build`，D8）。
+ *
+ * 绝不在此处跑 migrate：oj build 本身零磁盘副作用，`ojm build` 保持零 DB
+ * 副作用（CI/无 DB 环境可跑）；迁移由 preview 在起服务前应用（设计 §6）。
+ * 无后端源码返回 false（纯前端工程跳过）。
+ */
+export async function buildBackend(projectRoot: string): Promise<boolean> {
+	// 没有模块源码的工程（如 market 的隔离站点根）直接跳过——不能因为探测不到布局就抛
+	const layout = tryResolveLayout(projectRoot);
+	const moduleRoot = layout?.kind === "module-root";
+	const apiSrc = moduleRoot
+		? layout.modulesSrc
+		: path.join(projectRoot, "api/src");
+	if (!fs.existsSync(apiSrc))
+		return false;
+
+	const oj = resolveOjBin(projectRoot);
+	if (!fs.existsSync(oj)) {
+		throw new Error(
+			`[ojm] 找到 ${path.relative(projectRoot, apiSrc) || "."} 但缺少 ${oj}。\n`
+			+ "请重跑 ojm init 幂等补缺（不会覆盖 config 与用户代码）。",
+		);
+	}
+	// 能力闸门先于任何写入：失败时磁盘上不留半成品
+	if (moduleRoot)
+		requireModuleRootCapability(projectRoot);
+
+	// 别名投影：模块增删后要让 TS 的 paths 跟上（否则 `#/<模块名>/…` 在编辑器/typecheck
+	// 里解析不到，退化成 any）。内容未变不写盘。
+	const syncedPaths = syncAliasPaths(projectRoot);
+	if (syncedPaths === "created" || syncedPaths === "updated")
+		console.log(`[ojm] 已${syncedPaths === "created" ? "生成" : "更新"} ${ALIAS_PATHS_FILE}（\`#/<模块名>/…\` 的 TS paths 投影）`);
+
+	const apiDist = layout?.apiDist ?? path.join(projectRoot, "dist", "api");
+	console.log("[ojm] oj build（后端）…");
+	// 必须显式给 -c：oj build 的 -c 缺省是 ./config.yaml（相对 CWD），而 config 在
+	// <project>/config/ 下——漏传会静默读不到配置，连带 tasks 镜像目录回落默认 "tasks"、
+	// sql_guard 声明校验不生效（oj 只 warn 两行，极易被忽略）。
+	const configPath = resolveConfigPath(projectRoot);
+	const configArgs = fs.existsSync(configPath) ? ["-c", configPath] : [];
+	// --no-minify：oj 的 swc minify 当前会把产物压坏，必须绕开。实测两种坏法：
+	//   1) `const rows = await db.query(...); rows[0]` → 压成 `await db.query(...)[0]`，
+	//      下标先于 await 求值，Promise 上取 [0] 得 undefined（登录恒 401）；
+	//   2) `if (cond) x = y` → 压成 `cond && x = y`，赋值作 && 右项缺括号 →
+	//      SyntaxError: Invalid left-hand side in assignment（端点 500）。
+	// 0.1.32 / 0.1.50 均复现。产物体积换正确性，等上游修好再撤这个旗标。
+	// v0.1.85：`--module-root <dir>` 与 `-d` 互斥（都是「源码树根」）。新布局给 src，
+	// oj 在子树内递归找 manifest.yaml（命中 src/<name>/api/manifest.yaml 即停）。
+	const sourceArgs = layout?.moduleRoot ? ["--module-root", layout.moduleRoot] : ["-d", apiSrc];
+	// 出包前先自己确认 config 能读：读不动时 oj build 会静默关掉 sql_guard（见函数注释）
+	if (configArgs.length)
+		assertSealedValuesOpenable(oj, configPath);
+	execFileSync(oj, [
+		"build",
+		...configArgs,
+		...sourceArgs,
+		"-o",
+		apiDist,
+		"--no-minify",
+	], { stdio: "inherit" });
+	// 宿主 versions.json 双落点：站点壳从 shell-dist 拷进 dist/web（mergeShellSite），
+	// 而方案安装器读的是 `dist/api/versions.json`（B-11：与 manifests.yaml 同层，用于
+	// peerRuntime 强制比对）。两处必须同源，否则新工程 `ojm build` 完仍装不上方案——
+	// preflight 直接 C2-09 fail-closed「无法读取宿主 runtime 版本」。
+	const versionsSrc = path.join(resolveShellDist(), "versions.json");
+	if (fs.existsSync(versionsSrc)) {
+		fs.mkdirSync(apiDist, { recursive: true });
+		fs.copyFileSync(versionsSrc, path.join(apiDist, "versions.json"));
+	}
+	return true;
+}
+
+/**
+ * config 里的密封值（`oj secret seal` 产物）在 build 前试解一把——fail-closed。
+ *
+ * **为什么不能只信 oj 的 warn**：实测（oj 0.1.115）config 读不动时 `oj build` **退出码仍是 0**，
+ * 只往 stderr 甩两行「读配置失败 → 镜像目录回落默认 tasks / 本次 build 按 sql_guard=off 处理」，
+ * 然后照常出包。那两行夹在模块清单里极易被忽略，而关掉的 `sql_guard` 正是 tenant 声明校验
+ * （跨模块 SQL 的唯一守卫）——包看起来完好，检查其实没跑。
+ *
+ * 探法就是 oj 自己的排障命令 `oj secret open`：它和 `oj serve` / `oj build` 用同一套密钥解析
+ * （`OJ_SECRET_KEY` → `OJ_SECRET_KEY_FILE` → config 的 `secrets.private_key_path`），
+ * 解不开就非零退出。明文只可能出现在它的 stdout，这里直接丢弃，不落终端也不落日志。
+ */
+function assertSealedValuesOpenable(oj: string, configPath: string): void {
+	// 注释行不算：config 里留着注释掉的旧密文很常见，naive 匹配会让 build 因为一行 `#` 而失败
+	const live = fs.readFileSync(configPath, "utf-8")
+		.split("\n")
+		.filter(line => !line.trimStart().startsWith("#"))
+		.join("\n");
+	const sealed = [...new Set(live.match(/ENC\[[^\]\n]+\]/g) ?? [])];
+	for (const value of sealed) {
+		try {
+			execFileSync(oj, ["secret", "open", "-c", configPath, value], { stdio: ["ignore", "ignore", "pipe"] });
+		}
+		catch (e) {
+			const stderr = String((e as { stderr?: unknown }).stderr ?? "").trim();
+			const detail = stderr || (e as Error).message;
+			throw new Error(
+				`[ojm] config 里的密封值解不开，已停在出包前：${configPath}\n`
+				+ `      oj 说：${detail}\n`
+				+ "\n"
+				+ "不能放行：oj build 遇到读不动的 config 不会失败（退出码 0），只 warn 两行就继续——\n"
+				+ "tasks 镜像目录回落默认值，sql_guard（tenant 声明校验）直接关掉。那种包看着正常，\n"
+				+ "跨模块 SQL 的守卫却没跑过。\n"
+				+ "\n"
+				+ "两类原因，都修得了：\n"
+				+ "  1) 本机加载的私钥与密封时用的公钥不是一对——最常见是换机器/换部署目录时只带了\n"
+				+ "     config.yaml，没带 config/secrets-private.pem；\n"
+				+ "  2) 密文被改过——手工编辑、复制被截断、编辑器把长行折了。\n"
+				+ "\n"
+				+ "单独验一条：oj secret open -c <config> '<那个 ENC[...] 值>'（成功=这条没问题，失败=就是它）\n"
+				+ "修法：把配对私钥带到本机（OJ_SECRET_KEY / OJ_SECRET_KEY_FILE / config 的 secrets.private_key_path\n"
+				+ "      三选一）；密钥确实换了，就在本机重新 oj secret seal 覆写该值（明文走 stdin，别上命令行）。",
+			);
+		}
+	}
+}