@oj-module/cli 0.2.66 → 0.2.68

package/src/cli.ts

@@ -130,6 +130,10 @@ function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code
 			};
 		case "build":
 			return async (opts: { bundle?: unknown, out?: string } = {}) => {
+				// 脚手架完整性门禁（内置模块自治契约）：普通与 --bundle 汇合前执行，
+				// 失败零产物——默认模块上游自治，本地修改不允许进包
+				const { assertDefaultModulesUntouched } = await import("./scaffold-guard");
+				assertDefaultModulesUntouched(projectRoot);
 				// mri 可选值：裸 --bundle 得到 ""，--bundle name / --bundle=name 得到字符串
 				const bundle = opts.bundle !== undefined;
 				const bundleName = typeof opts.bundle === "string" && opts.bundle !== "" ? opts.bundle : undefined;
@@ -223,9 +227,21 @@ function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code
 				await mergeManifests(out ?? "", inputs);
 			};
 		case "keygen":
-			return async (opts: { id?: string, out?: string, yes?: boolean } = {}) => {
-				const { keygenCommand } = await import("./keygen");
-				keygenCommand({ id: opts.id, out: opts.out, yes: opts.yes });
+			return async (opts: { id?: string, out?: string, yes?: boolean, credential?: string, siteUrl?: string } = {}) => {
+				const { exchangePublishCredential, keygenCommand } = await import("./keygen");
+				// 令牌解析：--credential > OJM_PUBLISH_CREDENTIAL；都没有则走原离线路径（逐字节不变）
+				const credential = (opts.credential ?? process.env.OJM_PUBLISH_CREDENTIAL ?? "").trim();
+				if (credential === "") {
+					keygenCommand({ id: opts.id, out: opts.out, yes: opts.yes });
+					return;
+				}
+				// 身份只来自凭证：--id 是另一条（离线）路径的入口，同时给必然有一方被静默忽略
+				if (opts.id !== undefined)
+					throw new UsageError("[ojm] --credential 与 --id 不能同时使用：凭证已绑定发布身份（要自定义身份请走离线 ojm keygen --id）");
+				const identity = await exchangePublishCredential(credential, { siteUrl: opts.siteUrl });
+				const who = identity.display_name === null ? identity.username : `${identity.display_name}（${identity.username}）`;
+				console.log(`[ojm] 凭证已兑换：产品 ${identity.product} / 申请人 ${who}`);
+				keygenCommand({ id: identity.key_id, out: opts.out, yes: opts.yes });
 			};
 		case "sign":
 			return async (file: string | undefined, opts: { id?: string, key?: string, check?: boolean, registryId?: string } = {}) => {
@@ -283,9 +299,9 @@ function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code
 					exit(EXIT_FAILURE);
 			};
 		case "install":
-			return async (target: string | undefined, opts: SiteOpts & { locale?: string, name?: string, version?: string, registry?: string } = {}) => {
+			return async (target: string | undefined, opts: SiteOpts & { locale?: string, name?: string, version?: string, registry?: string, force?: boolean } = {}) => {
 				const { installCommand } = await import("./install");
-				await installCommand(target ?? "", { siteUrl: opts.siteUrl, user: opts.user, pass: opts.pass, locale: opts.locale, name: opts.name, version: opts.version, registry: opts.registry });
+				await installCommand(target ?? "", { siteUrl: opts.siteUrl, user: opts.user, pass: opts.pass, locale: opts.locale, name: opts.name, version: opts.version, registry: opts.registry, force: opts.force });
 			};
 		case "list":
 			return async (opts: SiteOpts & { all?: boolean, json?: boolean } = {}) => {

package/src/dev.ts

@@ -230,12 +230,6 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 		proxyWsUpgrade(ojTarget)(req, socket, head);
 	});
 
-	// 退出回收：server 关闭 → SSE 通道 + oj 子进程一并回收
-	server.on("close", () => {
-		hub.close();
-		void oj?.stop();
-	});
-
 	// 终端 Ctrl+C / `kill`（SIGINT / SIGTERM）终止 dev 进程时，后端 oj 必须随之消亡：
 	// 起一个统一优雅停机，先停 oj 再退出；并打印后端终止信息。
 	// 终端 Ctrl-C 是进程组信号：外层 bin 转发一份 + 组送达一份，内层会收到
@@ -249,13 +243,24 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 		shuttingDown = true;
 		void shutdownDev(server, oj, hub);
 	};
-	process.on("SIGINT", shutdown);
-	process.on("SIGTERM", shutdown);
-
 	// 兜底：dev 进程以任何非优雅路径退出（未走 SIGINT/SIGTERM，如未捕获异常）时，
 	// 同步强杀 oj，确保它不孤儿化继续占端口（shutdownDev 已停则 kill 为 no-op）。
