@oj-module/cli 0.2.18 → 0.2.20

package/src/init.ts

@@ -1,12 +1,12 @@
 /**
  * `ojm init` —— 前后端一体化工程脚手架（设计 §3，D1/D3/D6/D10）。
  *
- * 产物：api/（oj 后端 + seed）、config/（config.yaml + 现场签发证书，与 api/、web/ 同级）、
- * web/src/（前端模块）、bin/（从 everpan/only-js 最新 release 联网下载：oj + plugins + devkit）、
- * 工程配置文件。
+ * 产物（布局 `src/<name>/{api,web}`）：src/（模块源码单树）、config.yaml + config/（现场签发证书）、
+ * seed.*.sql / tests / vitest.config.ts（后端工程面，与 config.yaml 同级）、
+ * bin/（从 everpan/only-js 最新 release 联网下载：oj + plugins + devkit）、工程配置文件。
  *
- * 幂等补缺：对既有工程重跑只补缺失文件（bin/oj 已在则跳过下载），config.yaml 与
- * 用户文件永不覆盖——「重新 init 覆盖脚手架」是审阅记录二明令禁止的行为。
+ * 幂等补缺：对既有工程重跑只补缺失文件（bin/oj 已在则跳过下载，但先过 §7 能力闸门），
+ * config.yaml 与用户文件永不覆盖——「重新 init 覆盖脚手架」是审阅记录二明令禁止的行为。
  */
 
 import { execFileSync } from "node:child_process";
@@ -16,9 +16,11 @@ 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 { resolveCertDir, resolveConfigPath } from "./layout";
+import { probeOjCaps } from "./oj-caps";
 import { mintDevCert } from "./oj-cert";
-import { resolveOjBin, vendorCommand } from "./vendor";
+import { isSupportedOjVersion, MIN_OJ_VERSION, resolveOjBin, vendorCommand } from "./vendor";
 import { readHostVersions } from "./versions";
 
 export interface InitOptions {
@@ -33,6 +35,7 @@ export interface InitOptions {
 interface InitReport {
 	created: string[]
 	skipped: string[]
+	warnings: string[]
 }
 
 /**
@@ -41,6 +44,59 @@ interface InitReport {
  */
 export type Sealer = (destDir: string, plainSecret: string) => Promise<string | null>;
 
+/**
+ * 既有 `bin/oj` 的能力预检（设计 §7「双探」；评审 BLOCKING #8）。
+ *
+ * 只查**已存在**的二进制：刚由 `vendorCommand` 装下的那份已被 `MIN_OJ_VERSION` 挡过一遍，
+ * 而「从别处拷来的旧二进制」正是这条闸门要拦的形态。
+ *
+ * 三档处置：
+ *   - `-V` 读不出版本（桩/损坏二进制）→ 告警放行，不阻断幂等补缺；
+ *   - 版本 < MIN_OJ_VERSION → 抛错（`ojm vendor --force` 可覆盖标记）；
+ *   - 版本够但 `--module-root` 缺失 → 抛错，这是「声明新、能力旧」的真实形态。
+ */
+function assertExistingOjUsable(destDir: string, report: InitReport): void {
+	const ojBin = resolveOjBin(destDir);
+	if (!fs.existsSync(ojBin))
+		return;
+
+	let printed: string;
+	try {
+		printed = execFileSync(ojBin, ["-V"], { encoding: "utf-8", timeout: 10_000 }).trim();
+	}
+	catch (error) {
+		report.warnings.push(`无法执行 ${ojBin} -V（${(error as Error).message}），跳过版本校验`);
+		return;
+	}
+
+	const version = /(\d+\.\d+\.\d+)/.exec(printed)?.[1];
+	if (!version) {
+		report.warnings.push(`无法解析 ${ojBin} -V 的输出（${printed || "空"}），跳过版本校验`);
+		return;
+	}
+	if (!isSupportedOjVersion(version)) {
+		throw new Error(
+			`[ojm] ${ojBin} 是 v${version}，低于 ojm 要求的最低版本 v${MIN_OJ_VERSION}。\n`
+			+ "原因：init 不再对已存在的 bin/oj 静默跳过——旧二进制生成的新布局工程会在 `ojm build` 时才失败。\n"
+			+ `处置：\`ojm vendor --force v${MIN_OJ_VERSION}\` 重装，或删除 ${ojBin} 后重跑 init。`,
+		);
+	}
+
+	try {
+		if (probeOjCaps(ojBin).moduleRoot)
+			return;
+	}
+	catch (error) {
+		report.warnings.push(`能力探针失败（${(error as Error).message}），跳过 --module-root 校验`);
+		return;
+	}
+	throw new Error(
+		`[ojm] ${ojBin}（v${version}）不接受 --module-root，无法支撑 src/<name>/{api,web} 布局。\n`
+		+ "原因：版本号是声明，能跑通才是事实——`oj build --help` 里没有该旗标。\n"
+		+ `处置：\`ojm vendor --force v${MIN_OJ_VERSION}\` 重装。`,
+	);
+}
+
 export async function initProject(destDir: string, opts: InitOptions = {}): Promise<void> {
 	fs.mkdirSync(destDir, { recursive: true });
 	const existing = fs.readdirSync(destDir);
@@ -51,9 +107,13 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 		);
 	}
 
-	const report: InitReport = { created: [], skipped: [] };
+	const report: InitReport = { created: [], skipped: [], warnings: [] };
 	const cliRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
 
+	// 0) 已有 bin/oj 先过能力闸门（评审 BLOCKING #8）：早前「bin/oj 存在即跳过」
+	//    会让从旧工程带来的 0.1.84 静默过关，等 `ojm build` 才死在 --module-root 不认。
+	assertExistingOjUsable(destDir, report);
+
 	// 1) 模板（占位符替换 + 幂等跳过）
 	const templatesDir = path.join(cliRoot, "templates");
 	const jwtSecret = crypto.randomBytes(32).toString("hex");
@@ -65,14 +125,21 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	}, report, include, templatesDir);
 	pruneUnincludedApiPaths(destDir, include, report);
 
