@oj-module/cli 0.2.14 → 0.2.17

package/src/__tests__/manifest-routes-derive.test.ts

@@ -0,0 +1,102 @@
+import type { DerivedRoute, ModuleDefinitionLike } from "../manifest-routes-derive";
+
+import { describe, expect, it } from "vitest";
+import { deriveManifestRoutes, reconcileManifestRoutes } from "../manifest-routes-derive";
+
+/**
+ * BDD：R5 manifest.routes 由 entry.ts 路由 handle 自动派生（单一真源，避免手工双写漂移）。
+ * - d-1：三类（main/admin/hidden）路由均派生，字段口径正确；
+ * - d-2：无 handle.category 的路由（框架/纯页面/动态段子页）跳过，不进 manifest；
+ * - d-3：既有 manifest routes 与派生结果漂移时，reconcile 以 entry.ts 为准并发警告（不阻断）。
+ */
+
+function def(routes: ModuleDefinitionLike["routes"]): ModuleDefinitionLike {
+	return { name: "wiki", routes };
+}
+
+describe("deriveManifestRoutes（entry.ts → manifest routes）", () => {
+	it("d-1 三类 category 均派生，字段口径正确（path/category/order/title_key）", () => {
+		const d = def([
+			{ path: "/space", handle: { category: "main", order: 200, title: "wiki:menu.space" } },
+			{ path: "/admin", handle: { category: "admin", order: 220, title: "wiki:menu.admin" } },
+			{ path: "/wiki/status", handle: { category: "hidden", order: 201, title: "wiki:menu.status" } },
+		]);
+		const out = deriveManifestRoutes(d);
+		expect(out).toEqual([
+			{ path: "/space", category: "main", order: 200, title_key: "wiki:menu.space" },
+			{ path: "/admin", category: "admin", order: 220, title_key: "wiki:menu.admin" },
+			{ path: "/wiki/status", category: "hidden", order: 201, title_key: "wiki:menu.status" },
+		]);
+	});
+
+	it("d-2 无 category 的路由跳过：框架页/动态段子页/纯组件页不进 manifest", () => {
+		const d = def([
+			{ path: "/space", handle: { category: "main", order: 200, title: "wiki:menu.space" } },
+			// 动态段子页（空间成员页）：不进菜单，无 category → 跳过
+			{ path: ":id/members", handle: { title: "wiki:menu.members", hideInMenu: true } },
+			// 框架/纯页面路由：无 category → 跳过
+			{ path: "/dashboard", handle: { title: "framework:menu.dashboard" } },
+		]);
+		const out = deriveManifestRoutes(d);
+		expect(out).toEqual([
+			{ path: "/space", category: "main", order: 200, title_key: "wiki:menu.space" },
+		]);
+	});
+
+	it("d-2b 缺 order 的 category 路由仍派生（order 省略，交 C2-17 契约校验报必填）", () => {
+		const d = def([
+			{ path: "/space", handle: { category: "main", title: "wiki:menu.space" } },
+		]);
+		const out = deriveManifestRoutes(d);
+		expect(out).toEqual([{ path: "/space", category: "main", title_key: "wiki:menu.space" }]);
+	});
+
+	it("d-2c routes 缺失/空 → 派生为空数组（不抛）", () => {
+		expect(deriveManifestRoutes(def(undefined))).toEqual([]);
+		expect(deriveManifestRoutes(def([]))).toEqual([]);
+	});
+});
+
+describe("reconcileManifestRoutes（entry.ts 为准 + 漂移警告）", () => {
+	it("d-3a 既有 routes 与派生一致：不警告，采用派生", () => {
+		const existing: DerivedRoute[] = [
+			{ path: "/space", category: "main", order: 200, title_key: "wiki:menu.space" },
+		];
+		const derived: DerivedRoute[] = [
+			{ path: "/space", category: "main", order: 200, title_key: "wiki:menu.space" },
+		];
+		const { routes, warnings } = reconcileManifestRoutes(existing, derived);
+		expect(routes).toEqual(derived);
+		expect(warnings).toEqual([]);
+	});
+
+	it("d-3b 既有 routes 与派生漂移：以派生为准并发警告（不阻断）", () => {
+		const existing: DerivedRoute[] = [
+			// 旧 manifest 手写的 order 与 category 与 entry.ts 不一致
+			{ path: "/space", category: "admin", order: 999, title_key: "wiki:menu.space" },
+		];
+		const derived: DerivedRoute[] = [
+			{ path: "/space", category: "main", order: 200, title_key: "wiki:menu.space" },
+		];
+		const { routes, warnings } = reconcileManifestRoutes(existing, derived);
+		expect(routes).toEqual(derived); // 以 entry.ts 为准
+		expect(warnings).toHaveLength(1);
+		expect(warnings[0]).toContain("/space");
+		expect(warnings[0]).toContain("entry.ts 为准");
+	});
+
+	it("d-3c 派生为空（未迁移方案未声明 category）：保留既有 routes，不覆盖", () => {
+		const existing: DerivedRoute[] = [
+			{ path: "/space", category: "main", order: 200, title_key: "wiki:menu.space" },
+		];
+		const { routes, warnings } = reconcileManifestRoutes(existing, []);
+		expect(routes).toEqual(existing); // 沿用既有，向后兼容
+		expect(warnings).toEqual([]);
+	});
+
+	it("d-3d 既有为空且派生为空：结果为空，无警告", () => {
+		const { routes, warnings } = reconcileManifestRoutes([], []);
+		expect(routes).toEqual([]);
+		expect(warnings).toEqual([]);
+	});
+});