-	process.once("exit", () => {
+	const killOjOnExit = () => {
 		oj?.kill?.();
+	};
+	process.on("SIGINT", shutdown);
+	process.on("SIGTERM", shutdown);
+	process.once("exit", killOjOnExit);
+
+	// 退出回收：server 关闭 → SSE 通道 + oj 子进程一并回收，并摘除本实例注册的
+	// 进程级信号/exit handler。devServer 可在同一进程被多次调用（编程式 / 测试），
+	// 不摘除会累积闭包、触发 MaxListenersExceededWarning（与 preview 的 stop 同款）。
+	server.on("close", () => {
+		hub.close();
+		void oj?.stop();
+		process.removeListener("SIGINT", shutdown);
+		process.removeListener("SIGTERM", shutdown);
+		process.removeListener("exit", killOjOnExit);
 	});
 
 	// 端口被占用时自动顺延，避免 `EADDRINUSE` 直接让 `pnpm dev` 以非零码退出

package/src/init.ts

@@ -7,6 +7,8 @@
  *
  * 幂等补缺：对既有工程重跑只补缺失文件（bin/oj 已在则跳过下载，但先过 §7 能力闸门），
  * config.yaml 与用户文件永不覆盖——「重新 init 覆盖脚手架」是审阅记录二明令禁止的行为。
+ * 唯一例外是 `--yes`：默认方案的显式恢复入口，仅覆盖/清理上游自治的保护根
+ * （src/app、src/oj-market，见 scaffold-guard.ts），自定义模块与工程配置仍不动。
  */
 
 import { execFileSync } from "node:child_process";
@@ -14,18 +16,23 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
-import { fileURLToPath } from "node:url";
-import yaml from "yaml";
 import { ALIAS_PATHS_FILE, syncAliasPaths } from "./alias-paths";
 import { BUILTIN_LIST_FILE, writeBuiltinList } from "./builtin";
 import { resolveCertDir, resolveConfigPath } from "./layout";
 import { probeOjCaps } from "./oj-caps";
 import { mintDevCert } from "./oj-cert";
+import {
+	isProtectedRel,
+	readInitInclude,
+	removeExtraProtectedFiles,
+	cliRoot as resolveCliRoot,
+	templatesRoot,
+} from "./scaffold-guard";
 import { isSupportedOjVersion, MIN_OJ_VERSION, resolveOjBin, syncOjDevkit, vendorCommand } from "./vendor";
 import { readHostVersions } from "./versions";
 
 export interface InitOptions {
-	/** 跳过非空目录确认（自动化/测试用） */
+	/** 跳过非空目录确认（自动化/测试用）；对既有工程同时恢复上游自治的保护根 */
 	yes?: boolean
 	/** 注入桩 oj 安装器（测试）；默认 vendorCommand 经 npm 包 @oj-bin/oj 联网安装 */
 	ojInstaller?: (binDir: string) => Promise<void>
@@ -109,26 +116,34 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	}
 
 	const report: InitReport = { created: [], skipped: [], warnings: [] };
-	const cliRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+	const cliRoot = resolveCliRoot();
 
 	// 0) 已有 bin/oj 先过能力闸门（评审 BLOCKING #8）：早前「bin/oj 存在即跳过」
 	//    会让从旧工程带来的 0.1.84 静默过关，等 `ojm build` 才死在 --module-root 不认。
 	assertExistingOjUsable(destDir, report);
 
-	// 1) 模板（占位符替换 + 幂等跳过）
-	const templatesDir = path.join(cliRoot, "templates");
+	// 1) 模板（占位符替换 + 幂等跳过；--yes 时保护根内改为覆盖恢复）
+	const templatesDir = templatesRoot();
 	const jwtSecret = crypto.randomBytes(32).toString("hex");
 	const projectName = path.basename(destDir);
 	const include = readInitInclude(templatesDir);
 	copyTemplates(templatesDir, destDir, {
 		__JWT_SECRET__: jwtSecret,
 		__PROJECT_NAME__: projectName,
-	}, report, include, templatesDir);
+	}, report, include, templatesDir, false, !!opts.yes);
 	pruneUnincludedApiPaths(destDir, include, report);
 
+	// 1a') --yes 恢复的清理面：删除保护根内模板没有的文件（留着会让 build 门禁
+	//      永久失败——extra 漂移不因 init 补缺而消失，必须显式清掉）
+	if (opts.yes) {
+		for (const rel of removeExtraProtectedFiles(destDir))
+			report.created.push(`恢复：删除多出文件 ${rel}`);
+	}
+
 	// 1a) src/.ojm-builtin.json：脚手架自带模块身份（名单派生自上面的白名单，单一真源）。