-	// 2) 证书三件套（现场签发，D6）——落点即 resolveCertDir()（config.yaml 同级的 config/）
+	// 1b) tsconfig.paths.json：把 oj 别名 `#/<模块名>/…` 投影成 TS 的 paths。
+	//     必须**现场生成**而不是随模板拷贝——模板兼作 demo 工程（多出 demo/home 两个
+	//     模块），而用户工程只有白名单里的那些；照拷会让 paths 指向不存在的目录。
+	if (syncAliasPaths(destDir) === "created")
+		report.created.push(ALIAS_PATHS_FILE);
+
+	// 2) 证书三件套（现场签发，D6）——落点即 resolveCertDir()（config.yaml 同级的 config/；
+	//    新布局 config.yaml 在工程根，故为 <工程根>/config/）
 	const certDir = resolveCertDir(destDir);
 	if (fs.existsSync(path.join(certDir, "cert.jws"))) {
-		report.skipped.push("api/config/cert.jws");
+		report.skipped.push("config/cert.jws");
 	}
 	else {
 		await mintDevCert(certDir);
-		report.created.push("api/config/{private.pem,public.pem,cert.jws}");
+		report.created.push("config/{private.pem,public.pem,cert.jws}");
 	}
 
 	// 3) oj 二进制：从最新 release 联网下载（sha256 校验 → tar 解包 → chmod），
@@ -164,6 +231,8 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	console.log(`[ojm]   新增 ${report.created.length} 项，跳过（已存在）${report.skipped.length} 项`);
 	for (const item of report.skipped)
 		console.log(`[ojm]   · 跳过 ${item}`);
+	for (const item of report.warnings)
+		console.warn(`[ojm]   ! ${item}`);
 	console.log("[ojm] 下一步：pnpm install && pnpm dev（登录 admin / 123456）");
 }
 