package/src/__tests__/usage.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import { getCommandHelp, resolveHelpRequest } from "../usage";
+
+describe("getCommandHelp", () => {
+	it("返回命令级帮助（init）", () => {
+		const t = getCommandHelp("init");
+		expect(t).toBeDefined();
+		expect(t).toContain("ojm init");
+	});
+
+	it("子命令优先：market setup 命中专属条目", () => {
+		expect(getCommandHelp("market", "setup")).toContain("ojm market setup");
+	});
+
+	it("子命令无专属条目时回退到命令级（market 无 sub）", () => {
+		const t = getCommandHelp("market");
+		expect(t).toContain("ojm market");
+	});
+
+	it("trust 子命令（add/revoke/confirm/ls）各自有专属条目", () => {
+		for (const sub of ["ls", "add", "revoke", "confirm"]) {
+			const t = getCommandHelp("trust", sub);
+			expect(t, `trust ${sub}`).toBeDefined();
+			expect(t).toContain(`ojm trust ${sub}`);
+		}
+	});
+
+	it("未知命令返回 undefined", () => {
+		expect(getCommandHelp("nope")).toBeUndefined();
+	});
+});
+
+describe("resolveHelpRequest", () => {
+	it("ojm --help → 顶层（无 cmd）", () => {
+		expect(resolveHelpRequest(["--help"])).toEqual({ cmd: undefined, sub: undefined });
+	});
+
+	it("ojm -h → 顶层（无 cmd）", () => {
+		expect(resolveHelpRequest(["-h"])).toEqual({ cmd: undefined, sub: undefined });
+	});
+
+	it("ojm init --help → cmd=init", () => {
+		expect(resolveHelpRequest(["init", "--help"])).toEqual({ cmd: "init", sub: undefined });
+	});
+
+	it("ojm trust add --help → cmd=trust sub=add", () => {
+		expect(resolveHelpRequest(["trust", "add", "--help"])).toEqual({ cmd: "trust", sub: "add" });
+	});
+
+	it("ojm market setup --help → cmd=market sub=setup", () => {
+		expect(resolveHelpRequest(["market", "setup", "--help"])).toEqual({ cmd: "market", sub: "setup" });
+	});
+
+	it("ojm help init → cmd=init", () => {
+		expect(resolveHelpRequest(["help", "init"])).toEqual({ cmd: "init", sub: undefined });
+	});
+
+	it("ojm help trust add → cmd=trust sub=add", () => {
+		expect(resolveHelpRequest(["help", "trust", "add"])).toEqual({ cmd: "trust", sub: "add" });
+	});
+
+	it("ojm help → 顶层（无 cmd）", () => {
+		expect(resolveHelpRequest(["help"])).toEqual({ cmd: undefined, sub: undefined });
+	});
+
+	it("非帮助调用返回 null（ojm build）", () => {
+		expect(resolveHelpRequest(["build", "--bundle"])).toBeNull();
+	});
+});

package/src/build.ts

