@oj-module/cli 0.2.18 → 0.2.20

package/src/__tests__/oj-caps.test.ts

@@ -0,0 +1,114 @@
+// oj 能力探针 spec：双探的第二探（设计 202610220010 §7）。
+//
+// 失败方式很隐蔽：能力缺失却在构建入口回落到旧布局，会得到「源码搬了、产物还是旧的」
+// 半坏状态。这里钉住三件事：解析只看整词旗标、缓存按二进制指纹失效、缺失即抛且带版本。
+import { mkdirSync, mkdtempSync, readFileSync, statSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { CAPS_FILE, probeOjCaps, readCapsCache, requireModuleRootCapability, writeCapsCache } from "../oj-caps";
+
+function newProject(): { root: string, ojBin: string } {
+	const root = mkdtempSync(join(tmpdir(), "ojm-caps-"));
+	mkdirSync(join(root, "bin"), { recursive: true });
+	const ojBin = join(root, "bin", "oj");
+	writeFileSync(ojBin, "#!/bin/sh\necho fake\n", { mode: 0o755 });
+	return { root, ojBin };
+}
+
+const HELP_WITH = "Options:\n  -d, --dir <DIR>  源码目录\n      --module-root <GLOB>  模块根 glob\n";
+const HELP_WITHOUT = "Options:\n  -d, --dir <DIR>  源码目录\n";
+
+describe("probeOjCaps", () => {
+	it("帮助里有 --module-root 即支持", () => {
+		const { ojBin } = newProject();
+		expect(probeOjCaps(ojBin, () => HELP_WITH).moduleRoot).toBe(true);
+	});
+
+	it("帮助里没有则不支持", () => {
+		const { ojBin } = newProject();
+		expect(probeOjCaps(ojBin, () => HELP_WITHOUT).moduleRoot).toBe(false);
+	});
+
+	it("同名前缀不算命中（--module-rooted 之类的说明文字）", () => {
+		const { ojBin } = newProject();
+		expect(probeOjCaps(ojBin, () => "--module-rooted 是别的意思\n").moduleRoot).toBe(false);
+	});
+
+	it("探测本身失败时报错带处置命令", () => {
+		const { ojBin } = newProject();
+		expect(() => probeOjCaps(ojBin, () => {
+			throw new Error("boom");
+		})).toThrow(/ojm vendor/);
+	});
+});
+
+describe("能力缓存", () => {
+	it("写入后能读回", () => {
+		const { ojBin } = newProject();
+		writeCapsCache(ojBin, { moduleRoot: true });
+		expect(readCapsCache(ojBin)).toEqual({ moduleRoot: true });
+	});
+
+	it("换二进制（size 变）后缓存失效", () => {
+		const { ojBin } = newProject();
+		writeCapsCache(ojBin, { moduleRoot: true });
+		writeFileSync(ojBin, "#!/bin/sh\necho replaced-and-longer\n", { mode: 0o755 });
+		expect(readCapsCache(ojBin)).toBeNull();
+	});
+
+	it("mtime 变（同尺寸手替）后缓存失效", () => {
+		const { ojBin } = newProject();
+		writeCapsCache(ojBin, { moduleRoot: true });
+		const future = new Date(Date.now() + 60_000);
+		utimesSync(ojBin, future, future);
+		expect(readCapsCache(ojBin)).toBeNull();
+	});
+
+	it("缓存文件损坏不影响主流程（视为未缓存）", () => {
+		const { root, ojBin } = newProject();
+		writeFileSync(join(root, "bin", CAPS_FILE), "{not json", "utf-8");
+		expect(readCapsCache(ojBin)).toBeNull();
+	});
+});
+
+describe("requireModuleRootCapability", () => {
+	it("支持时通过并落缓存，第二次不再探测", () => {
+		const { root } = newProject();
+		let calls = 0;
+		const run = () => {
+			calls += 1;
+			return HELP_WITH;
+		};
+		expect(requireModuleRootCapability(root, run).moduleRoot).toBe(true);
+		expect(requireModuleRootCapability(root, run).moduleRoot).toBe(true);
+		expect(calls).toBe(1);
+		expect(readFileSync(join(root, "bin", CAPS_FILE), "utf-8")).toContain("\"moduleRoot\": true");
+	});
+
+	it("二进制缺失时报错指向 ojm vendor", () => {
+		const { root } = newProject();
+		const run = () => HELP_WITH;
+		expect(() => requireModuleRootCapability(join(root, "nope"), run)).toThrow(/ojm vendor/);
+	});
+
+	it("能力缺失时抛错，文案含现场版本与两种处置", () => {
+		const { root } = newProject();
+		const run = (_bin: string, args: string[]) =>
+			args[0] === "-V" ? "oj 0.1.84\n" : HELP_WITHOUT;
+		expect(() => requireModuleRootCapability(root, run)).toThrow(/oj 0\.1\.84/);
+		expect(() => requireModuleRootCapability(root, run)).toThrow(/ojm vendor/);
+	});
+
+	it("能力缺失也写缓存（避免每次构建重探），换二进制后指纹变化自动重探", () => {
+		const { root, ojBin } = newProject();
+		expect(() => requireModuleRootCapability(root, (_b, args) => (args[0] === "-V" ? "oj 0.1.84" : HELP_WITHOUT))).toThrow();
+		expect(readCapsCache(ojBin)?.moduleRoot).toBe(false);
+		// 二进制更新后指纹变化 → 重探，能力补齐即放行
+		const before = statSync(ojBin).size;
+		writeFileSync(ojBin, "#!/bin/sh\necho upgraded\n", { mode: 0o755 });
+		expect(statSync(ojBin).size).not.toBe(before);
+		expect(requireModuleRootCapability(root, () => HELP_WITH).moduleRoot).toBe(true);
+	});
+});

package/src/alias-paths.ts

@@ -0,0 +1,102 @@
+/**
+ * oj 原生别名 `#/<模块名>/…` 在 TS 侧的投影（生成 `<project>/tsconfig.paths.json`）。
+ *
+ * 为什么必须生成而不能手写一条通配：oj 的 `#/<name>/<tail>` 锚定「目标模块根」，在
+ * `src/<name>/{api,web}` 布局下即 `src/<name>/api`。tsconfig 的 `paths` 做不了这件事：
+ *   - 每条规则的替换值只允许一个 `*`——想用单条 `"#/*"` 同时匹配模块名与尾路径，会被
+ *     TS 以 TS5062 直接拒掉（两处通配只能二选一）；
+ *   - `paths` 是静态全局映射，表达不了 `#x`（本模块根，随引用方变化）。
+ * 所以只能**按模块逐条枚举** `"#/<name>/*": ["./src/<name>/api/*"]`。模块清单必须与
+ * `src/<name>/api/manifest.yaml` 同源，手写必然漂移 → 由 `ojm init` / `ojm build` / `ojm dev` 生成。
+ *
+ * 生成物只被 `src/tsconfig.json`（后端）`extends`：前端 tsconfig 不引，因为 web 侧
+ * 没有 `#` 解析（`build.ts` 的 esbuild/vite 不认别名），让编辑器「能过」而打包失败
+ * 比漏补 path 更坏。
+ *
+ * 模式串用 manifest 的 `name`（oj 的身份口径，v0.1.85 起与目录名脱钩），替换值用
+ * **目录名**——两者在正常工程里同值，但真分叉时只有按此口径才不会一边错位。
+ */
+import type { ProjectLayout } from "./layout";
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "yaml";
+import { 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 重写本文件，请勿手改。",
+	"//",
+	"// oj 别名 `#/<模块名>/…` 锚在目标模块根（本布局下即 src/<模块名>/api）。tsconfig 的",
+	"// paths 只能静态全局映射，且每条规则的替换值只允许一个 `*`（`./src/*/api/*` 会被 TS",
+	"// 以 TS5062 拒掉），故按模块逐条枚举。",
+].join("\n");
+
+/** 读模块根 manifest 的 `name`（oj 的模块身份）；读不到/格式坏时回落到目录名 */
+function manifestName(apiDir: string, fallback: string): string {
+	try {
+		const doc: unknown = parse(fs.readFileSync(path.join(apiDir, "manifest.yaml"), "utf-8"));
+		if (doc && typeof doc === "object" && "name" in doc) {
+			const name = (doc as { name?: unknown }).name;
+			if (typeof name === "string" && name.trim())
+				return name.trim();
+		}
+	}
+	catch {}
+	return fallback;
+}
+
+/**
+ * 模块名 → tsconfig `paths` 规则（仅 module-root 布局）。
+ *
+ * 键序按目录名排序（`scanModules` 已排序），保证同布局两次生成字节一致——
+ * 否则「生成物是否过期」的比对会因文件系统枚举顺序抖动而误报。
+ */
+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("."))
+			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", "*")}`];
+	}
+	return entries;
+}
+
+/** 渲染 `tsconfig.paths.json`（含头注释；tsconfig 解析器接受 JSONC） */
+export function renderAliasPaths(layout: ProjectLayout): string {
+	const entries = Object.entries(aliasPathEntries(layout));
+	const body = entries.length === 0
+		? "\t\t\"paths\": {}"
+		: `\t\t"paths": {\n${
+			entries
+				.map(([pattern, targets]) => `\t\t\t${JSON.stringify(pattern)}: [${targets.map(t => JSON.stringify(t)).join(", ")}]`)
+				.join(",\n")
+		}\n\t\t}`;
+	return `${HEADER}\n{\n\t"compilerOptions": {\n${body}\n\t}\n}\n`;
+}
+
+/**
+ * 按当前模块清单同步生成物，**内容未变则不写**（避免每次 build 都产生无意义 diff）。
+ *
+ * 返回 `skipped` 表示不是 module-root 布局（历史布局的别名口径不同，不在此生成）。
+ */
+export function syncAliasPaths(projectRoot: string): "created" | "updated" | "unchanged" | "skipped" {
+	const layout = tryResolveLayout(projectRoot);
+	if (layout?.kind !== "module-root")
+		return "skipped";
+	const file = path.join(projectRoot, ALIAS_PATHS_FILE);
+	const next = renderAliasPaths(layout);
+	const prev = fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : null;
+	if (prev === next)
+		return "unchanged";
+	fs.writeFileSync(file, next);
+	return prev === null ? "created" : "updated";
+}