@@ -213,7 +282,7 @@ async function sealJwtSecret(destDir: string, report: InitReport, seal: Sealer =
 	// secrets 段：私钥只放部署机，路径相对 config 目录（config.yaml 同级）
 	const withSecrets = `${next.trimEnd()}\nsecrets:\n  private_key_path: ./config/secrets-private.pem\n  public_key_path: ./config/secrets-public.pem\n`;
 	fs.writeFileSync(configPath, withSecrets);
-	report.created.push("api/config/{secrets-private.pem,secrets-public.pem} + auth.jwt_secret 已密封（ENC[...]）");
+	report.created.push("config/{secrets-private.pem,secrets-public.pem} + auth.jwt_secret 已密封（ENC[...]）");
 }
 
 /**
@@ -318,9 +387,10 @@ function pruneUnincludedApiPaths(destDir: string, include: Set<string>, report:
 	// 只裁本次新建的 openapi.json：init 是幂等补缺，不改动既有工程文件
 	if (!report.created.includes("openapi.json"))
 		return;
+	// 白名单里 `src/<name>/api` 这条（整模块收录）决定「脚手架有哪些后端模块」
 	const mods = new Set([...include]
-		.map(p => (p.startsWith("api/src/") ? p.slice("api/src/".length) : null))
-		.filter((m): m is string => !!m && !m.includes("/")));
+		.map(p => /^src\/([^/]+)\/api$/.exec(p)?.[1])
+		.filter((m): m is string => !!m));
 	if (mods.size === 0)
 		return;
 	const openapiPath = path.join(destDir, "openapi.json");
@@ -401,15 +471,15 @@ node_modules/
 bin/
 .ojm-tmp-*
 # ojm preview 的派生 config（临时产物，进程退出即删；见 preview-config.ts）
-api/.ojm-preview.yaml
-# 本地 sqlite 与运行日志
-api/db.sqlite
-api/db.sqlite-shm
-api/db.sqlite-wal
-api/logs/
+.ojm-preview.yaml
+# 本地 sqlite 与运行日志（config.yaml 在工程根，路径都相对工程根）
+db.sqlite
+db.sqlite-shm
+db.sqlite-wal
+logs/
 # 现场签发的开发证书与凭据私钥（ojm dev 缺证时自动签发，见 oj-cert.ts）；私钥绝不入仓
-api/config/*.pem
-api/config/cert.jws
+config/*.pem
+config/cert.jws
 # 构建产物
 api/dist/
 web/dist/

package/src/layout.ts

@@ -1,13 +1,24 @@
 /**
- * 模块工程布局探测（设计 D11，2026-09-11 硬切换）。
+ * 模块工程布局探测（设计 D11，2026-09-11 硬切换；2026-10 增补 module-root）。
  *
  * dev/build/preview 对「源码目录、产物目录、watch 目录」的全部路径取值
  * 一律经此模块，禁止各自手拼——布局分叉点收敛一处。
  *
- * 布局（uni-dev）：web/src/ + web/dist/（src/dist 同级配对）。
- * 框架根仓自身为平铺 web/<name>/（dogfooding，产物落 build/，不经 ojm）。
- * 硬切换只认 web/：存量 modules/ 工程不再探测，须迁移
- * （modules/ → web/，modules.config.ts → web.config.ts）。
+ * 三种布局（互斥）：
+ *   module-root  <project>/src/<name>/{api,web}   新布局：一目录一模块（设计 v2）
+ *   new           <project>/web/src/<name>        历史 uni-dev 布局
+ *   flat          <project>/web/<name>            框架根仓 dogfooding（产物落 build/）
+ *
+ * module-root 的判定只认「模块根标记文件」而不是单纯的 src/ 存在性：工程里
+ * 常有不属于模块的 src/（脚本、共享库），凭目录名猜会误判。
+ * `src/<x>/api/manifest.yaml` 与 `src/<x>/web/entry.ts` 是唯一真源（设计 C-6：
+ * 一侧可缺省，两侧皆无则不是模块）。
+ *
+ * 产物根在两套布局里语义相同、位置不变：
+ *   api/dist   oj 扁平 release 根（<name>-<version>/ 同层兄弟 + manifests.yaml）
+ *   web/dist   站点产物（shell + modules/ + modules.json）
+ * 产物按模块聚合已被设计 §2.2 否决（实证见该节），禁止在此引入第二套形状。
+ *
  * watch 目标绝不含产物目录：若 watch `web/`，重建产物（web/dist）
  * 会反过来触发重建，形成自触发循环（设计 §4）。
  */