-	//     copyIfAbsent：旧工程重跑 init 时缺失才补写，已存在不覆盖用户手改。
-	const builtinStatus = writeBuiltinList(destDir, include);
+	//     copyIfAbsent：旧工程重跑 init 时缺失才补写，已存在不覆盖用户手改；
+	//     --yes 恢复语义下重写为上游名单。
+	const builtinStatus = writeBuiltinList(destDir, include, { overwrite: !!opts.yes });
 	if (builtinStatus === "created")
 		report.created.push(`src/${BUILTIN_LIST_FILE}`);
 	else if (builtinStatus === "skipped")
@@ -317,6 +332,9 @@ async function sealJwtSecret(destDir: string, report: InitReport, seal: Sealer =
  * created/skipped（demo 模块/模板自运行产物/元数据的大头在清单外）。清单外的
  * 目录仅在「有收录子孙」时才穿行（如 `api/`、`web/src/`、`web/src/demo/`——
  * 只收录了后者底下的 entry/locales/pages），穿行时未收录的子项继续被挡下。
+ *
+ * `restore`（--yes）：上游自治保护根（scaffold-guard.PROTECTED_ROOTS）内的
+ * 已存在文件改为覆盖写入——这是默认方案的显式恢复入口，其余文件仍不覆盖。
  */
 function copyTemplates(
 	srcDir: string,
@@ -326,6 +344,7 @@ function copyTemplates(
 	include: Set<string>,
 	rootDir: string,
 	underIncluded = false,
+	restore = false,
 ): void {
 	for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
 		const src = path.join(srcDir, entry.name);
@@ -343,24 +362,36 @@ function copyTemplates(
 			if (!dirHasFiles(src))
 				continue;
 			fs.mkdirSync(dest, { recursive: true });
-			copyTemplates(src, dest, placeholders, report, include, rootDir, underIncluded || listed);
+			copyTemplates(src, dest, placeholders, report, include, rootDir, underIncluded || listed, restore);
 			continue;
 		}
+		// 恢复判定用 srcRel（模板相对 == 工程相对，已归一正斜杠）；destRel 是相对
+		// 当前递归层 destDir 的短路径，只配做报告标签，做不了保护根判定
 		const destRel = path.relative(destDir, dest);
 		if (fs.existsSync(dest)) {
+			if (restore && isProtectedRel(srcRel)) {
+				writeTemplateFile(src, dest, placeholders);
+				report.created.push(`恢复（--yes 覆盖）${srcRel}`);
+				continue;
+			}
 			report.skipped.push(destRel);
 			continue;
 		}
-		let content = fs.readFileSync(src, "utf-8");
-		for (const [token, value] of Object.entries(placeholders))
-			content = content.replaceAll(token, value);
-		content = stripRegion(content, "demo-only");
-		fs.mkdirSync(path.dirname(dest), { recursive: true });
-		fs.writeFileSync(dest, content);
+		writeTemplateFile(src, dest, placeholders);
 		report.created.push(destRel);
 	}
 }
 
+/** 读模板 → 占位符替换 → 剥 demo-only 区间 → 落盘（创建与 --yes 恢复共用一条变换链） */
+function writeTemplateFile(src: string, dest: string, placeholders: Record<string, string>): void {
+	let content = fs.readFileSync(src, "utf-8");
+	for (const [token, value] of Object.entries(placeholders))
+		content = content.replaceAll(token, value);
+	content = stripRegion(content, "demo-only");
+	fs.mkdirSync(path.dirname(dest), { recursive: true });
+	fs.writeFileSync(dest, content);
+}
+
 /** srcRel 是否为白名单里某条收录路径的祖先目录——决定清单外目录要不要穿行 */
 function hasIncludedDescendant(include: Set<string>, srcRel: string): boolean {
 	const prefix = `${srcRel}/`;
@@ -382,31 +413,6 @@ function dirHasFiles(dir: string): boolean {
 	return false;
 }
 
-/**
- * 读取模板根 `init.include.yaml` 的 `include` 白名单，归一为相对模板根的路径集合。
- * 清单随模板一起发布，缺失即安装包损坏——直接 fail-fast，不留「静默少拷」的
- * 退化路径。条目指向不存在的路径同样 fail-fast：拼错一个目录名不会当场报错，
- * 只会在用户工程里留下难以追溯的缺文件（旧 exclude 清单没有这类校验面）。
- */
-function readInitInclude(templatesDir: string): Set<string> {
-	const yamlPath = path.join(templatesDir, "init.include.yaml");
-	if (!fs.existsSync(yamlPath))
-		throw new Error(`模板缺少 init.include.yaml：${yamlPath}（安装包损坏？）`);
-	const doc = yaml.parse(fs.readFileSync(yamlPath, "utf-8")) as { include?: string[] } | null;
-	const out = new Set<string>();
-	for (const raw of doc?.include ?? []) {
-		// 跨平台：include 清单用正斜杠书写，但 path.normalize 在 Windows 会把
-		// 正斜杠折成反斜杠，导致与 srcRel（path.relative 在 Windows 同样出反斜杠）
-		// 的对比永远落空、整棵 src 子树被 skip。这里只把反斜杠归正、剥 ./ 前缀，
-		// 不引入平台分隔符（修复：Windows 下 init 不拷贝 src 树）。
-		const p = raw.replace(/\\/g, "/").replace(/^(\.\/)+/, "");
-		out.add(p);
-		if (!fs.existsSync(path.join(templatesDir, p)))
-			throw new Error(`init.include.yaml 收录了不存在的路径：${p}（拼写错误或模板缺文件？）`);
-	}
-	return out;
-}
-
 /**
  * 从脚手架产出的 openapi.json 里删掉未进白名单的 api 模块端点。
  *

package/src/install.ts

@@ -254,6 +254,11 @@ export interface InstallOptions {
 	locale?: string
 	/** REG-R9②：从指定 registry 源安装（白名单在服务端；旧站点 API < 0.2.0 不支持 → exit 1） */
 	registry?: string
+	/**
+	 * 强制重装配（oj 0.1.123+ reloadConfig(force)）：旁路「unchanged=已是最新装配」幂等短路，
+	 * 强制宿主重做一次装配。运维显式重装配用；缺省 false。
+	 */
+	force?: boolean
 	/** 测试注入；缺省 globalThis.fetch */
 	fetchFn?: typeof fetch
 	/** 测试注入；缺省真睡 */
@@ -269,6 +274,8 @@ export async function installCommand(target: string, opts: InstallOptions = {}):
 	const fetchFn = opts.fetchFn ?? globalThis.fetch;
 	const { base, user, pass } = resolveSite(opts);
 	const token = await login(fetchFn, base, user, pass);
+	// force 透传（oj 0.1.123+ reloadConfig(force) 逃逸舱）：仅运维显式重装配时用；常规安装走锁 diff
+	const forceQ = opts.force === true ? "?force=1" : "";
 
 	let response: { task_id: string };
 	if (opts.registry !== undefined) {
@@ -282,13 +289,13 @@ export async function installCommand(target: string, opts: InstallOptions = {}):
 		if (!isSiteApiAtLeast(meta.apiVersion, "0.2.0"))
 			throw new Error(`[ojm] 目标站点平台 API 版本过低（需 ≥ 0.2.0 才支持 --registry 源安装，实为 ${meta.apiVersion ?? "未知"}）——请升级目标站点的 oj-module，或改用 CDN/file 源`);
 		const registryOrigin = originOf(src.url) ?? src.url;
-		response = await callApi<{ task_id: string }>(fetchFn, base, token, "POST", "/api/_platform/market/install", {
+		response = await callApi<{ task_id: string }>(fetchFn, base, token, "POST", `/api/_platform/market/install${forceQ}`, {
 			name: slug,
 			version: opts.version ?? version,
 			source: "registry",
 			registry: registryOrigin,
 		});
-		console.log(`[ojm] 已从 registry 源提交安装任务（源 ${registryOrigin}，物理名 ${slug}）`);
+		console.log(`[ojm] 已从 registry 源提交安装任务（源 ${registryOrigin}，物理名 ${slug}${opts.force === true ? "，强制重装配" : ""}）`);
 	}
 	else {
 		const parsed = parseTarget(target);
@@ -314,7 +321,7 @@ export async function installCommand(target: string, opts: InstallOptions = {}):
 			else {
 				console.log(`[ojm] 未发现签名侧车（${path.basename(sigPath)}）——宿主验签硬 fail-closed，未签名包将被拒（sig_missing）；签名方法见 devkit「签名与信任」`);
 			}
-			const res = await fetchFn(`${base}/api/_platform/market/install`, {
+			const res = await fetchFn(`${base}/api/_platform/market/install${forceQ}`, {
 				method: "POST",
 				headers: { authorization: `Bearer ${token}`, ...tenantHeaders() },
 				body: form,
@@ -324,7 +331,7 @@ export async function installCommand(target: string, opts: InstallOptions = {}):
 		else {
 			if (opts.name !== undefined && opts.name !== parsed.name)
 				throw new Error(`[ojm] --name「${opts.name}」与目标「${parsed.name}」不一致——请二选一`);
-			response = await callApi<{ task_id: string }>(fetchFn, base, token, "POST", "/api/_platform/market/install", {
+			response = await callApi<{ task_id: string }>(fetchFn, base, token, "POST", `/api/_platform/market/install${forceQ}`, {
 				name: parsed.name,
 				version: opts.version ?? parsed.version,
 				source: "cdn",

package/src/keygen.ts

@@ -10,6 +10,7 @@ import path from "node:path";
 import process from "node:process";
 import { generateKeyPair } from "./lifecycle/keygen";
 import { fingerprintOfPublicKey } from "./lifecycle/sign";
+import { DEFAULT_SITE_URL, tenantHeaders, unwrapEnvelope } from "./site";
 
 export interface KeygenOptions {
 	/** 发布方 key_id（C2-37：<publisher>.<id> 全小写，禁裸通用名） */
@@ -67,3 +68,56 @@ export function keygenCommand(opts: KeygenOptions = {}): KeygenResult {
 	console.log(`[ojm] 下一步：ojm sign <pkg>.tgz --id ${keyId}（或 --key ${privateKeyPath} --id ${keyId}）`);
 	return { keyId, publicKeyHex: kp.publicKeyHex, fingerprint, dir, privateKeyPath, publicKeyPath };
 }
+
+/** 兑换结果：服务端下发身份（CLI 零推导——编码规则只在 templates 侧一份） */
+export interface ExchangedIdentity {
+	key_id: string
+	product: string
+	username: string
+	display_name: string | null
+}
+
+export interface ExchangeOptions {
+	/** 站点地址；flag > OJM_SITE_URL > DEFAULT_SITE_URL */
+	siteUrl?: string
+	/** 测试注入 */
+	fetchFn?: typeof fetch
+}
+
+/**
+ * 用一次性发布凭证换身份（匿名端点，不需要账号密码）。
+ *
+ * 只做「取回服务端算好的 key_id」——不做任何编码推导（规则漂移比多一次网络请求贵得多），
+ * 但**必须**校验拿回的 key_id 形状：它马上会被拼进 `~/.ojm/keys/<key_id>`，
+ * 一个被中间人改成 `../../x` 的响应就是任意路径写入。失败一律不落盘（调用方先兑换后生成）。
+ */
+export async function exchangePublishCredential(token: string, opts: ExchangeOptions = {}): Promise<ExchangedIdentity> {
+	const t = token.trim();
+	// 形状先挡：不是 64 位 hex 的输入连请求都不必发（与页面生成规则一致）
+	if (!/^[0-9a-f]{64}$/i.test(t))
+		throw new Error("[ojm] 发布凭证格式不对（应为 64 位十六进制）：请在站点「发布管理」页复制完整凭证");
+
+	const base = (opts.siteUrl ?? process.env.OJM_SITE_URL ?? DEFAULT_SITE_URL).replace(/\/+$/, "");
+	const fetchFn = opts.fetchFn ?? fetch;
+	let res: Response;
+	try {
+		res = await fetchFn(`${base}/api/publish/credential/exchange`, {
+			method: "POST",
+			headers: { "content-type": "application/json", ...tenantHeaders() },
+			body: JSON.stringify({ token: t }),
+		});
+	}
+	catch (e) {
+		throw new Error(`[ojm] 无法连接站点 ${base}：${e instanceof Error ? e.message : String(e)}——请确认站点地址（--site-url / OJM_SITE_URL）与网络`);
+	}
+	const data = await unwrapEnvelope(res) as Partial<ExchangedIdentity> | null;
+	const keyId = String(data?.key_id ?? "");
+	if (!isValidKeyId(keyId))
+		throw new Error(`[ojm] 站点返回的 key_id 非法（C2-37）：「${keyId}」——已中止，未写入任何密钥（请核对站点版本）`);
+	return {
+		key_id: keyId,
+		product: String(data?.product ?? ""),
+		username: String(data?.username ?? ""),
+		display_name: data?.display_name == null ? null : String(data.display_name),
+	};
+}

package/src/lifecycle/__tests__/bundle.test.ts

@@ -53,8 +53,8 @@ function makePrebuiltArtifacts(): void {
 	const apiDist = join(project, "dist/api/demo-solution-0.1.0");
 	mkdirSync(join(apiDist, "ping"), { recursive: true });
 	mkdirSync(join(apiDist, "migrations"), { recursive: true });
-	writeFileSync(join(apiDist, "manifest.yaml"), "name: demo-solution\ndesc: manifest.yaml 契约全字段合法夹具\nversion: 0.1.0\ntables:\n  - note\n");
-	writeFileSync(join(apiDist, "schema.yaml"), "tables:\n  note: {}\n");
+	writeFileSync(join(apiDist, "manifest.yaml"), "name: demo-solution\ndesc: manifest.yaml 契约全字段合法夹具\nversion: 0.1.0\ntables:\n  - demo_solution_note\n");
+	writeFileSync(join(apiDist, "schema.yaml"), "prefix: demo_solution_\ntables:\n  demo_solution_note: {}\n");
 	writeFileSync(join(apiDist, "routes.js"), "export {};\n");
 	writeFileSync(join(apiDist, "ping/api.js"), "export async function ping() {}\n");
 	// 站点构建产物（dist/web/modules/<name>/<version>/entry.js + css，对应 web.entry/css 声明）
@@ -317,11 +317,29 @@ describe("buildBundle · 校验先于打包（fail-fast）", () => {
 
 	it("c2-12a：api.tables 与 schema.yaml 表集不一致 → 构建期拒绝", async () => {
 		const m = readManifest();
-		m.api.tables = ["note", "ghost"];
+		m.api.tables = ["demo_solution_note", "ghost"];
 		writeManifest(m);
 		await expect(pack()).rejects.toThrow(/C2-12a/);
 	});
 
+	it("c2-12c：schema.yaml 缺 prefix / 表名未带方案前缀 → 构建期拒绝", async () => {
+		const schemaPath = join(project, "api/src/demo-solution/schema.yaml");
+		writeFileSync(schemaPath, "tables:\n  demo_solution_note: {}\n");
+		await expect(pack()).rejects.toThrow(/C2-12c.*prefix/);
+
+		writeFileSync(schemaPath, "prefix: demo_solution_\ntables:\n  note: {}\n");
+		await expect(pack()).rejects.toThrow(/C2-12c.*demo_solution_note/);
+	});
+
+	it("c2-12c：prefix 落在第一方保留段 → 构建期拒绝", async () => {
+		const m = readManifest();
+		m.api.tables = ["oj_note"];
+		writeManifest(m);
+		const schemaPath = join(project, "api/src/demo-solution/schema.yaml");
+		writeFileSync(schemaPath, "prefix: oj_\ntables:\n  oj_note: {}\n");
+		await expect(pack()).rejects.toThrow(/C2-12c.*保留段/);
+	});
+
 	it("c2-25：locales 缺引用 key → 构建期 fail-fast", async () => {
 		const m = readManifest();
 		m.roles[0].title_key = "demo-solution:role.absent";

package/src/lifecycle/__tests__/fixtures/fixture-valid/api/src/demo-solution/manifest.yaml

@@ -6,4 +6,4 @@ name: demo-solution
 desc: manifest.yaml 契约全字段合法夹具
 version: 0.1.0
 tables:
-  - note
+  - demo_solution_note

package/src/lifecycle/__tests__/fixtures/fixture-valid/api/src/demo-solution/migrations/0001__init.sql

@@ -1,5 +1,5 @@
--- 0001__init：建 note 表（与 schema.yaml 列集一致；oj migrate 按 seq 升序执行）
-CREATE TABLE IF NOT EXISTS note (
+-- 0001__init：建 demo_solution_note 表（与 schema.yaml 列集一致；oj migrate 按 seq 升序执行）
+CREATE TABLE IF NOT EXISTS demo_solution_note (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   title TEXT NOT NULL,
   create_time INTEGER NOT NULL

package/src/lifecycle/__tests__/fixtures/fixture-valid/api/src/demo-solution/schema.yaml

@@ -1,7 +1,10 @@
 # 声明式表结构（形态对齐 apps/playground-oj/api/src/demo/schema.yaml）。
-# 契约 C2-12：bundle manifest 的 api.tables 必须与本表 keys 一致（oj 冗余校验 fail-fast）。
+# C2-12c：prefix 必须 = 模块名 kebab→snake 再补尾部 `_`（demo-solution → demo_solution_），
+# 且每张表名以它开头——表名全库共享，前缀把归属编码进名字，避免方案之间撞表。
+prefix: demo_solution_
+# 契约 C2-12a：bundle manifest 的 api.tables 必须与本表 keys 一致（oj 冗余校验 fail-fast）。
 tables:
-  note:
+  demo_solution_note:
     pk: id
     columns:
       id: {type: integer, autoincrement: true}

package/src/lifecycle/__tests__/fixtures/fixture-valid/manifest.yaml

@@ -26,7 +26,7 @@ peerPlatform: '>=0.1.0' # C2-11（P2 起对宿主 API_VERSION 强制；本仓 AP
 api:
   module: demo-solution # C2-12（存在时必须 === name）
   prefix: /api/demo-solution # C2-13（默认形态显式写出）
-  tables: [note] # 与 schema.yaml 表集一致（oj 冗余校验同源）
+  tables: [demo_solution_note] # 与 schema.yaml 表集一致（oj 冗余校验同源）；表名带 C2-12c 前缀
   deps: # 键 = 模块名（C2-01 语法或 _platform）；值 = 范围算子语法
     _platform: '>=0.1.0'
   anonymous: # C2-26：首段 === 模块段；无登录语义端点

package/src/lifecycle/__tests__/manifest-contract.test.ts

@@ -14,7 +14,7 @@ import { parse } from "yaml";
 // 跨端引用（双端一致钉）：被测实现同仓分居两运行时（计划 §1「两运行时取舍」），
 // 测试直接互调，比「两套件各读同一夹具」更强——漂移即本文件红。
 import { preflight } from "../../../templates/src/app/api/_platform/_lifecycle/steps/preflight";
-import { checkLocalesComplete, checkTablesAgainstSchema, parseManifest, RESERVED_NAMES, reservedNameSuggestions, validateContract } from "../../manifest-contract";
+import { checkLocalesComplete, checkSchemaTablePrefix, checkTablesAgainstSchema, parseManifest, RESERVED_NAMES, reservedNameSuggestions, validateContract } from "../../manifest-contract";
 
 const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), "fixtures");
 const readText = (p: string) => readFileSync(join(FIXTURES, p), "utf8");
@@ -214,19 +214,91 @@ describe("rEG-CS7 保留名扩项（红队 F5）", () => {
 describe("checkTablesAgainstSchema（C2-12a：构建 ✅ 对照 schema.yaml）", () => {
 	const SCHEMA = readText("fixture-valid/api/src/demo-solution/schema.yaml");
 
-	it("fixture-valid tables [note] 与 schema.yaml 表集一致 → 零违规", () => {
+	it("fixture-valid tables 与 schema.yaml 表集一致 → 零违规", () => {
 		expect(checkTablesAgainstSchema(structuredClone(VALID), SCHEMA)).toEqual([]);
 	});
 
 	it("tables 与 schema.yaml 表集不一致 → C2-12a 且指明差额", () => {
 		const m = structuredClone(VALID);
-		(m.api as any).tables = ["note", "ghost"];
+		(m.api as any).tables = ["demo_solution_note", "ghost"];
 		const v = checkTablesAgainstSchema(m, SCHEMA);
 		expect(v[0]).toContain("C2-12a");
 		expect(v[0]).toContain("ghost");
 	});
 });
 
+describe("checkSchemaTablePrefix（C2-12c：schema.yaml 表前缀）", () => {
+	const SCHEMA = readText("fixture-valid/api/src/demo-solution/schema.yaml");
+
+	it("fixture-valid 声明 prefix 且表名带前缀 → 零违规", () => {
+		expect(checkSchemaTablePrefix(SCHEMA)).toEqual([]);
+	});
+
+	it("允许自选短前缀（长模块名可用 crm_ 之类，不强制由模块名派生）", () => {
+		expect(checkSchemaTablePrefix("prefix: dm_\ntables:\n  dm_note: {}\n")).toEqual([]);
+	});
+
+	it("缺 prefix → C2-12c", () => {
+		const v = checkSchemaTablePrefix("tables:\n  demo_solution_note: {}\n");
+		expect(v[0]).toContain("C2-12c");
+		expect(v[0]).toContain("prefix");
+	});
+
+	it("prefix 不以 _ 结尾 → C2-12c 语法违规", () => {
+		const v = checkSchemaTablePrefix("prefix: demo_solution\ntables:\n  demo_solution_note: {}\n");
+		expect(v[0]).toContain("C2-12c");
+		expect(v[0]).toContain("_ 结尾");
+	});
+
+	it("prefix 超过 32 字符 → C2-12c（吃掉表名可用空间）", () => {
+		const long = `${"a".repeat(33)}_`;
+		const v = checkSchemaTablePrefix(`prefix: ${long}\ntables:\n  ${long}note: {}\n`);
+		expect(v[0]).toContain("C2-12c");
+		expect(v[0]).toContain("超过上限 32");
+	});
+
+	it("表名未带前缀 → C2-12c 并给出改名建议", () => {
+		const v = checkSchemaTablePrefix("prefix: demo_solution_\ntables:\n  note: {}\n");
+		expect(v[0]).toContain("C2-12c");
+		expect(v[0]).toContain("demo_solution_note");
+	});
+
+	it("表名总长边界：63 合法、64 拒绝（PostgreSQL 上限 63 字节）", () => {
+		const p = "ab_";
+		const name63 = `${p}${"c".repeat(60)}`; // 3 + 60 = 63
+		const name64 = `${p}${"c".repeat(61)}`; // 3 + 61 = 64
+		expect(name63.length).toBe(63);
+		expect(checkSchemaTablePrefix(`prefix: ${p}\ntables:\n  ${name63}: {}\n`)).toEqual([]);
+		const v = checkSchemaTablePrefix(`prefix: ${p}\ntables:\n  ${name64}: {}\n`);
+		expect(v[0]).toContain("C2-12c");
+		expect(v[0]).toContain("63 字符");
+	});
+
+	it("引用式方案（api.tables 缺省）也做前缀检查", () => {
+		const m = structuredClone(VALID);
+		delete (m.api as any).tables;
+		const v = checkTablesAgainstSchema(m, "tables:\n  note: {}\n");
+		expect(v[0]).toContain("C2-12c");
+	});
+
+	it("prefix 落在第一方保留段（oj_ / ojm_ 开头）→ C2-12c，整段禁用含派生形式", () => {
+		for (const p of ["oj_", "ojm_", "oj_crm_", "ojm_tools_"]) {
+			const v = checkSchemaTablePrefix(`prefix: ${p}\ntables:\n  ${p}note: {}\n`);
+			expect(v.some(x => x.includes("C2-12c") && x.includes("保留段"))).toBe(true);
+		}
+	});
+
+	it("自有前缀不落在保留段 → 零违规（保留段检查的对照）", () => {
+		expect(checkSchemaTablePrefix("prefix: crm_\ntables:\n  crm_note: {}\n")).toEqual([]);
+	});
+
+	it("_oj_ 因下划线开头只报语法违规，不重复报保留段", () => {
+		const v = checkSchemaTablePrefix("prefix: _oj_\ntables:\n  _oj_note: {}\n");
+		expect(v[0]).toContain("必须匹配");
+		expect(v.every(x => !x.includes("保留段"))).toBe(true);
+	});
+});
+
 describe("checkLocalesComplete（C2-25：构建期缺 key fail-fast）", () => {
 	const ZH = readText("fixture-valid/web/src/demo-solution/locales/zh-CN.json");
 	const EN = readText("fixture-valid/web/src/demo-solution/locales/en-US.json");

package/src/lifecycle/__tests__/smoke.test.ts

@@ -37,11 +37,11 @@ describe.skipIf(!smokeReady)("真机冒烟（需 OJM_SMOKE_URL/OJM_SMOKE_USER/OJ
 		const apiDist = join(project, "dist/api/demo-solution-0.1.0");
 		const { mkdirSync, writeFileSync } = await import("node:fs");
 		mkdirSync(join(apiDist, "ping"), { recursive: true });
-		// 迁移 SQL 随夹具 src 真源（0001__init.sql 建 note 表）；B-11 硬验收：appliedSeq > 0 可断言
+		// 迁移 SQL 随夹具 src 真源（0001__init.sql 建 demo_solution_note 表）；B-11 硬验收：appliedSeq > 0 可断言
 		cpSync(join(FIXTURE_VALID, "api/src/demo-solution/migrations"), join(apiDist, "migrations"), { recursive: true });
 		// schema.yaml 同随夹具真源（列集与迁移 SQL 一致）：oj migrate 在 apply 后跑 schema
 		// reconcile（migrate_cmd.rs migrate_one），声明缺列而实库多列 = Err——合成空列集会炸
-		writeFileSync(join(apiDist, "manifest.yaml"), "name: demo-solution\ndesc: manifest.yaml 契约全字段合法夹具\nversion: 0.1.0\ntables:\n  - note\n");
+		writeFileSync(join(apiDist, "manifest.yaml"), "name: demo-solution\ndesc: manifest.yaml 契约全字段合法夹具\nversion: 0.1.0\ntables:\n  - demo_solution_note\n");
 		cpSync(join(FIXTURE_VALID, "api/src/demo-solution/schema.yaml"), join(apiDist, "schema.yaml"));
 		writeFileSync(join(apiDist, "routes.js"), "export {};\n");
 		writeFileSync(join(apiDist, "ping/api.js"), "export async function ping() {}\n");