package/src/build.ts

@@ -10,8 +10,10 @@ import { pathToFileURL } from "node:url";
 import tailwindcss from "@tailwindcss/vite";
 import { build as esbuild } from "esbuild";
 import { build } from "vite";
-import { loadModulesConfig, resolveModuleEntry } from "./config";
-import { resolveConfigPath, resolveLayout } from "./layout";
+import { ALIAS_PATHS_FILE, syncAliasPaths } from "./alias-paths";
+import { assertModuleList, loadSiteConfig, mergeModuleList, resolveModuleEntry } from "./config";
+import { resolveConfigPath, resolveLayout, scanModules, tryResolveLayout } from "./layout";
+import { requireModuleRootCapability } from "./oj-caps";
 import { isSharedDep, SHARED_DEPS } from "./shared-deps";
 import { normalizeSiteBase, rewriteIndexHtml } from "./site-base";
 import { resolveOjBin } from "./vendor";
@@ -494,18 +496,33 @@ function assertResolvableSpecifiers(
  * 无后端源码返回 false（纯前端工程跳过）。
  */
 export async function buildBackend(projectRoot: string): Promise<boolean> {
-	const apiSrc = path.join(projectRoot, "api/src");
+	// 没有模块源码的工程（如 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] 找到 api/src 但缺少 ${oj}。\n`
+			`[ojm] 找到 ${path.relative(projectRoot, apiSrc) || "."} 但缺少 ${oj}。\n`
 			+ "请重跑 ojm init 幂等补缺（不会覆盖 config 与用户代码）。",
 		);
 	}