@@ -1,5 +1,6 @@
 import type { Plugin as EsbuildPlugin } from "esbuild";
 import type { Plugin } from "vite";
+import type { RouteDefinitionLike } from "./manifest-routes-derive";
 import { execFileSync } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
@@ -12,6 +13,7 @@ import { build } from "vite";
 import { loadModulesConfig, resolveModuleEntry } from "./config";
 import { resolveConfigPath, resolveLayout } from "./layout";
 import { isSharedDep, SHARED_DEPS } from "./shared-deps";
+import { normalizeSiteBase, rewriteIndexHtml } from "./site-base";
 import { resolveOjBin } from "./vendor";
 import { checkSharedVersions, resolveShellDist } from "./versions";
 
@@ -138,6 +140,9 @@ export const mapTree = _fn;
 export const getAllExpandedKeys = _fn;
 export const getAppInfo = _fn;
 export const getRedirectPath = _fn;
+// 站点部署 base（子路径部署）：stub 只需占位，元数据读取期不拼 URL
+export const resolveSiteBase = _fn;
+export const withSiteBase = _fn;
 export const getYesNoOptions = _fn;
 export const getBooleanOptions = _fn;
 // 模块契约
@@ -387,6 +392,9 @@ export async function readModuleDefinition(entryFile: string, projectRoot: strin
 			version: string
 			peerRuntime?: string
 			config?: { dependencies?: string[] }
+			// R5：entry.ts 声明的路由树（含 handle.category/order/title），
+			// buildBundle 据此派生 manifest.routes（单一真源，避免手工双写漂移）
+			routes?: RouteDefinitionLike[]
 		};
 	}
 	finally {
@@ -528,12 +536,22 @@ export async function buildBackend(projectRoot: string): Promise<boolean> {
  * 再由模块构建写入 modules.json 与 modules/。清场防旧哈希资产无限累积
  * （shell 每次重构建生成新哈希文件名）；devServer 热重建路径不合并——
  * dev 的 / 与 /assets/* 直接服务 shell dist，合并产物无人消费。
+ *
+ * siteBase 非空时（站点挂载在 `/oj` 这类子路径）改写 index.html 的站内绝对
+ * URL 并注入 `window.__OJ_BASE__`（见 site-base.ts）；为空则产物与既有行为
+ * 逐字节一致。
  */
-function mergeShellSite(distDir: string): void {
+function mergeShellSite(distDir: string, siteBase: string): void {
 	const shellDist = resolveShellDist();
 	fs.rmSync(distDir, { recursive: true, force: true });
 	fs.mkdirSync(path.dirname(distDir), { recursive: true });
 	fs.cpSync(shellDist, distDir, { recursive: true });
+
+	const indexPath = path.join(distDir, "index.html");
+	if (normalizeSiteBase(siteBase) !== "/") {
+		fs.writeFileSync(indexPath, rewriteIndexHtml(fs.readFileSync(indexPath, "utf-8"), siteBase));
+		console.log(`[ojm] 站点 index.html 已按 siteBase=${normalizeSiteBase(siteBase)} 重写（子路径部署）`);
+	}
 	console.log(`[ojm] 已合并宿主站点 → ${distDir}`);
 }
 
@@ -557,7 +575,7 @@ export async function buildModules(
 	const baseUrl = config.baseUrl ?? "";
 
 	if (opts.mergeSite)
-		mergeShellSite(outDir);
+		mergeShellSite(outDir, config.siteBase ?? "");
 
 	// P4.5 / C4 / D12：构建前先过版本矩阵门禁，版本漂移直接拒绝
 	checkSharedVersions(projectRoot, resolveShellDist());

package/src/bundle.ts

@@ -10,8 +10,11 @@ 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 { checkLocalesComplete, checkTablesAgainstSchema, parseManifest, referencedI18nKeys, validateContract } from "./manifest-contract";
+import { deriveManifestRoutes, reconcileManifestRoutes } from "./manifest-routes-derive";
 
 export interface BundleBuildResult {
 	tgz: string
@@ -37,11 +40,34 @@ export async function buildBundle(projectRoot: string, opts: { out?: string } =
 		throw new Error(`[ojm] 方案包构建失败：${parsed.error}`);
 	}
 	const m = parsed.manifest;
+	const name = m.name as string;
+
+	// R5：manifest.routes 由 entry.ts 路由 handle 自动派生（单一真源），覆盖手工书写。
+	// 仅当 entry.ts 声明了 category 路由才覆盖；否则保留 manifest 既有 routes（未迁移方案兼容）。
+	// entry 读不出来（如第三依赖未装）时软降级：沿用既有 routes，不阻断打包。
+	const layout = resolveLayout(projectRoot);
+	const entryFile = path.join(layout.modulesSrc, name, "entry.ts");
+	if (fs.existsSync(entryFile)) {
+		try {
+			const def = await readModuleDefinition(entryFile, projectRoot);
+			const derived = deriveManifestRoutes(def);
+			const { routes, warnings } = reconcileManifestRoutes(
+				Array.isArray(m.routes) ? m.routes : [],
+				derived,
+			);
+			for (const w of warnings)
+				console.warn(w);
+			m.routes = routes;
+		}
+		catch (e) {
+			console.warn(`[ojm] ⚠️ 无法从 entry.ts 派生 routes（${e instanceof Error ? e.message : String(e)}），沿用 manifest.yaml 既有 routes`);
+		}
+	}
+
 	const violations = validateContract(m);
 	if (violations.length > 0) {
 		throw new Error(`[ojm] 方案包构建失败：manifest.yaml 契约校验未通过（${violations.length} 项违规，全量列出）：\n${violations.map(x => `- ${x}`).join("\n")}`);
 	}
-	const name = m.name as string;
 	const version = m.version as string;
 
 	// 2) 文件面契约（§4.1 构建列专属执行点；manifest 内在规则已在 validateContract 全量通过）

package/src/config.ts

@@ -12,6 +12,19 @@ export interface ModuleConfigEntry {
 export interface ModulesConfig {
 	/** 产物 URL 前缀，留空表示同源相对路径 */
 	baseUrl?: string
+	/**
+	 * 站点部署子路径（如 `"/oj"`），留空 = 挂在域名根。
+	 *
+	 * 站点被 oj 挂到 `mounts: [{ prefix: /oj, web: dist, spa: true }]` 这类非根
+	 * 前缀时**必须**配它：`ojm build` 会把全站 index.html 的站内绝对 URL
+	 * （importmap / `<script src>` / `<link href>`）改写为 `/oj/...`，并注入
+	 * `window.__OJ_BASE__` 供路由 basename 与模块资源解析取用。
+	 * 不配则浏览器去域名根取 `/assets/*` → 404 白屏，深链刷新也匹配不到路由。
+	 *
+	 * 与 `baseUrl` 的区别：`baseUrl` 是**模块产物**的 URL 前缀（可指向 CDN
+	 * 绝对域），`siteBase` 是**站点自身**的部署位置；两者正交，可同时使用。
+	 */
+	siteBase?: string
 	modules: ModuleConfigEntry[]
 	/**
 	 * 站点 HTML 变换模块（可选）：相对工程根的路径（`./html-transform.ts`）
@@ -24,8 +37,9 @@ export interface ModulesConfig {
 	htmlTransform?: string
 }
 
-const DEFAULT_CONFIG: Required<Pick<ModulesConfig, "baseUrl">> = {
+const DEFAULT_CONFIG: Required<Pick<ModulesConfig, "baseUrl" | "siteBase">> = {
 	baseUrl: "",
+	siteBase: "",
 };
 
 /**
@@ -34,7 +48,7 @@ const DEFAULT_CONFIG: Required<Pick<ModulesConfig, "baseUrl">> = {
  * 用 tsx 真实 import，而不是正则解析——这样配置文件里可以写注释、
  * 用变量、做条件判断，且类型错误会直接暴露（B10 的正则方案做不到）。
  */
-export async function loadModulesConfig(projectRoot: string): Promise<ModulesConfig & { baseUrl: string }> {
+export async function loadModulesConfig(projectRoot: string): Promise<ModulesConfig & { baseUrl: string, siteBase: string }> {
 	const configPath = path.join(projectRoot, "web.config.ts");
 
 	let mod: { default?: ModulesConfig };

package/src/index.ts

@@ -8,7 +8,7 @@ import { devServer } from "./dev";
 import { mergeManifests, printInfo } from "./info";
 import { initProject } from "./init";
 import { runPreview } from "./preview";
-import { usageText } from "./usage";
+import { getCommandHelp, resolveHelpRequest, usageText } from "./usage";
 import { vendorCommand } from "./vendor";
 import { readCliVersion } from "./versions";
 
@@ -25,6 +25,23 @@ function usage(): never {
 async function main() {
 	const projectRoot = process.cwd();
 
+	// 帮助请求：`ojm <cmd> --help` / `ojm help <cmd>` / 顶层 `ojm --help`
+	// 必须在 switch 之前拦截，否则会真正执行子命令（如 `ojm market setup --help` 会去建 CDN）。
+	const helpReq = resolveHelpRequest();
+	if (helpReq !== null) {
+		if (!helpReq.cmd) {
+			console.log(usageText());
+			return;
+		}
+		const text = getCommandHelp(helpReq.cmd, helpReq.sub);
+		if (text) {
+			console.log(text);
+			return;
+		}
+		console.error(`[ojm] 未知命令：${helpReq.cmd}${helpReq.sub ? ` ${helpReq.sub}` : ""}`);
+		process.exit(1);
+	}
+
 	// 顶层 --version / -V：打印 cli 包版本（与 `ojm info` 的 cli 版本同源）
 	if (command === "--version" || command === "-V") {
 		console.log(readCliVersion());

package/src/lifecycle/__tests__/fixtures/fixture-valid/web/src/demo-solution/locales/en-US.json

@@ -2,7 +2,8 @@
 	"menu": {
 		"main": "Lifecycle Sample",
 		"admin": "Sample Admin",
-		"report": "Sample Report"
+		"report": "Sample Report",
+		"group": "Sample Group"
 	},
 	"perm": {
 		"view": "View sample",

package/src/lifecycle/__tests__/fixtures/fixture-valid/web/src/demo-solution/locales/zh-CN.json

@@ -2,7 +2,8 @@
 	"menu": {
 		"main": "生命周期样例",
 		"admin": "样例管理",
-		"report": "样例报告"
+		"report": "样例报告",
+		"group": "样例分组"
 	},
 	"perm": {
 		"view": "查看样例",

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

@@ -14,7 +14,7 @@ import { parse } from "yaml";
 // 跨端引用（双端一致钉）：被测实现同仓分居两运行时（计划 §1「两运行时取舍」），
 // 测试直接互调，比「两套件各读同一夹具」更强——漂移即本文件红。
 import { preflight } from "../../../templates/api/src/_platform/_lifecycle/steps/preflight";
-import { checkLocalesComplete, checkTablesAgainstSchema, parseManifest, validateContract } from "../../manifest-contract";
+import { checkLocalesComplete, checkTablesAgainstSchema, groupI18nKeys, parseManifest, validateContract } from "../../manifest-contract";
 
 const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), "fixtures");
 const readText = (p: string) => readFileSync(join(FIXTURES, p), "utf8");
@@ -214,6 +214,75 @@ describe("checkLocalesComplete（C2-25：构建期缺 key fail-fast）", () => {
 	});
 });
 
+// ── C2-43 归组父标题 i18n（solution menu grouping；纯内容入参）──
+
+describe("c2-43 归组父标题 i18n（solution menu grouping）", () => {
+	const baseManifest = (): any => ({
+		name: "demo-solution",
+		version: "0.1.0",
+		routes: [
+			{ path: "/demo-solution", category: "main", order: 200, title_key: "demo-solution:menu.main" },
+		],
+	});
+	const ZH_FULL = JSON.stringify({ menu: { main: "主", group: "分组" } });
+	const EN_FULL = JSON.stringify({ menu: { main: "Main", group: "Group" } });
+
+	it("groupI18nKeys：声明 main/admin 路由才产一条 <name>:menu.group", () => {
+		expect(groupI18nKeys(baseManifest())).toEqual(["demo-solution:menu.group"]);
+	});
+
+	it("groupI18nKeys：多条 main 路由去重只产一条（C5）", () => {
+		const m = baseManifest();
+		m.routes = [
+			{ path: "/a", category: "main", order: 200, title_key: "demo-solution:menu.a" },
+			{ path: "/b", category: "main", order: 210, title_key: "demo-solution:menu.b" },
+		];
+		expect(groupI18nKeys(m)).toEqual(["demo-solution:menu.group"]);
+	});
+
+	it("groupI18nKeys：仅 hidden 路由不产 group key（C3）", () => {
+		const m = baseManifest();
+		m.routes = [{ path: "/x", category: "hidden", order: 210, title_key: "demo-solution:menu.x" }];
+		expect(groupI18nKeys(m)).toEqual([]);
+	});
+
+	it("c1 正例：menu.group 双语齐备 → 零违规", () => {
+		expect(checkLocalesComplete(baseManifest(), ZH_FULL, EN_FULL)).toEqual([]);
+	});
+
+	it("c2 反例：zh-CN 缺 menu.group → C2-43（非 C2-25，去重生效）", () => {
+		const zh = JSON.stringify({ menu: { main: "主" } });
+		const v = checkLocalesComplete(baseManifest(), zh, EN_FULL);
+		const hit = v.find(x => x.includes("C2-43"));
+		expect(hit, `期望 C2-43，实际：\n${v.join("\n")}`).toBeTruthy();
+		expect(hit).not.toContain("C2-25");
+		expect(hit).toContain("menu.group");
+	});
+
+	it("c4 反例：en-US 缺 menu.group → C2-43 指明 en-US", () => {
+		const en = JSON.stringify({ menu: { main: "Main" } });
+		const v = checkLocalesComplete(baseManifest(), ZH_FULL, en);
+		const hit = v.find(x => x.includes("C2-43"));
+		expect(hit).toBeTruthy();
+		expect(hit).toContain("en-US");
+	});
+
+	it("去重：多条 main 路由只产一条 group key，缺失时按语言各报一次（非按路由重复）", () => {
+		const m = baseManifest();
+		m.routes = [
+			{ path: "/a", category: "main", order: 200, title_key: "demo-solution:menu.a" },
+			{ path: "/b", category: "main", order: 210, title_key: "demo-solution:menu.b" },
+		];
+		const v = checkLocalesComplete(m, JSON.stringify({ menu: { main: "主" } }), JSON.stringify({ menu: { main: "Main" } }));
+		const c243 = v.filter(x => x.includes("C2-43"));
+		// 关键：2 条路由只产 1 个 group key → 缺失时按语言各报 1 次 = 2 条 C2-43，
+		// 而非 2 路由 × 2 语言 = 4 条（去重生效的判据是「< 路由数 × 语言数」）
+		expect(c243.length).toBe(2);
+		expect(c243.some(x => x.includes("zh-CN 缺少归组父标题 key「demo-solution:menu.group」"))).toBe(true);
+		expect(c243.some(x => x.includes("en-US 缺少归组父标题 key「demo-solution:menu.group」"))).toBe(true);
+	});
+});
+
 // ── isolate 侧 preflight 复用助手（与 templates/api/tests/lifecycle/preflight.spec.ts 同构）──
 
 function makeCtx(manifest: unknown): InstallContext {

package/src/manifest-contract.ts

@@ -1,5 +1,5 @@
 // bundle 级 manifest.yaml 契约校验（P1-11，`ojm build --bundle` 构建期执行点）。
-// 规则真源：docs/prd/solution/202610171254-lifecycle-manifest-contract.md §2/§4（C2-01~33 构建列）；
+// 规则真源：docs/prd/solution/202610171254-lifecycle-manifest-contract.md §2/§4（C2-01~33 构建列；C2-34~42 为归档签名与信任，见 sign.ts；本文件新增 C2-43）；
 // 期望真源：src/lifecycle/__tests__/fixtures/（fixture-valid 零违规 / fixture-invalid 七码齐报）。
 // 双端一致：本实现与 isolate 侧 preflight（templates/api/.../steps/preflight.ts）共享同一组夹具，
 // 正则与规则**逐字一致**（§4.1 矩阵构建列 vs 安装列的执行点差异见各规则注释）——
@@ -581,6 +581,15 @@ export function validateContract(m: unknown): string[] {
 	return v0;
 }
 
+/** C2-43 引用面：声明 main/admin 路由的方案须提供归组父标题 `<name>:menu.group`（单 bundle 单 name，去重只产一条） */
+export function groupI18nKeys(m: BundleManifest): string[] {
+	if (!isObj(m) || typeof m.name !== "string")
+		return [];
+	const routes = Array.isArray(m.routes) ? m.routes : [];
+	const hasGroupable = routes.some(r => isObj(r) && (r.category === "main" || r.category === "admin"));
+	return hasGroupable ? [`${m.name}:menu.group`] : [];
+}
+
 /** 收集 manifest 引用的全部 i18n key（C2-25 locales 齐备检查的引用面；bundle.ts 以此判定 locales 文件是否必查） */
 export function referencedI18nKeys(m: BundleManifest): string[] {
 	const keys: string[] = [];
@@ -611,6 +620,10 @@ export function referencedI18nKeys(m: BundleManifest): string[] {
 			}
 		}
 	}
+	// C2-43：归组父标题纳入引用面，交由 checkLocalesComplete 双语齐备（改报 C2-43）
+	for (const k of groupI18nKeys(m)) {
+		keys.push(k);
+	}
 	return keys;
 }
 
@@ -633,9 +646,12 @@ export function checkLocalesComplete(m: unknown, zhText: string, enText: string)
 	if (!isObj(m))
 		return [v("C2-25", "manifest 不是键值对象，无法核对 locales 引用")];
 	const locales: [string, Record<string, unknown> | null][] = [["zh-CN", parseJson(zhText)], ["en-US", parseJson(enText)]];
+	// group key 识别（C2-43）：归组父标题缺失须归因 C2-43 而非笼统 C2-25，避免重复报错
+	const groupKeys = new Set(groupI18nKeys(m));
 	const out: string[] = [];
 	for (const key of referencedI18nKeys(m)) {
 		const nsKey = key.includes(":") ? key.slice(key.indexOf(":") + 1) : key;
+		const isGroup = groupKeys.has(key);
 		for (const [lang, tree] of locales) {
 			if (tree === null) {
 				out.push(v("C2-25", `${lang} locale 不是合法 JSON 对象，无法核对引用 key`));
@@ -643,7 +659,14 @@ export function checkLocalesComplete(m: unknown, zhText: string, enText: string)
 			}
 			const val = lookupKey(tree, nsKey);
 			if (typeof val !== "string" || val === "") {
-				out.push(v("C2-25", `${lang} 缺少 manifest 引用的 key「${key}」（双语齐备，D4；构建期 fail-fast）`));
+				out.push(
+					v(
+						isGroup ? "C2-43" : "C2-25",
+						isGroup
+							? `${lang} 缺少归组父标题 key「${key}」（须为嵌套 menu.group，C2-43；声明 main/admin 路由即须提供）`
+							: `${lang} 缺少 manifest 引用的 key「${key}」（双语齐备，D4；构建期 fail-fast）`,
+					),
+				);
 			}
 		}
 	}

package/src/manifest-routes-derive.ts

@@ -0,0 +1,130 @@
+// R5：manifest.yaml `routes` 由 entry.ts 路由 handle 自动派生（单一真源）。
+//
+// 背景：0.2.15 时期 manifest.routes 由作者手工书写，且 runtime 分组还依赖
+// `sys_solution_route` 表行（dev 下该表空 → 不分组，见上游 wiki parity 方案 R1–R6）。
+// 0.2.16 起：category/order/title 的真源是 entry.ts 路由 handle，manifest.routes
+// 改为 build 期从 handle 派生，杜绝「entry.ts 改了 handle 但 manifest.yaml 没同步」的漂移。
+//
+// 派生口径（仅取顶层一级菜单路由；children 是动态段/子页，不进 manifest routes）：
+//   - handle.category ∈ {main,admin,hidden} 才纳入（无 category 的路由不进菜单，跳过）
+//   - path      ← route.path
+//   - category  ← handle.category
+//   - order     ← handle.order（缺省不写，交 C2-17 契约校验报「必填整数」）
+//   - title_key ← handle.title（main/admin 必填且须匹配 <name>:menu.*，契约校验）
+//
+// 兼容：entry.ts 未声明任何 category 路由时（迁移前的旧方案），调用方保留 manifest
+// 既有 routes，不强制覆盖——避免未迁移方案构建即坏。
+
+/** entry.ts 路由树节点（派生只读字段，宽松结构，避免 import runtime 类型形成环） */
+export interface RouteDefinitionLike {
+	path?: string
+	handle?: {
+		category?: "main" | "admin" | "hidden"
+		order?: number
+		title?: string
+		[key: string]: unknown
+	}
+	children?: RouteDefinitionLike[]
+	[key: string]: unknown
+}
+
+/** 派生出的 manifest route 契约项（字段口径见 C2-17） */
+export interface DerivedRoute {
+	path: string
+	category: "main" | "admin" | "hidden"
+	order?: number
+	title_key?: string
+}
+
+/** 模块定义（只需 name + routes 子集，宽松结构） */
+export interface ModuleDefinitionLike {
+	name: string
+	routes?: RouteDefinitionLike[]
+	[key: string]: unknown
+}
+
+/**
+ * 从 entry.ts 模块定义派生 manifest routes（仅顶层一级菜单路由）。
+ * 不抛异常：handle 缺字段时照常产出，交由 C2-17 契约校验报出具体违规项。
+ */
+export function deriveManifestRoutes(definition: ModuleDefinitionLike): DerivedRoute[] {
+	const routes = Array.isArray(definition.routes) ? definition.routes : [];
+	const out: DerivedRoute[] = [];
+	for (const r of routes) {
+		if (r === null || typeof r !== "object")
+			continue;
+		const handle = (typeof r.handle === "object" && r.handle !== null) ? r.handle : undefined;
+		const category = handle?.category;
+		if (category !== "main" && category !== "admin" && category !== "hidden")
+			continue;
+		if (typeof r.path !== "string" || r.path.length === 0)
+			continue;
+		const route: DerivedRoute = { path: r.path, category };
+		if (typeof handle?.order === "number")
+			route.order = handle.order;
+		if (typeof handle?.title === "string")
+			route.title_key = handle.title;
+		out.push(route);
+	}
+	return out;
+}
+
+/**
+ * 归并既有 manifest routes 与 entry.ts 派生 routes，返回最终采用项 + 警告。
+ *
+ * 规则（单一真源 = entry.ts）：
+ *   - derived 为空（entry.ts 未声明任何 category 路由）→ 沿用 existing，不覆盖（向后兼容）
+ *   - derived 非空 → 以 derived 为准；若 existing 非空且与 derived 在某 path 上漂移
+ *     （category/order/title_key 任一不一致）→ 追加警告（不阻断，R5 选择项「自动生成」而非「双写+校验」）
+ */
+export function reconcileManifestRoutes(
+	existing: unknown[],
+	derived: DerivedRoute[],
+): { routes: DerivedRoute[], warnings: string[] } {
+	const warnings: string[] = [];
+	if (derived.length === 0) {
+		// 未迁移方案：保留 manifest 既有 routes，等作者后续在 entry.ts 登记 category
+		return { routes: normalizeExisting(existing), warnings };
+	}
+	const existingByPath = new Map<string, DerivedRoute>();
+	for (const r of normalizeExisting(existing)) {
+		existingByPath.set(r.path, r);
+	}
+	const drift: DerivedRoute[] = [];
+	for (const d of derived) {
+		const e = existingByPath.get(d.path);
+		if (e === undefined)
+			continue;
+		if (e.category !== d.category || e.order !== d.order || e.title_key !== d.title_key) {
+			drift.push(d);
+		}
+	}
+	if (existing.length > 0 && drift.length > 0) {
+		warnings.push(
+			`[ojm] manifest.yaml 既有 routes 与 entry.ts 派生结果不一致，已采用 entry.ts 为准（R5 单一真源，避免手工双写漂移）：\n${
+				drift.map(d => `- ${d.path}（派生 category=${d.category} order=${d.order ?? "?"} title_key=${d.title_key ?? "?"})`).join("\n")}`,
+		);
+	}
+	return { routes: derived, warnings };
+}
+
+function normalizeExisting(existing: unknown[]): DerivedRoute[] {
+	const out: DerivedRoute[] = [];
+	for (const r of existing) {
+		if (r === null || typeof r !== "object")
+			continue;
+		const o = r as Record<string, unknown>;
+		if (typeof o.path !== "string")
+			continue;
+		const cat = o.category;
+		if (cat !== "main" && cat !== "admin" && cat !== "hidden")
+			continue;
+		const route: DerivedRoute = { path: o.path, category: cat };
+		if (typeof o.order === "number")
+			route.order = o.order;
+		if (typeof o.title_key === "string")
+			route.title_key = o.title_key;
+		out.push(route);
+	}
+	return out;
+}