@@ -15,40 +26,270 @@
 import fs from "node:fs";
 import path from "node:path";
 
+export type LayoutKind = "module-root" | "new" | "flat";
+
+/** 模块一侧的可缺省组合：两侧皆无不是模块（设计 C-6） */
+export interface ModuleSides {
+	name: string
+	/** 后端源码目录 `<project>/src/<name>/api`（无此侧为 undefined） */
+	apiSrc?: string
+	/** 前端源码目录 `<project>/src/<name>/web`（无此侧为 undefined） */
+	webSrc?: string
+}
+
 export interface ProjectLayout {
-	kind: "new" | "flat"
-	/** 模块源码目录（watch 与 build 的 entry 来源） */
+	kind: LayoutKind
+	projectRoot: string
+	/** 模块源码目录：module-root → `<project>/src`；new → `<project>/web/src`；flat → `<project>/web` */
 	modulesSrc: string
-	/** 产物目录：dev 写 modules.json + modules/；ojm build 合并全站于此 */
+	/** 站点产物根：module-root / new → `<project>/web/dist`；flat → `<project>/build` */
 	distDir: string
+	/** oj 扁平 release 根：恒为 `<project>/api/dist`（设计 C-3/C-7，不随布局变化） */
+	apiDist: string
 	/** fs.watch 目标（纯源码，永不落产物） */
 	watchTarget: string
+	/**
+	 * oj 的 `--module-root` 取值（源码树根目录），仅 module-root 有值。
+	 *
+	 * v0.1.85 语义：在**该目录的子树内递归**找 `manifest.yaml`，命中即停；模块身份取
+	 * manifest 的 `name`（目录名只作定位）。它与 `-d`/`--api-path` **互斥**——两者都是
+	 * 「源码树根」，同时给会被 clap 拒掉，所以调用方是二选一，不是「-d + 附加旗标」。
+	 */
+	moduleRoot?: string
 }
 