-	const apiDist = path.join(projectRoot, "api/dist");
+	// 能力闸门先于任何写入：失败时磁盘上不留半成品
+	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, "api", "dist");
 	console.log("[ojm] oj build（后端）…");
 	// 必须显式给 -c：oj build 的 -c 缺省是 ./config.yaml（相对 CWD），而 config 在
 	// <project>/config/ 下——漏传会静默读不到配置，连带 tasks 镜像目录回落默认 "tasks"、
@@ -518,7 +535,17 @@ export async function buildBackend(projectRoot: string): Promise<boolean> {
 	//   2) `if (cond) x = y` → 压成 `cond && x = y`，赋值作 && 右项缺括号 →
 	//      SyntaxError: Invalid left-hand side in assignment（端点 500）。
 	// 0.1.32 / 0.1.50 均复现。产物体积换正确性，等上游修好再撤这个旗标。
-	execFileSync(oj, ["build", ...configArgs, "-d", apiSrc, "-o", apiDist, "--no-minify"], { stdio: "inherit" });
+	// 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];
+	execFileSync(oj, [
+		"build",
+		...configArgs,
+		...sourceArgs,
+		"-o",
+		apiDist,
+		"--no-minify",
+	], { stdio: "inherit" });
 	// 宿主 versions.json 双落点：站点壳从 shell-dist 拷进 web/dist（mergeShellSite），
 	// 而方案安装器读的是 `<api>/dist/versions.json`（B-11：与 manifests.yaml 同层，用于
 	// peerRuntime 强制比对）。两处必须同源，否则新工程 `ojm build` 完仍装不上方案——
@@ -569,8 +596,13 @@ export async function buildModules(
 	projectRoot: string,
 	opts: { mergeSite?: boolean } = {},
 ): Promise<BuiltModule[]> {
-	const config = await loadModulesConfig(projectRoot);
 	const layout = resolveLayout(projectRoot);
+	const config = await loadSiteConfig(projectRoot);
+	// module-root：模块清单由 src/*/web/entry.ts 扫描得出（web.config.ts 仅可选覆盖）；
+	// 历史布局：仍以 web.config.ts 的 modules 为唯一真源。
+	const modules = layout.kind === "module-root"
+		? mergeModuleList(scanModules(layout), config.modules, projectRoot)
+		: assertModuleList(projectRoot, config.modules);
 	const outDir = layout.distDir;
 	const baseUrl = config.baseUrl ?? "";
 
@@ -584,7 +616,7 @@ export async function buildModules(
 
 	const built: BuiltModule[] = [];
 
-	for (const item of config.modules) {
+	for (const item of modules) {
 		if (item.enabled === false) {
 			console.log(`[ojm] 跳过已禁用模块 ${item.name}`);
 			continue;
@@ -595,7 +627,7 @@ export async function buildModules(
 
 		if (definition.name !== item.name) {
 			throw new Error(
-				`模块名不一致：web.config.ts 中为 "${item.name}"，entry.ts 中为 "${definition.name}"`,
+				`模块名不一致：${layout.kind === "module-root" ? `src/${item.name}` : "web.config.ts"} 中为 "${item.name}"，entry.ts 中为 "${definition.name}"`,
 			);
 		}
 

package/src/bundle.ts

@@ -3,16 +3,18 @@
 // 组装映射（对齐 P1-9 staging copy 源一层定版，unpack 布局即安装器 extract 段消费面）：
 //   <project>/manifest.yaml                     → <name>-<version>/manifest.yaml（Form A）
 //   <project>/api/dist/<name>-<version>/        → <name>-<version>/api/<name>-<version>/（oj build 产物原样，C2-31 分层核对）
-//   <project>/web/dist/modules/                 → <name>-<version>/web/modules/（web.entry/css 存在性复核）
+//   <project>/web/dist/modules/<name>/          → <name>-<version>/web/modules/<name>/（只入包方案自己的模块；
+//                                                 web.entry/css 存在性复核）
 // 红线：modules.json 禁入包（C2-31——该清单由安装器在目标站点 upsert，防覆盖宿主清单）；
 // 文件面契约（tables↔schema.yaml、locales 双语齐备）构建期 fail-fast（契约 §4.1 构建列）。
+import type { ProjectLayout } from "./layout";
 import fs from "node:fs";
 import path from "node:path";
 
 import { parse } from "yaml";
 import { readModuleDefinition } from "./build";
 import { createDeterministicTgz } from "./deterministic-tar";
-import { resolveLayout } from "./layout";
+import { apiSrcOf, resolveLayout, webSrcOf } from "./layout";
 import { checkLocalesComplete, checkTablesAgainstSchema, parseManifest, referencedI18nKeys, validateContract } from "./manifest-contract";
 import { deriveManifestRoutes, reconcileManifestRoutes } from "./manifest-routes-derive";
 
@@ -46,7 +48,8 @@ export async function buildBundle(projectRoot: string, opts: { out?: string } =
 	// 仅当 entry.ts 声明了 category 路由才覆盖；否则保留 manifest 既有 routes（未迁移方案兼容）。
 	// entry 读不出来（如第三依赖未装）时软降级：沿用既有 routes，不阻断打包。
 	const layout = resolveLayout(projectRoot);
-	const entryFile = path.join(layout.modulesSrc, name, "entry.ts");
+	// 前端入口两侧布局都在 webSrcOf 里收口：module-root → src/<name>/web，历史 → web/src/<name>
+	const entryFile = path.join(webSrcOf(layout, name), "entry.ts");
 	if (fs.existsSync(entryFile)) {
 		try {
 			const def = await readModuleDefinition(entryFile, projectRoot);
@@ -72,8 +75,8 @@ export async function buildBundle(projectRoot: string, opts: { out?: string } =
 
 	// 2) 文件面契约（§4.1 构建列专属执行点；manifest 内在规则已在 validateContract 全量通过）
 	const fileViolations = [
-		...checkTables(m, projectRoot, name),
-		...checkLocales(m, projectRoot, name),
+		...checkTables(m, layout, name),
+		...checkLocales(m, layout, name),
 	];
 	if (fileViolations.length > 0) {
 		throw new Error(`[ojm] 方案包构建失败：文件面契约未通过（${fileViolations.length} 项，全量列出）：\n${fileViolations.map(x => `- ${x}`).join("\n")}`);
@@ -109,13 +112,22 @@ export async function buildBundle(projectRoot: string, opts: { out?: string } =
 			fs.cpSync(built, path.join(root, "api", `${name}-${version}`), { recursive: true });
 		}
 
-		// web：站点构建模块产物入包（web 段缺省 = 纯后端方案，整段跳过）
+		// web：只入包方案自己的模块产物（web 段缺省 = 纯后端方案，整段跳过）。
+		// 为何不是整树：web/dist/modules 里除本方案模块外还有脚手架模板模块（home/login/
+		// personal-center/notification/system/oj-market…），而安装器 deployWeb 会把包内
+		// web/modules 整树覆盖进目标站 <dist>/modules——整树入包等于用开发机上的模板产物
+		// 覆盖目标站同名前端。方案包只该带自己那一份，模板模块属宿主面，不由方案分发。
 		if (m.web !== undefined) {
 			const webModules = path.join(projectRoot, "web/dist/modules");
 			if (!fs.existsSync(webModules)) {
 				throw new Error("[ojm] 方案包构建失败：缺少站点构建产物 web/dist/modules（manifest 声明了 web 段；先运行 ojm build 生成模块产物）");
 			}
-			fs.cpSync(webModules, path.join(root, "web", "modules"), { recursive: true });
+			const ownWeb = path.join(webModules, name);
+			if (!fs.existsSync(ownWeb)) {
+				throw new Error(`[ojm] 方案包构建失败：缺少本方案的站点产物 web/dist/modules/${name}/（方案包只入包方案自己的模块；请确认 web.config.ts 已登记 ${name} 且本次 ojm build 已产出）`);
+			}
+			fs.mkdirSync(path.join(root, "web", "modules"), { recursive: true });
+			fs.cpSync(ownWeb, path.join(root, "web", "modules", name), { recursive: true });
 			const web = m.web as Record<string, unknown>;
 			for (const rel of [web.entry, ...(Array.isArray(web.css) ? web.css : [])]) {
 				if (typeof rel === "string" && !fs.existsSync(path.join(root, "web", rel))) {
@@ -173,28 +185,28 @@ function checkModuleManifest(built: string, name: string, version: string, _summ
 }
 
 /** api.tables ↔ schema.yaml 表集对照（C2-12a 构建列；schema 缺失/声明不一致均 fail-fast） */
-function checkTables(m: Record<string, unknown>, projectRoot: string, name: string): string[] {
+function checkTables(m: Record<string, unknown>, layout: ProjectLayout, name: string): string[] {
 	const api = m.api as Record<string, unknown> | undefined;
 	if (api === undefined || api.tables === undefined)
 		return [];
-	const schemaPath = path.join(projectRoot, "api/src", name, "schema.yaml");
+	const schemaPath = path.join(apiSrcOf(layout, name), "schema.yaml");
 	if (!fs.existsSync(schemaPath)) {
-		return [`【C2-12a】api.tables 已声明但缺少 ${path.relative(projectRoot, schemaPath)}，无法对照表集（oj 冗余校验同源）`];
+		return [`【C2-12a】api.tables 已声明但缺少 ${path.relative(layout.projectRoot, schemaPath)}，无法对照表集（oj 冗余校验同源）`];
 	}
 	return checkTablesAgainstSchema(m, fs.readFileSync(schemaPath, "utf8"));
 }
 
 /** locales 双语齐备（C2-25 构建列缺 key fail-fast；安装期信任构建产物不重复校验） */
-function checkLocales(m: Record<string, unknown>, projectRoot: string, name: string): string[] {
+function checkLocales(m: Record<string, unknown>, layout: ProjectLayout, name: string): string[] {
 	if (referencedI18nKeys(m).length === 0)
 		return [];
-	const dir = path.join(projectRoot, "web/src", name, "locales");
+	const dir = path.join(webSrcOf(layout, name), "locales");
 	const texts: Partial<Record<"zh-CN" | "en-US", string>> = {};
 	const out: string[] = [];
 	for (const lang of ["zh-CN", "en-US"] as const) {
 		const p = path.join(dir, `${lang}.json`);
 		if (!fs.existsSync(p)) {
-			out.push(`【C2-25】manifest 引用了 i18n key 但缺少 ${path.relative(projectRoot, p)}（双语齐备，D4）`);
+			out.push(`【C2-25】manifest 引用了 i18n key 但缺少 ${path.relative(layout.projectRoot, p)}（双语齐备，D4）`);
 			continue;
 		}
 		texts[lang] = fs.readFileSync(p, "utf8");

package/src/config.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
@@ -25,7 +26,7 @@ export interface ModulesConfig {
 	 * 绝对域），`siteBase` 是**站点自身**的部署位置；两者正交，可同时使用。
 	 */
 	siteBase?: string
-	modules: ModuleConfigEntry[]
+	modules?: ModuleConfigEntry[]
 	/**
 	 * 站点 HTML 变换模块（可选）：相对工程根的路径（`./html-transform.ts`）
 	 * 或包名。`ojm dev` / `ojm preview` 动态 import 它，用其 default 导出
@@ -43,13 +44,18 @@ const DEFAULT_CONFIG: Required<Pick<ModulesConfig, "baseUrl" | "siteBase">> = {
 };
 
 /**
- * 加载模块工程的 web.config.ts。
+ * 加载模块工程的 web.config.ts（**不校验 modules**）。
  *
- * 用 tsx 真实 import，而不是正则解析——这样配置文件里可以写注释、
- * 用变量、做条件判断，且类型错误会直接暴露（B10 的正则方案做不到）。
+ * 两种布局的差别只在模块清单从哪来：
+ *   - module-root：模块由 `src/<name>/web/entry.ts` 扫描得出（一目录一模块），
+ *     web.config.ts 退化为「站点级配置 + 可选覆盖」（设计 D3）；
+ *   - 历史布局：modules 必填，用 `loadModulesConfig`。
+ * 缺文件不是错误（新工程可以没有 web.config.ts），坏文件必须报错。
  */
-export async function loadModulesConfig(projectRoot: string): Promise<ModulesConfig & { baseUrl: string, siteBase: string }> {
+export async function loadSiteConfig(projectRoot: string): Promise<ModulesConfig & { baseUrl: string, siteBase: string }> {
 	const configPath = path.join(projectRoot, "web.config.ts");
+	if (!fs.existsSync(configPath))
+		return { ...DEFAULT_CONFIG };
 
 	let mod: { default?: ModulesConfig };
 	try {
@@ -59,12 +65,79 @@ export async function loadModulesConfig(projectRoot: string): Promise<ModulesCon
 		throw new Error(`无法加载 ${configPath}：${(error as Error).message}`, { cause: error });
 	}
 
-	const config = mod.default;
-	if (!config?.modules?.length) {
-		throw new Error(`${configPath} 未导出有效的 modules 列表`);
+	return { ...DEFAULT_CONFIG, ...mod.default };
+}
+
+/**
+ * 加载模块工程的 web.config.ts（历史布局：modules 必填）。
+ *
+ * 用 tsx 真实 import，而不是正则解析——这样配置文件里可以写注释、
+ * 用变量、做条件判断，且类型错误会直接暴露（B10 的正则方案做不到）。
+ */
+export async function loadModulesConfig(projectRoot: string): Promise<ModulesConfig & { baseUrl: string, siteBase: string, modules: ModuleConfigEntry[] }> {
+	const config = await loadSiteConfig(projectRoot);
+	return { ...config, modules: assertModuleList(projectRoot, config.modules) };
+}
+
+/** 历史布局的 modules 必填校验（module-root 布局不走这条） */
+export function assertModuleList(projectRoot: string, modules: ModuleConfigEntry[] | undefined): ModuleConfigEntry[] {
+	if (!modules?.length)
+		throw new Error(`${path.join(projectRoot, "web.config.ts")} 未导出有效的 modules 列表`);
+	return modules;
+}
+
+/** 前端模块的最终清单项（entry 为相对工程根的路径，与 web.config.ts 历史口径一致） */
+export interface ResolvedWebModule {
+	name: string
+	entry: string
+	enabled: boolean
+}
+
+/**
+ * module-root 布局的模块清单：**扫描为准，web.config.ts 只做可选覆盖**（设计 D3）。
+ *
+ * 规则（并集，不是替换——新增模块目录不会因为忘了登记而被静默漏构建）：
+ *   1. 来源只有 `src/<name>/web/entry.ts`：纯后端模块没有前端产物，不进入本清单；
+ *   2. 覆盖项按声明顺序排在前，其余按模块名字典序追加；
+ *   3. `enabled: false` 仍生效（跳过构建）；
+ *   4. 覆盖项指向不存在的前端入口 → 报错（改名/删目录后忘了改 config 的典型症状）。
+ */
+export function mergeModuleList(
+	scanned: { name: string, webSrc?: string }[],
+	overrides: ModuleConfigEntry[] | undefined,
+	projectRoot: string,
+): ResolvedWebModule[] {
+	const web = scanned.filter(m => m.webSrc);
+	const byName = new Map(web.map(m => [m.name, m]));
+	const ordered: ResolvedWebModule[] = [];
+	const seen = new Set<string>();
+
+	for (const item of overrides ?? []) {
+		const hit = byName.get(item.name);
+		if (!hit) {
+			throw new Error(
+				`web.config.ts 登记了模块 "${item.name}"，但 src/${item.name}/web/entry.ts 不存在。\n`
+				+ "module-root 布局以目录为准：删掉这条登记，或补回该模块目录。",
+			);
+		}
+		seen.add(item.name);
+		ordered.push({
+			name: item.name,
+			entry: path.relative(projectRoot, path.join(hit.webSrc!, "entry.ts")),
+			enabled: item.enabled !== false,
+		});
 	}
 
-	return { ...DEFAULT_CONFIG, ...config };
+	for (const m of web) {
+		if (seen.has(m.name))
+			continue;
+		ordered.push({
+			name: m.name,
+			entry: path.relative(projectRoot, path.join(m.webSrc!, "entry.ts")),
+			enabled: true,
+		});
+	}
+	return ordered;
 }
 
 /** 解析模块 entry 的绝对路径 */

package/src/contract/__tests__/market-client.integration.test.ts

@@ -9,8 +9,8 @@ import type { ScopedRequestLike } from "@oj-module/runtime/contract/errors";
 // 不加载 @oj-module/runtime 重依赖（antd / pro-components 在 node 环境无法 import），仅桩 request、
 // 透传真实 zod（供生成 client 的 DEV 响应校验走真实路径）。ContractApiError 由轻量子路径提供。
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import { bindRequest } from "../../../templates/web/src/_platform/__client/api";
-import { httpMarketClient } from "../../../templates/web/src/oj-market/api/defaultClient";
+import { bindRequest } from "../../../templates/src/_platform/web/__client/api";
+import { httpMarketClient } from "../../../templates/src/oj-market/web/api/defaultClient";
 
 // index() 直连 request（不走生成 client），故把桩 request 做成可变实现，测试内统一指向同一 mock。
 const { requestImpl } = vi.hoisted(() => ({