@oj-module/cli 0.2.8 → 0.2.15

package/shell-dist/index.html

@@ -5,9 +5,9 @@
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<link rel="icon" href="/favicon.ico" />
 		<title>React Antd Admin · Shell</title>
-		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-GbU8577c6LFtg4pmT1NjGA=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
+		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-+MhU9b9nCIgdxcVv98WPgQ=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
 
-		<script type="importmap" nonce="GbU8577c6LFtg4pmT1NjGA==">{
+		<script type="importmap" nonce="+MhU9b9nCIgdxcVv98WPgQ==">{
   "imports": {
     "react": "/assets/react.js",
     "react/jsx-runtime": "/assets/jsx-runtime.js",

package/shell-dist/versions.json

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

package/src/__tests__/build-backend.test.ts

@@ -0,0 +1,64 @@
+// buildBackend spec：宿主 versions.json 双落点（方案安装的 C2-09 前置）。
+//
+// 安装器按 B-11 布局读 `<api>/dist/versions.json`（与 manifests.yaml 同层）做 peerRuntime
+// 强制比对；而站点壳的 versions.json 落在 web/dist。两者不同源时，新工程 `ojm build`
+// 完仍会在 preflight 被 C2-09 拒装——这条用例钉住「同源双写」，防止回归。
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { buildBackend } from "../build";
+
+/**
+ * 假 oj 二进制：只需成功退出——本 spec 验的是 buildBackend 在 oj build 之后的收尾动作
+ * （versions.json 同源落地），oj build 自身的产物由用例预先放好模拟。
+ */
+function fakeOj(projectRoot: string): void {
+	mkdirSync(join(projectRoot, "bin"), { recursive: true });
+	const bin = join(projectRoot, "bin", "oj");
+	writeFileSync(bin, "#!/bin/sh\nexit 0\n");
+	chmodSync(bin, 0o755);
+}
+
+function newProject(): string {
+	const root = mkdtempSync(join(tmpdir(), "ojm-build-backend-"));
+	mkdirSync(join(root, "api", "src", "demo"), { recursive: true });
+	writeFileSync(join(root, "api", "src", "demo", "manifest.yaml"), "name: demo\nversion: 0.1.0\n", "utf-8");
+	writeFileSync(join(root, "api", "config.yaml"), "server:\n  port: 9778\n", "utf-8");
+	// 模拟 oj build 已产出的 manifests.yaml（验证收尾动作不破坏既有产物）
+	mkdirSync(join(root, "api", "dist"), { recursive: true });
+	writeFileSync(join(root, "api", "dist", "manifests.yaml"), "demo: 0.1.0\n", "utf-8");
+	fakeOj(root);
+	return root;
+}
+
+describe("given 宿主工程有 api/src When ojm build 后端", () => {
+	it("then api/dist/versions.json 与 shell-dist 同源落地（安装器 C2-09 前置）", async () => {
+		const root = newProject();
+
+		await buildBackend(root);
+
+		const hostVersions = join(root, "api", "dist", "versions.json");
+		expect(existsSync(hostVersions)).toBe(true);
+		const parsed = JSON.parse(readFileSync(hostVersions, "utf-8")) as Record<string, string>;
+		expect(typeof parsed["@oj-module/runtime"]).toBe("string");
+	});
+
+	it("then 既有 oj build 产物不被覆盖（manifests.yaml 原样保留）", async () => {
+		const root = newProject();
+
+		await buildBackend(root);
+
+		expect(readFileSync(join(root, "api", "dist", "manifests.yaml"), "utf-8")).toBe("demo: 0.1.0\n");
+	});
+});
+
+describe("given 纯前端工程（无 api/src）When ojm build 后端", () => {
+	it("then 跳过构建、不产出 api/dist", async () => {
+		const root = mkdtempSync(join(tmpdir(), "ojm-build-backend-fe-"));
+
+		expect(await buildBackend(root)).toBe(false);
+		expect(existsSync(join(root, "api", "dist"))).toBe(false);
+	});
+});

package/src/__tests__/versions.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+
+import { hostArtifactFreshnessError } from "../versions";
+
+describe("hostArtifactFreshnessError（源码形态宿主产物过期守卫）", () => {
+	it("版本一致 → 通过", () => {
+		expect(hostArtifactFreshnessError("0.2.11", "0.2.11")).toBeUndefined();
+	});
+
+	it("任一侧缺失 → 跳过守卫", () => {
+		expect(hostArtifactFreshnessError(undefined, "0.2.11")).toBeUndefined();
+		expect(hostArtifactFreshnessError("0.2.11", undefined)).toBeUndefined();
+	});
+
+	it("宿主产物落后于 workspace runtime → 报真因并指向 build:shell", () => {
+		const err = hostArtifactFreshnessError("0.2.10", "0.2.11");
+		expect(err).toContain("shell-dist/versions.json）过期");
+		expect(err).toContain("0.2.10");
+		expect(err).toContain("0.2.11");
+		expect(err).toContain("build:shell");
+	});
+
+	it("宿主产物领先（跨仓消费旧版 runtime）→ 同样拦截", () => {
+		expect(hostArtifactFreshnessError("0.2.12", "0.2.11")).toContain("过期");
+	});
+});

package/src/build.ts

@@ -511,6 +511,15 @@ export async function buildBackend(projectRoot: string): Promise<boolean> {
 	//      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" });
+	// 宿主 versions.json 双落点：站点壳从 shell-dist 拷进 web/dist（mergeShellSite），
+	// 而方案安装器读的是 `<api>/dist/versions.json`（B-11：与 manifests.yaml 同层，用于
+	// peerRuntime 强制比对）。两处必须同源，否则新工程 `ojm build` 完仍装不上方案——
+	// preflight 直接 C2-09 fail-closed「无法读取宿主 runtime 版本」。
+	const versionsSrc = path.join(resolveShellDist(), "versions.json");
+	if (fs.existsSync(versionsSrc)) {
+		fs.mkdirSync(apiDist, { recursive: true });
+		fs.copyFileSync(versionsSrc, path.join(apiDist, "versions.json"));
+	}
 	return true;
 }
 

package/src/bundle.ts

@@ -116,8 +116,14 @@ export async function buildBundle(projectRoot: string, opts: { out?: string } =
 	}
 }
 
-/** C2-31 分层核对：模块级 manifest 仅 oj 原生键，且 name/version/desc 与 bundle 级逐一相等（oj 启动强校验同源） */
-function checkModuleManifest(built: string, name: string, version: string, summary: string): string[] {
+/**
+ * C2-31 分层核对：模块级 manifest 仅 oj 原生键，且 name/version 与 bundle 级逐一相等
+ * （oj 启动强校验同源）。
+ *
+ * 变更（2026-10-21）：`desc === summary` 的等值要求已移除（与安装侧 extract.ts 同步）——
+ * 那是构建期映射的产物而不是安全边界，保留它会让 desc 与 summary 一字之差的包直接装不上。
+ */
+function checkModuleManifest(built: string, name: string, version: string, _summary: string): string[] {
 	const p = path.join(built, "manifest.yaml");
 	let doc: unknown;
 	try {
@@ -137,9 +143,6 @@ function checkModuleManifest(built: string, name: string, version: string, summa
 	if (mm.version !== version) {
 		out.push(`模块级 version「${String(mm.version)}」必须 === bundle version「${version}」`);
 	}
-	if (mm.desc !== summary) {
-		out.push(`模块级 desc「${String(mm.desc)}」必须 === bundle summary「${summary}」（安装器写 desc 即取 summary）`);
-	}
 	return out;
 }
 

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

@@ -1,4 +1,6 @@
-import type { ScopedRequestLike } from "../../../templates/web/src/_platform/__client/api";
+// ScopedRequestLike 真源在 runtime contract（生成物 __client/api.ts 也从这里 import，
+// 自身不再 re-export——旧写法 type import 自 __client 会在再生后 TS2305）。
+import type { ScopedRequestLike } from "@oj-module/runtime/contract/errors";
 
 // 集成回归：真实 httpMarketClient（统一后委托 ojm 生成 client）的委托行为。
 // 经 bindRequest 注入 mock request，验证每条 MarketClient 方法 → 正确 URL/body/query + 返回形状；
@@ -43,9 +45,8 @@ function mockRequest(responder: (c: Call) => { status?: number, data?: unknown }
 		calls.push({ method, url, opts });
 		const r = responder({ method, url, opts });
 		if (r.status && r.status >= 400) {
-			const err: { response?: { status?: number } } = new Error(`HTTP ${r.status}`);
-			err.response = { status: r.status };
-			throw err;
+			// ky 形态：HTTPError 携带 response.status（httpMarketClient.isUnconfigured 依赖它）
+			throw Object.assign(new Error(`HTTP ${r.status}`), { response: { status: r.status } });
 		}
 		return { json: () => Promise.resolve({ code: 0, data: r.data ?? null }) };
 	};
@@ -61,14 +62,12 @@ function mockRequest(responder: (c: Call) => { status?: number, data?: unknown }
 }
 
 // 让 index() 直连的 request 与生成 client 的 bindRequest 指向同一 mock，行为一致。
+// 桥接：占位方法零参签名 ↔ ScopedRequestLike 真实签名，经 any 双向打通（测试桩，无运行时差异）。
 function useMock(m: ReturnType<typeof mockRequest>) {
 	bindRequest(m.req);
-	requestImpl.get = m.req.get;
-	requestImpl.post = m.req.post;
-	requestImpl.put = m.req.put;
-	requestImpl.delete = m.req.delete;
-	requestImpl.patch = m.req.patch;
-	requestImpl.head = m.req.head;
+	const req = m.req as unknown as Record<keyof typeof requestImpl, () => never>;
+	for (const k of Object.keys(requestImpl) as Array<keyof typeof requestImpl>)
+		requestImpl[k] = req[k];
 }
 
 describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
@@ -101,6 +100,10 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 		useMock(mock);
 		const r = await httpMarketClient.index();
 		expect(r).toEqual([]);
+		// 503 是配置态而非故障：silentError 抑制全局 toast + retry:0 不重试（原
+		// market-client-unconfigured 用例的断言并入此处——工厂形态退役后唯一活口）
+		expect(mock.calls).toHaveLength(1);
+		expect(mock.calls[0].opts).toMatchObject({ silentError: true, retry: 0 });
 	});
 
 	it("install(input) → POST _platform/market/install，body 含 name/version/source", async () => {

package/src/index.ts

@@ -161,6 +161,12 @@ async function main() {
 			publishCommand(positionals[0] ?? "", { id, key, check });
 			break;
 		}
+		case "market": {
+			// 本地模拟 CDN 与市场链路（setup / publish / build-index）
+			const { runMarket } = await import("./market/command");
+			await runMarket(process.argv.slice(3));
+			break;
+		}
 		default: {
 			if (command && OJ_PASSTHROUGH.has(command)) {
 				const { runOjSubcommand } = await import("./oj-cmd");

package/src/init.ts

@@ -98,6 +98,13 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 		fs.mkdirSync(skillDir, { recursive: true });
 		for (const name of ["SKILL.md", "api-manual.md"])
 			copyIfAbsent(path.join(devkit, name), path.join(skillDir, name), report);
+		// v0.1.82 起 devkit 新增两份专题指南（api-manual/SKILL 均引用它们）：
+		// SQL 构造器能力矩阵/方言差异、oj test L1 测试指南。它们是**增量文档**、
+		// 不影响 ojm 运行，故「有则拷、无则记跳过」——bin/devkit 来自用户本地
+		// oj 版本（MIN_OJ_VERSION 只钉到 0.1.73），旧版 devkit 没有这两个文件，
+		// 为两份文档把整个 init 打挂不值当（用户升 oj 后重跑 init 即补上）。
+		for (const name of ["sql-builder-guide.md", "oj-test-guide.md"])
+			copyIfPresent(path.join(devkit, name), path.join(skillDir, name), report);
 		copyIfAbsent(path.join(devkit, "global.d.ts"), path.join(destDir, "global.d.ts"), report);
 	}
 	else {
@@ -367,6 +374,21 @@ function copyIfAbsent(src: string, dest: string, report: InitReport): void {
 	report.created.push(path.relative(process.cwd(), dest) || path.basename(dest));
 }
 
+/**
+ * 同 copyIfAbsent，但**源缺失**时记一条跳过而非抛错。
+ *
+ * 用于从 bin/devkit 拷第三方版本化内容（两份专题指南）：devkit 随用户本地 oj
+ * 版本而变，旧版没有新文件属正常版本 skew，不是安装包损坏——缺了只少份文档，
+ * 不该让 init 失败。源在而目标已存在仍走 copyIfAbsent 的幂等跳过。
+ */
+function copyIfPresent(src: string, dest: string, report: InitReport): void {
+	if (!fs.existsSync(src)) {
+		report.skipped.push(`${path.basename(src)}（bin/devkit 无此文件，跳过）`);
+		return;
+	}
+	copyIfAbsent(src, dest, report);
+}
+
 /**
  * 新工程 .gitignore：不存在则生成；已存在则幂等跳过（用户规则永不覆盖）。
  *

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

@@ -33,7 +33,7 @@ afterEach(() => {
 
 /** 预置「已构建」产物：oj build（api/dist/<name>-<version>/）与站点构建（web/dist/modules/） */
 function makePrebuiltArtifacts(): void {
-	// oj build 产物（模块级 manifest 仅 oj 原生七键；name/version/desc 与 bundle 级逐一相等，C2-31）
+	// oj build 产物（模块级 manifest 仅 oj 原生七键；name/version 与 bundle 级逐一相等，C2-31）
 	const apiDist = join(project, "api/dist/demo-solution-0.1.0");
 	mkdirSync(join(apiDist, "ping"), { recursive: true });
 	mkdirSync(join(apiDist, "migrations"), { recursive: true });
@@ -101,9 +101,9 @@ describe("buildBundle · 校验先于打包（fail-fast）", () => {
 		await expect(pack()).rejects.toThrow(/manifest\.yaml/);
 	});
 
-	it("c2-31 分层核对：模块级 desc ≠ bundle summary → 拒绝", async () => {
+	it("c2-31 分层核对：模块级 desc ≠ bundle summary → 放行（等值要求已移除）", async () => {
 		writeFileSync(join(project, "api/dist/demo-solution-0.1.0/manifest.yaml"), "name: demo-solution\ndesc: 不一致描述\nversion: 0.1.0\n");
-		await expect(pack()).rejects.toThrow(/C2-31/);
+		await expect(pack()).resolves.toMatchObject({ name: "demo-solution" });
 	});
 
 	it("c2-31 分层核对：api/dist 缺 <name>-<version>/ → 可读报错指明期望产物路径", async () => {

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）`,
+					),
+				);
 			}
 		}
 	}