-export function resolveLayout(projectRoot: string): ProjectLayout {
-	if (fs.existsSync(path.join(projectRoot, "web/src"))) {
+function isDir(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	}
+	catch {
+		return false;
+	}
+}
+
+function isFile(p: string): boolean {
+	try {
+		return fs.statSync(p).isFile();
+	}
+	catch {
+		return false;
+	}
+}
+
+/**
+ * 扫描 module-root 布局的 `src/`：返回模块清单与「像模块但缺标记文件」的坏目录。
+ *
+ * 坏目录只在 module-root 被判定为当前布局后才报错（见 resolveLayout），
+ * 否则一个恰好带 `src/utils/api/` 的历史工程会被误伤。
+ */
+function scanModuleRoot(projectRoot: string): { modules: ModuleSides[], broken: string[] } | null {
+	const srcDir = path.join(projectRoot, "src");
+	if (!isDir(srcDir))
+		return null;
+
+	const modules: ModuleSides[] = [];
+	const broken: string[] = [];
+	// 按名字排序：readdir 的顺序取决于文件系统与创建历史（同一份源码在不同机器上可能不同），
+	// 而枚举顺序会进入构建顺序与产物内容——不排序则「同布局两次构建 sha256 相等」无法保证。
+	const entries = fs.readdirSync(srcDir, { withFileTypes: true })
+		.filter(ent => ent.isDirectory() && !ent.name.startsWith("."))
+		.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+	for (const ent of entries) {
+		const dir = path.join(srcDir, ent.name);
+		const apiDir = path.join(dir, "api");
+		const webDir = path.join(dir, "web");
+		const hasApi = isFile(path.join(apiDir, "manifest.yaml"));
+		const hasWeb = isFile(path.join(webDir, "entry.ts"));
+		if (!hasApi && !hasWeb) {
+			// 只把「有 api/ 或 web/ 子目录但缺标记」算坏目录；纯共享库目录（无两者）静默跳过
+			if (isDir(apiDir) || isDir(webDir))
+				broken.push(ent.name);
+			continue;
+		}
+		modules.push({
+			name: ent.name,
+			apiSrc: hasApi ? apiDir : undefined,
+			webSrc: hasWeb ? webDir : undefined,
+		});
+	}
+	return { modules, broken };
+}
+
+/** 历史布局：`web/src` 为 uni-dev 工程；`web/<name>/entry.ts` 为框架根仓 */
+function detectLegacyKind(projectRoot: string): LayoutKind | null {
+	if (isDir(path.join(projectRoot, "web", "src")))
+		return "new";
+	const webDir = path.join(projectRoot, "web");
+	if (isDir(webDir)) {
+		for (const ent of fs.readdirSync(webDir, { withFileTypes: true })) {
+			if (ent.isDirectory() && isFile(path.join(webDir, ent.name, "entry.ts")))
+				return "flat";
+		}
+	}
+	return null;
+}
+
+/**
+ * 探测布局；工程里没有任何模块源码时返回 null（供 `buildBackend` 这类「没有源码就
+ * 跳过」的调用方使用）。布局存在但**自相矛盾**（双树并存 / src 下有坏模块目录）仍抛错。
+ */
+export function tryResolveLayout(projectRoot: string): ProjectLayout | null {
+	const scanned = scanModuleRoot(projectRoot);
+	const isModuleRoot = !!scanned && scanned.modules.length > 0;
+	const legacyKind = detectLegacyKind(projectRoot);
+
+	// 互斥：两套源码树同时存在时静默选一个，会让 `ojm build` 构建 A 而 `ojm dev` 预览 B
+	if (isModuleRoot && legacyKind) {
+		throw new Error(
+			`[ojm] ${projectRoot} 同时存在两套模块源码树：src/<name>/{api,web} 与 `
+			+ `${legacyKind === "new" ? "web/src/<name>" : "web/<name>"}。\n`
+			+ "布局互斥，无法判断以哪套为准——请显式移除其中一套后重试。",
+		);
+	}
+
+	if (scanned && (isModuleRoot || legacyKind === null) && scanned.broken.length > 0) {
+		throw new Error(
+			`[ojm] ${projectRoot}/src 下这些目录既无 api/manifest.yaml 也无 web/entry.ts：\n${
+				scanned.broken.map(n => `  - src/${n}/`).join("\n")}\n`
+				+ "module-root 布局里一个目录 = 一个模块，至少需要其中一侧；"
+				+ "若这些目录不是模块（脚本、共享库），请移到 src/ 之外。",
+		);
+	}
+
+	if (isModuleRoot) {
+		return {
+			kind: "module-root",
+			projectRoot,
+			modulesSrc: path.join(projectRoot, "src"),
+			distDir: path.join(projectRoot, "web", "dist"),
+			apiDist: path.join(projectRoot, "api", "dist"),
+			watchTarget: path.join(projectRoot, "src"),
+			moduleRoot: path.join(projectRoot, "src"),
+		};
+	}
+
+	if (legacyKind === "new") {
 		return {
 			kind: "new",
-			modulesSrc: path.join(projectRoot, "web/src"),
-			distDir: path.join(projectRoot, "web/dist"),
-			watchTarget: path.join(projectRoot, "web/src"),
+			projectRoot,
+			modulesSrc: path.join(projectRoot, "web", "src"),
+			distDir: path.join(projectRoot, "web", "dist"),
+			apiDist: path.join(projectRoot, "api", "dist"),
+			watchTarget: path.join(projectRoot, "web", "src"),
 		};
 	}
+
 	// 框架根仓：平铺 web/<name>/（readModuleDefinition 的裸说明符扫描复用此探测，B10）
-	if (fs.existsSync(path.join(projectRoot, "web"))) {
+	if (legacyKind === "flat") {
 		return {
 			kind: "flat",
+			projectRoot,
 			modulesSrc: path.join(projectRoot, "web"),
 			distDir: path.join(projectRoot, "build"),
+			apiDist: path.join(projectRoot, "api", "dist"),
 			watchTarget: path.join(projectRoot, "web"),
 		};
 	}
+
+	return null;
+}
+
+export function resolveLayout(projectRoot: string): ProjectLayout {
+	const layout = tryResolveLayout(projectRoot);
+	if (layout)
+		return layout;
 	throw new Error(
-		`[ojm] ${projectRoot} 下未发现 web/——web 布局硬切换后只认 web/src + web/dist，`
+		`[ojm] ${projectRoot} 下未发现模块源码（硬切换后只认 web/src；2026-10 起也认 src/<name>/{api,web}）：\n`
+		+ "  - 新布局：src/<name>/{api/manifest.yaml 或 web/entry.ts}\n"
+		+ "  - 历史布局：web/src/<name>（uni-dev）或 web/<name>/entry.ts（框架根仓）\n"
 		+ "存量 modules/ 工程请迁移：modules/ → web/，modules.config.ts → web.config.ts。",
 	);
 }
 
+/**
+ * 枚举 module-root 布局的模块（设计 C-6：真源是标记文件，不是人工登记的 web.config.ts）。
+ * 历史布局的模块顺序由 `web.config.ts` 的 `modules` 决定，此处不适用。
+ */
+export function scanModules(layout: ProjectLayout): ModuleSides[] {
+	if (layout.kind !== "module-root")
+		throw new Error(`[ojm] scanModules 只适用于 module-root 布局，当前为 ${layout.kind}`);
+	return scanModuleRoot(layout.projectRoot)?.modules ?? [];
+}
+
+/** 契约工具的处理单元：模块名 + 该模块 api 侧目录（handler 目录镜像的根） */
+export interface ApiModuleRoot {
+	name: string
+	dir: string
+}
+
+/**
+ * 历史布局的模块 api 根：`<project>/api/src/<name>`。
+ *
+ * 单独导出是因为**纯后端工程**可能只有 `api/src` 而没有 `web/src`——`tryResolveLayout`
+ * 会返回 null，契约工具仍要能对账。
+ */
+export function legacyApiModuleRoots(projectRoot: string): ApiModuleRoot[] {
+	const root = path.join(projectRoot, "api", "src");
+	if (!isDir(root))
+		return [];
+	return fs.readdirSync(root, { withFileTypes: true })
+		.filter(entry => entry.isDirectory() && !entry.name.startsWith("."))
+		.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+		.map(entry => ({ name: entry.name, dir: path.join(root, entry.name) }));
+}
+
+/**
+ * 枚举后端模块的 api 根，供 `ojm api` 生成 / `--check` 对账**按模块**扫描。
+ *
+ * 为什么不直接 walk `apiModulesSrc(layout)`：module-root 布局的树根是 `src`，模块的
+ * api 侧在 `<src>/<name>/api`，中间那层 `api` 是**布局分隔符、不是路由段**。拿 `src`
+ * 当扫描根会双重出错——路由镜像多出 `api` 段（`system/api/users` ≠ 真实 `system/users`），
+ * 且 `src/<name>/web/__client/api.ts` 这种前端生成物也会被当 handler 扫进来。
+ *
+ * module-root → 按 `<name>/api/manifest.yaml` 判模块（与 build 同源，name 取 manifest）；
+ * 历史布局    → `<project>/api/src` 的一级目录即模块。
+ */
+export function apiModuleRoots(layout: ProjectLayout): ApiModuleRoot[] {
+	if (layout.kind !== "module-root")
+		return legacyApiModuleRoots(layout.projectRoot);
+	return scanModules(layout)
+		.filter((m): m is ModuleSides & { apiSrc: string } => !!m.apiSrc)
+		.map(m => ({ name: m.name, dir: m.apiSrc }));
+}
+
+/** `<project>/src/<name>` */
+export function moduleDir(layout: ProjectLayout, name: string): string {
+	return path.join(layout.modulesSrc, name);
+}
+
+/**
+ * 后端源码根。module-root 为 `<modulesSrc>/<name>/api`（模块的 api 侧目录）；
+ * 历史布局为 `<project>/api/src/<name>`——不在 modulesSrc 之下，必须走 projectRoot。
+ */
+export function apiSrcOf(layout: ProjectLayout, name: string): string {
+	return layout.kind === "module-root"
+		? path.join(layout.modulesSrc, name, "api")
+		: path.join(layout.projectRoot, "api", "src", name);
+}
+
+/**
+ * 后端源码的**根**目录：
+ *   module-root → `<project>/src`（oj 的 `--module-root` 取源码树根，模块在每层 api 子目录）
+ *   历史布局    → `<project>/api/src`（oj 的 `-d` / `--api-path` 取模块目录的父级）
+ */
+export function apiModulesSrc(layout: ProjectLayout): string {
+	return layout.kind === "module-root"
+		? layout.modulesSrc
+		: path.join(layout.projectRoot, "api", "src");
+}
+
+/** 前端源码目录（历史布局与模块目录同体） */
+export function webSrcOf(layout: ProjectLayout, name: string): string {
+	return layout.kind === "module-root"
+		? path.join(layout.modulesSrc, name, "web")
+		: path.join(layout.modulesSrc, name);
+}
+
 export function resolveWatchTarget(projectRoot: string): string {
 	return resolveLayout(projectRoot).watchTarget;
 }
@@ -56,21 +297,38 @@ export function resolveWatchTarget(projectRoot: string): string {
 /**
  * 定位工程 config.yaml。
  *
- * 唯一规范位置：`<project>/api/config.yaml`。
+ * 唯一规范位置由布局决定：
+ *   module-root → `<project>/config.yaml`
+ *   历史布局    → `<project>/api/config.yaml`
  *
- * 不能挪到与 api/ 同级的 config/ 目录：oj 的模块解析把「项目根」锚定在
- * **config 文件所在目录**，且相对 import 被钳制在该根内（devkit 手册第 5 章）。
- * config 一进 `config/` 子目录，`api/src` 就整体落到项目根之外，凡是带 `../`
- * 相对 import 的 handler（模板的 system/auth/_platform 依赖 `_shared/`）在
- * `ojm dev` 下会被判 `escapes project root` 而整条路由加载失败
- * （实测：26 个 api 文件 → 只剩 8 个，18 条路由被跳过）。
+ * module-root 下没有回退到 `api/config.yaml`：oj 把「项目根」锚定在 **config 文件所在目录**，
+ * 相对 import 被钳制在该根内（devkit 手册第 5 章）。源码搬到 `src/` 而 config 留在 `api/`
+ * 时，project root 收缩成 `<project>/api`，`src/` 整体落到根之外——凡是带 `../` 相对 import
+ * 的 handler 在 `ojm dev` 下会被判 `escapes project root` 而整条路由加载失败
+ * （实测：26 个 api 文件 → 只剩 8 个，18 条路由被跳过）。回退会把这个陷阱伪装成「能跑」。
  */
 export function resolveConfigPath(projectRoot: string): string {
-	return path.join(projectRoot, "api", "config.yaml");
+	const rootConfig = path.join(projectRoot, "config.yaml");
+	if (isFile(rootConfig))
+		return rootConfig;
+	const legacyConfig = path.join(projectRoot, "api", "config.yaml");
+	// 源码已是 module-root 但 config 还在 api/ ⇒ 迁移未完成。此时回退会踩上面那个陷阱，
+	// 且症状是「部分路由静默消失」，比直接失败更难排查。
+	if (isFile(legacyConfig) && (scanModuleRoot(projectRoot)?.modules.length ?? 0) > 0) {
+		throw new Error(
+			`[ojm] ${projectRoot} 已是 src/<name>/{api,web} 布局，但 config.yaml 仍在 api/ 下。\n`
+			+ `请移到 ${rootConfig}（证书目录随之变为 ${path.join(projectRoot, "config")}）。\n`
+			+ "oj 以 config 所在目录为 project root：config 留在 api/ 会把 src/ 甩到根外，"
+			+ "带 ../ 相对 import 的 handler 会被判 escapes project root 而整条路由不加载。",
+		);
+	}
+	return legacyConfig;
 }
 
 /**
- * 证书与密钥的唯一落点：`<project>/api/config/`（config.yaml 同级的 config/ 子目录）。
+ * 证书与密钥的唯一落点：config.yaml 同级的 `config/` 子目录。
+ *
+ * module-root → `<project>/config/`；历史布局 → `<project>/api/config/`。
  *
  * 三个入口都指向这里，别再各自手拼：
  *   ① `server.public_key_path`     → ./config/public.pem（oj 验签公钥）

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

@@ -2,7 +2,7 @@
 // 组装契约（对齐 tgz 内布局，契约 §2.9 + P1-9 staging copy 源定版）：
 //   <root>/manifest.yaml                          ← 必填，契约校验 fail-fast 先于打包
 //   api/dist/<name>-<version>/                    ← oj build 产物原样 → tgz 内 api/<name>-<version>/（C2-31 分层核对）
-//   web/dist/modules/                             ← 站点构建模块产物 → tgz 内 web/modules/（web.entry 存在性复核）
+//   web/dist/modules/<name>/                      ← 站点构建模块产物 → tgz 内 web/modules/<name>/（只入包方案自己的模块）
 // 禁携 modules.json（C2-31 红线）；产物确定性（C2-32）由 deterministic-tar 承担，此处断言端到端复现。
 import { execFileSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -64,6 +64,16 @@ describe("buildBundle · 正路径", () => {
 			expect(names, `缺成员 ${member}`).toContain(`demo-solution-0.1.0/${member}`);
 	});
 
+	it("只入包方案自己的前端模块：模板模块（home/login…）不随包", async () => {
+		// 安装器 deployWeb 把包内 web/modules 整树覆盖进目标站，模板产物随包会覆盖宿主同名前端
+		const hostWeb = join(project, "web/dist/modules/home/0.1.0");
+		mkdirSync(hostWeb, { recursive: true });
+		writeFileSync(join(hostWeb, "entry.js"), "export default {};\n");
+		const names = tarList((await pack()).tgz);
+		expect(names.some(n => n.includes("/web/modules/home/"))).toBe(false);
+		expect(names).toContain("demo-solution-0.1.0/web/modules/demo-solution/0.1.0/entry.js");
+	});
+
 	it("端到端确定性：同一工程两次打包 sha256 相等（C2-32）", async () => {
 		const r1 = await pack();
 		const r2 = await pack();
@@ -116,6 +126,11 @@ describe("buildBundle · 校验先于打包（fail-fast）", () => {
 		await expect(pack()).rejects.toThrow(/web\/dist\/modules/);
 	});
 
+	it("web/dist/modules 在但缺本方案目录 → 可读报错（不整树入包）", async () => {
+		rmSync(join(project, "web/dist/modules/demo-solution"), { recursive: true, force: true });
+		await expect(pack()).rejects.toThrow(/web\/dist\/modules\/demo-solution\//);
+	});
+
 	it("c2-12a：api.tables 与 schema.yaml 表集不一致 → 构建期拒绝", async () => {
 		const m = readManifest();
 		m.api.tables = ["note", "ghost"];

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

@@ -1,4 +1,4 @@
-import type { InstallContext } from "../../../templates/api/src/_platform/_lifecycle/steps/preflight";
+import type { InstallContext } from "../../../templates/src/_platform/api/_lifecycle/steps/preflight";
 
 // BDD：bundle 级 manifest.yaml 契约校验（P1-11，C2 规则构建列）。
 // 规则真源：docs/prd/solution/202610171254-lifecycle-manifest-contract.md（C2-01~33 构建列，§4.1 矩阵）；
@@ -13,7 +13,7 @@ import { describe, expect, it } from "vitest";
 import { parse } from "yaml";
 // 跨端引用（双端一致钉）：被测实现同仓分居两运行时（计划 §1「两运行时取舍」），
 // 测试直接互调，比「两套件各读同一夹具」更强——漂移即本文件红。
-import { preflight } from "../../../templates/api/src/_platform/_lifecycle/steps/preflight";
+import { preflight } from "../../../templates/src/_platform/api/_lifecycle/steps/preflight";
 import { checkLocalesComplete, checkTablesAgainstSchema, parseManifest, validateContract } from "../../manifest-contract";
 
 const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), "fixtures");