@oj-module/cli 0.2.56 → 0.2.57

package/src/bundle.ts

@@ -308,6 +308,16 @@ async function assembleBundle(projectRoot: string, layout: ProjectLayout, plan:
 			}
 			fs.mkdirSync(path.join(root, "web", "modules"), { recursive: true });
 			fs.cpSync(ownWeb, path.join(root, "web", "modules", name), { recursive: true });
+			// R1 数据源随包（计划 docs/plans/20261103-0948）：安装期角色 title 解析读
+			// <包>/web/modules/<name>/locales/<lang>.json——构建产物不含 locales（源码 JSON
+			// 被 vite 内联进 JS chunk），故从源码树复制双语；目录不存在（纯后端段缺 locales）静默跳过。
+			for (const lang of ["zh-CN", "en-US"]) {
+				const src = path.join(webSrcOf(layout, name), "locales", `${lang}.json`);
+				if (fs.existsSync(src)) {
+					fs.mkdirSync(path.join(root, "web", "modules", name, "locales"), { recursive: true });
+					fs.copyFileSync(src, path.join(root, "web", "modules", name, "locales", `${lang}.json`));
+				}
+			}
 			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))) {
@@ -365,6 +375,57 @@ export async function buildBundle(projectRoot: string, opts: { out?: string, nam
 	return results;
 }
 
+/**
+ * `ojm build` 末尾的用户方案摘要（2026-11-03，计划 docs/plans/20261103-0925）：
+ * 明确回答「我的方案构建进了吗、能不能打包」。判定口径与 resolveContractTargets 同源
+ * （模块级契约 ∪ 根契约，减内置名单）——摘要里列出的就是 --bundle 将要打包的那批。
+ * 只报告不裁决：不调 resolveLayout（构建末尾不因摘要崩溃），log 可注入供测试断言。
+ */
+export function summarizeBuiltSolutions(projectRoot: string, built: readonly { name: string, version: string }[], log: (line: string) => void = console.log): void {
+	const builtin = readBuiltinModules(projectRoot);
+	const rootSolution = path.join(projectRoot, "solution.yaml");
+	const rootManifest = path.join(projectRoot, "manifest.yaml");
+	const rootContract = fs.existsSync(rootSolution) ? rootSolution : fs.existsSync(rootManifest) ? rootManifest : undefined;
+	const rootName = rootContract ? peekContractName(rootContract) : undefined;
+
+	// 用户方案候选：模块级契约（非内置）∪ 根契约 name（按名去重——「根压 src」只是打包取哪份契约，摘要里是同一个方案）
+	const names = new Set<string>();
+	for (const c of collectModuleContracts(projectRoot)) {
+		if (!builtin.has(c.moduleDir!))
+			names.add(c.moduleDir!);
+	}
+	if (rootName !== undefined && !builtin.has(rootName))
+		names.add(rootName);
+
+	const builtByName = new Map(built.map(b => [b.name, b]));
+	if (names.size === 0) {
+		log("[ojm] 用户方案 0 份（ojm new <name> 创建后即可 ojm build --bundle 打包）");
+	}
+	else {
+		const all = [...names].sort();
+		const ok = all.filter(n => builtByName.has(n));
+		const missing = all.filter(n => !builtByName.has(n));
+		const builtList = ok.map(n => `${n}@${builtByName.get(n)!.version}`).join("、") || "无";
+		if (missing.length === 0)
+			log(`[ojm] 用户方案 ${all.length} 份已构建：${builtList}（ojm build --bundle 打包）`);
+		else
+			log(`[ojm] 用户方案 ${all.length} 份中 ${ok.length} 份已构建：${builtList}；未构建：${missing.join("、")}（查 web.config.ts 登记/enabled）`);
+	}
+
+	const builtinBuilt = built.filter(b => builtin.has(b.name));
+	if (builtinBuilt.length > 0)
+		log(`[ojm] 框架自带模块 ${builtinBuilt.length} 份已构建（不参与用户打包）`);
+
+	// module-root 口径（src/ 树在即适用；flat/new 工程模块不在 src/）：非内置且无契约的模块不会被打包——提前点名，别等 --bundle 才发现
+	if (fs.existsSync(path.join(projectRoot, "src"))) {
+		for (const b of built) {
+			if (builtin.has(b.name) || names.has(b.name))
+				continue;
+			log(`[ojm] ⚠️ 模块 ${b.name}@${b.version} 缺方案契约（src/${b.name}/solution.yaml），不会被打包`);
+		}
+	}
+}
+
 /**
  * C2-31 分层核对：模块级 manifest 仅 oj 原生键，且 name/version 与 bundle 级逐一相等
  * （oj 启动强校验同源）。

package/src/cli.ts

@@ -135,7 +135,10 @@ function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code
 				}
 				const { buildBackend, buildModules } = await import("./build");
 				await buildBackend(projectRoot);
-				await buildModules(projectRoot, { mergeSite: true });
+				const built = await buildModules(projectRoot, { mergeSite: true });
+				// 用户方案摘要（计划 20261103-0925）：构建末尾点名「我的方案」是否进构建、能否打包
+				const { summarizeBuiltSolutions } = await import("./bundle");
+				summarizeBuiltSolutions(projectRoot, built);
 			};
 		case "new":
 			return async (name: string | undefined, extra: string[] = [], opts: { layout?: string, api?: boolean } = {}) => {

package/src/init.ts

@@ -21,7 +21,7 @@ import { BUILTIN_LIST_FILE, writeBuiltinList } from "./builtin";
 import { resolveCertDir, resolveConfigPath } from "./layout";
 import { probeOjCaps } from "./oj-caps";
 import { mintDevCert } from "./oj-cert";
-import { isSupportedOjVersion, MIN_OJ_VERSION, resolveOjBin, vendorCommand } from "./vendor";
+import { isSupportedOjVersion, MIN_OJ_VERSION, resolveOjBin, syncOjDevkit, vendorCommand } from "./vendor";
 import { readHostVersions } from "./versions";
 
 export interface InitOptions {
@@ -167,25 +167,16 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	//      oj 不可用/不支持 secret → 保留明文并告警（init 不因加密失败而失败）
 	await sealJwtSecret(destDir, report, opts.seal);
 
-	// 4) devkit 分发：agent skill + 全局类型
-	const devkit = path.join(binDir, "devkit");
-	if (fs.existsSync(path.join(devkit, "SKILL.md"))) {
-		const skillDir = path.join(destDir, ".claude/skills/oj-api-dev");
-		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 {
+	// 4) devkit 分发：agent skill（与 vendor 同一同步出口 syncOjDevkit：bin/devkit 全量
+	//    .md **覆盖**进 .claude/skills/oj-api-dev——文档随 oj 版本同步，见计划 20261103-1020）
+	//    + 全局类型（模板已落则 copyIfAbsent 跳过，模板变体优先、用户可编辑）
+	const devkitStatus = syncOjDevkit(destDir, binDir);
+	if (devkitStatus.ok)
+		report.created.push(`.claude/skills/oj-api-dev（oj devkit 文档已同步 ${devkitStatus.files.length} 个文件）`);
+	else
 		report.skipped.push(".claude/skills/oj-api-dev（bin/devkit 缺失，跳过）");
-	}
+	if (fs.existsSync(path.join(binDir, "devkit", "global.d.ts")))
+		copyIfAbsent(path.join(binDir, "devkit", "global.d.ts"), path.join(destDir, "global.d.ts"), report);
 
 	// 4b) ojm 模块开发 skill 分发：从 cli 包内置 devkit（prepack 同步的
 	//     docs/devkit）拷到 .claude/skills/ojm-module-dev/；已存在则幂等跳过。
@@ -197,7 +188,8 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 		// 业务工程拿到模板后自助完成对接要用，不能只留本仓：
 		//   · `wecom-daikaifa.md`  企业微信代开发（服务商模板）：凭据清单 + 用户/开发/部署三视角；
 		//   · `wecom-internal-app.md` 企业内部应用（自建）：五项 corp 凭据 + 验证并接入 + 共存。
-		for (const name of ["SKILL.md", "manual.md", "README.md", "wecom-daikaifa.md", "wecom-internal-app.md"])
+		//   · `publish-walkthrough.md` 方案包发布全流程（新手照做版）：打包/签名/CDN/安装一条链。
+		for (const name of ["SKILL.md", "manual.md", "README.md", "wecom-daikaifa.md", "wecom-internal-app.md", "publish-walkthrough.md"])
 			copyIfAbsent(path.join(cliDevkit, name), path.join(ojmSkillDir, name), report);
 	}
 	else {
@@ -483,21 +475,6 @@ 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-summary.test.ts

@@ -0,0 +1,106 @@
+// BDD：`ojm build` 末尾用户方案摘要（计划 docs/plans/20261103-0925-ojm-build-solution-summary.md）。
+// 摘要只报告不裁决：判定口径与 --bundle 打包对象同源（模块级契约 ∪ 根契约，减内置名单）；
+// log 注入断言，夹具只摆契约/名单/构建结果三样，不需要真实工程结构。
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { summarizeBuiltSolutions } from "../../bundle";
+
+let project: string;
+let lines: string[];
+
+beforeEach(() => {
+	project = mkdtempSync(join(tmpdir(), "ojm-build-summary-"));
+	lines = [];
+});
+
+afterEach(() => {
+	rmSync(project, { recursive: true, force: true });
+});
+
+/** 模块级契约：src/<name>/solution.yaml（+ web/entry.ts 保持真实模块目录形态） */
+function moduleContract(name: string): void {
+	const dir = join(project, "src", name);
+	mkdirSync(join(dir, "web"), { recursive: true });
+	writeFileSync(join(dir, "web", "entry.ts"), "export default {};\n");
+	writeFileSync(join(dir, "solution.yaml"), `name: ${name}\nversion: 1.0.0\nsummary: ${name}\n`);
+}
+
+function builtinList(names: string[]): void {
+	mkdirSync(join(project, "src"), { recursive: true });
+	writeFileSync(join(project, "src", ".ojm-builtin.json"), JSON.stringify({ modules: names }));
+}
+
+function summaryOf(built: { name: string, version: string }[]): string[] {
+	summarizeBuiltSolutions(project, built, l => lines.push(l));
+	return lines;
+}
+
+describe("summarizeBuiltSolutions", () => {
+	it("场景：全部构建成功 → 一行列出可打包方案 + 一行列出内置模块", () => {
+		moduleContract("crm");
+		moduleContract("erp");
+		builtinList(["home", "login"]);
+		const out = summaryOf([
+			{ name: "crm", version: "1.0.0" },
+			{ name: "erp", version: "0.2.0" },
+			{ name: "home", version: "9.9.9" },
+			{ name: "login", version: "9.9.9" },
+		]);
+		expect(out.some(l => l.includes("用户方案 2 份已构建") && l.includes("crm@1.0.0") && l.includes("erp@0.2.0"))).toBe(true);
+		expect(out.some(l => l.includes("框架自带模块 2 份已构建"))).toBe(true);
+	});
+
+	it("场景：方案没进构建 → 点名未构建方案与排查方向", () => {
+		moduleContract("crm");
+		moduleContract("erp");
+		builtinList(["home"]);
+		const out = summaryOf([
+			{ name: "crm", version: "1.0.0" },
+			{ name: "home", version: "9.9.9" },
+		]);
+		expect(out.some(l => l.includes("crm@1.0.0"))).toBe(true);
+		expect(out.filter(l => l.includes("erp")).join("\n")).toContain("未构建");
+	});
+
+	it("场景：零用户方案 → 提示 ojm new", () => {
+		moduleContract("home");
+		builtinList(["home"]);
+		const out = summaryOf([{ name: "home", version: "9.9.9" }]);
+		expect(out.some(l => l.includes("用户方案 0 份") && l.includes("ojm new"))).toBe(true);
+	});
+
+	it("场景：非内置模块缺契约 → 警告不会被打包", () => {
+		builtinList(["home"]);
+		const out = summaryOf([
+			{ name: "foo", version: "0.1.0" },
+			{ name: "home", version: "9.9.9" },
+		]);
+		expect(out.some(l => l.includes("缺方案契约") && l.includes("foo@0.1.0"))).toBe(true);
+	});
+
+	it("场景：旧单方案工程（根契约、无 src/ 树）→ 列出根契约方案，不误报缺契约", () => {
+		writeFileSync(join(project, "manifest.yaml"), "name: demo-solution\nversion: 0.1.0\nsummary: 旧写法\n");
+		const out = summaryOf([{ name: "demo-solution", version: "0.1.0" }]);
+		expect(out.some(l => l.includes("用户方案 1 份已构建") && l.includes("demo-solution@0.1.0"))).toBe(true);
+		expect(out.every(l => !l.includes("缺方案契约"))).toBe(true);
+	});
+
+	it("场景：新脚手架形态（内置集中 src/app，无用户方案）→ 0 份提示，src/app 不被误判", () => {
+		// 脚手架 init 后：src/ 下只有 app（平台聚合树，无契约）与 oj-market，均在内置名单
+		mkdirSync(join(project, "src", "app", "web"), { recursive: true });
+		writeFileSync(join(project, "src", "app", "web", "entry.ts"), "export default {};\n");
+		mkdirSync(join(project, "src", "oj-market", "web"), { recursive: true });
+		writeFileSync(join(project, "src", "oj-market", "web", "entry.ts"), "export default {};\n");
+		builtinList(["app", "oj-market", "_platform", "auth", "notification", "personal-center", "system", "web"]);
+		const out = summaryOf([
+			{ name: "app", version: "0.2.56" },
+			{ name: "oj-market", version: "0.2.56" },
+		]);
+		expect(out.some(l => l.includes("用户方案 0 份") && l.includes("ojm new"))).toBe(true);
+		expect(out.some(l => l.includes("框架自带模块 2 份已构建"))).toBe(true);
+		expect(out.every(l => !l.includes("缺方案契约"))).toBe(true);
+	});
+});

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

@@ -104,6 +104,12 @@ describe("buildBundle · 正路径", () => {
 		expect(tarList(r.tgz).some(n => n.endsWith("/modules.json"))).toBe(false);
 	});
 
+	it("r1 前提：模块源码 locales 双语随包（安装期角色 title 解析数据源，计划 20261103-0948）", async () => {
+		const names = tarList((await pack()).tgz);
+		expect(names).toContain("demo-solution-0.1.0/web/modules/demo-solution/locales/zh-CN.json");
+		expect(names).toContain("demo-solution-0.1.0/web/modules/demo-solution/locales/en-US.json");
+	});
+
 	it("solution.yaml 作为 bundle 契约（优先于 manifest.yaml，避开 oj 按 manifest.yaml 枚举 api 后端的冲突）", async () => {
 		// 根目录若用 manifest.yaml 当 bundle 契约，会被 oj 的 api 模块搜索枚举误判为 api 模块；
 		// 故解决方案改用 solution.yaml，bundle 工具优先认它（manifest.yaml 仅旧方案回退）。

package/src/vendor.ts

@@ -79,6 +79,30 @@ export function ojBinName(platform: string = process.platform): string {
 	return platform === "win32" ? "oj.exe" : "oj";
 }
 
+/**
+ * oj devkit 文档同步（计划 docs/plans/20261103-1020-vendor-devkit-sync）：bin/devkit
+ * （@oj-bin/oj postinstall 落盘，与 bin/oj 同版本）→ 工程 `.claude/skills/oj-api-dev/`，
+ * 全部 `.md` **覆盖**拷入——skill 文档始终与已装 oj 版本一致（vendor/init 共用出口）。
+ * bin/devkit 缺失（旧版 oj/异常安装）→ ok:false，调用方记跳过、不失败。
+ * global.d.ts 不在此同步：工程根那份是模板自有变体、用户可编辑（init 首装 copyIfAbsent）。
+ */
+export function syncOjDevkit(projectRoot: string, binDir: string, log: (msg: string) => void = () => {}): { ok: boolean, files: string[] } {
+	const devkitDir = path.join(binDir, "devkit");
+	if (!fs.existsSync(path.join(devkitDir, "SKILL.md")))
+		return { ok: false, files: [] };
+	const skillDir = path.join(projectRoot, ".claude", "skills", "oj-api-dev");
+	fs.mkdirSync(skillDir, { recursive: true });
+	const files: string[] = [];
+	for (const name of fs.readdirSync(devkitDir)) {
+		if (!name.endsWith(".md"))
+			continue;
+		fs.copyFileSync(path.join(devkitDir, name), path.join(skillDir, name));
+		files.push(name);
+	}
+	log(`[ojm] oj devkit 文档已同步 → .claude/skills/oj-api-dev/（${files.length} 个文件，与已装 oj 同版本）`);
+	return { ok: true, files };
+}
+
 /**
  * 工程内 oj 二进制路径的**唯一口径**（<projectRoot>/bin/oj）。
  *
@@ -222,6 +246,12 @@ function installFromNpm(version: string, binDir: string, run: NpmRun, log: (msg:
 	}
 }
 
+/** devkit 同步 + 缺失时的人话跳过行（vendorCommand 两个调用点共用） */
+function syncDevkitOrSkip(projectRoot: string, binDir: string, log: (msg: string) => void): void {
+	if (!syncOjDevkit(projectRoot, binDir, log).ok)
+		log("[ojm] bin/devkit 缺失，跳过 oj devkit 文档同步（旧版 oj 或异常安装；skill 文档不更新）");
+}
+
 /**
  * US-1..US-5 编排：解析目标版本（tag 缺省经 npm view 追 latest，显式 tag 去 v 前缀）
  * → 本地已是该版本则跳过（--force 除外）→ 临时目录安装 + 拷贝 → 报告版本 → 探针冒烟。
@@ -243,6 +273,9 @@ export async function vendorCommand(
 	const binDir = path.join(projectRoot, "bin");
 	const local = readLocalVersion(binDir);
 	if (!opts.force && local === `v${version}`) {
+		// 文档同步不随版本跳过：用户删过 skill 目录后重跑 vendor 即补齐（R4）。
+		// 先同步再打跳过行——「已是 vX」保持命令收尾行（既有门禁断言末行）。
+		syncDevkitOrSkip(projectRoot, binDir, log);
 		log(`[ojm] oj 已是 v${version}，跳过。`);
 		const result = probe(binDir);
 		if (!result.ok)
@@ -255,6 +288,7 @@ export async function vendorCommand(
 		log(`[ojm] 本地 ${local ?? "未安装"} → v${version}`);
 	installFromNpm(version, binDir, run, log);
 	log(`[ojm] oj ${local ? `${local} → ` : ""}v${version} 安装完成：${path.join(binDir, ojBinName(process.platform))}`);
+	syncDevkitOrSkip(projectRoot, binDir, log);
 	// 安装后冒烟：发布二进制可能因构建机路径被烤进而不可用（见 probeOjRuntime）
 	const result = probe(binDir);
 	if (!result.ok)

package/templates/openapi.json

@@ -5679,6 +5679,7 @@
 													"name",
 													"module",
 													"title",
+													"title_key",
 													"description",
 													"builtin",
 													"deprecated",
@@ -5698,6 +5699,12 @@
 															"null"
 														]
 													},
+													"title_key": {
+														"type": [
+															"string",
+															"null"
+														]
+													},
 													"description": {
 														"type": [
 															"string",

package/templates/src/app/api/_platform/_lifecycle/installer.ts

@@ -31,7 +31,7 @@ import { download } from "./steps/download";
 import { extract } from "./steps/extract";
 import { maxAppliedSeq, migrate, rollbackGuard } from "./steps/migrate";
 import { preflight } from "./steps/preflight";
-import { registerSolution } from "./steps/register";
+import { registerSolution, resolveDeclTitles, siteLanguage } from "./steps/register";
 import { reloadAndAssert } from "./steps/reload";
 import { smoke } from "./steps/smoke";
 import { verify } from "./steps/verify";
@@ -261,7 +261,8 @@ async function lockCommitStage(req: InstallRequest): Promise<StageResult> {
 }
 
 /**
- * manifest.yaml（C2 形状）→ SolutionDecl（D10 出口入参）：roles[].title_key → title、
+ * manifest.yaml（C2 形状）→ SolutionDecl（D10 出口入参）：roles[].title/title_key 透传
+ * （title 此刻仍是原始 key，registering 段落库前经 resolveDeclTitles 按站点语言解析，R1/R4）、
  * settings.groups[].items[] 摊平、enum options 序列化为 JSON 字符串（sys_setting.options 形态）。
  */
 export function declOf(req: InstallRequest): SolutionDecl {
@@ -297,6 +298,7 @@ export function declOf(req: InstallRequest): SolutionDecl {
 		roles: (Array.isArray(m.roles) ? m.roles : []).filter(isObj).map(r => ({
 			name: typeof r.name === "string" ? r.name : "",
 			title: typeof r.title_key === "string" ? r.title_key : "",
+			title_key: typeof r.title_key === "string" ? r.title_key : undefined,
 			permissions: Array.isArray(r.permissions) ? r.permissions.map(String) : [],
 		})),
 		// 顶层 permissions[] 的 code：无角色权限点（系统预置点）唯一能落库的来源，别在此丢弃
@@ -316,7 +318,10 @@ export function declOf(req: InstallRequest): SolutionDecl {
 }
 
 async function registerStage(req: InstallRequest): Promise<StageResult> {
-	return registerSolution(declOf(req));
+	// R1/R4：落库前按站点默认语言解析角色 title（数据源 = 包内 locales，staging 此刻仍在；
+	// 解析失败回退原文绝不失败安装）。fsFace 注入读文件面（测试 stub 同 DIP 纪律）。
+	const decl = await resolveDeclTitles(declOf(req), req.staging, await siteLanguage(), p => fsFace().readFile(p));
+	return registerSolution(decl);
 }
 
 async function deployWebStage(req: InstallRequest): Promise<StageResult> {

package/templates/src/app/api/_platform/_lifecycle/steps/register.ts

@@ -65,6 +65,59 @@ export interface SolutionSnapshot {
 	permissions: string[]
 }
 
+/** 角色 title 的裸 i18n key 形状（`pm:role.sales`；0018 迁移回填同口径） */
+const TITLE_KEY_SHAPE = /^[a-z][\w-]*:/;
+
+/**
+ * 站点默认语言（R4）：sys_setting `site.language`，无行/空值回退 zh-CN
+ * （与前端 preference 缺省同值；未来设置面落库即自动生效）。
+ */
+export async function siteLanguage(): Promise<string> {
+	const rows = await db.table("sys_setting").select(["value"]).where({ field: "key", op: "eq", value: "site.language" }).all() as Array<{ value: string | null }>;
+	const v = rows[0]?.value;
+	return typeof v === "string" && v.trim() ? v.trim() : "zh-CN";
+}
+
+/**
+ * 角色 title 落库前解析（R1，registering 段消费；升级重装同路径 = R3 重解析）。
+ * 仅 title 命中 key 形状才尝试；ns（冒号前段）=== 模块名才读本包 locale（跨 ns 不越界）；
+ * dotted path 取值须为非空 string。数据源 = 方案包 `web/modules/<ns>/locales/<lang>.json`
+ * （bundle 侧随包，见 cli bundle.ts）。任何失败（无文件/坏 JSON/缺 key/非 string）保留原文
+ * 并继续——翻译永不失败安装（R1 红线）。
+ */
+export async function resolveDeclTitles(
+	decl: SolutionDecl,
+	stagingDir: string,
+	lang: string,
+	readFile: (path: string) => Promise<Uint8Array>,
+): Promise<SolutionDecl> {
+	const roles = [...decl.roles];
+	for (let i = 0; i < roles.length; i++) {
+		const title = roles[i]!.title;
+		if (!TITLE_KEY_SHAPE.test(title)) {
+			continue;
+		}
+		const ns = title.slice(0, title.indexOf(":"));
+		if (ns !== decl.module) {
+			continue;
+		}
+		try {
+			const bytes = await readFile(`${stagingDir}/web/modules/${ns}/locales/${lang}.json`);
+			let node: unknown = JSON.parse(new TextDecoder().decode(bytes));
+			for (const part of title.slice(title.indexOf(":") + 1).split(".")) {
+				node = node == null ? undefined : (node as Record<string, unknown>)[part];
+			}
+			if (typeof node === "string" && node.trim()) {
+				roles[i] = { ...roles[i]!, title: node };
+			}
+		}
+		catch {
+			// 解析失败 = 回退原文（R1）
+		}
+	}
+	return { ...decl, roles };
+}
+
 /** 首段提取（/wiki/docs → wiki）——占用判定粒度：前缀段冲突即整段首段比较（P1-5 备案③） */
 function firstSeg(path: string): string {
 	return path.split("/")[1] ?? "";

package/templates/src/app/api/_platform/_shared/service/domain/roles.ts

@@ -9,6 +9,8 @@ export interface RoleRow {
 	name: string
 	module: string
 	title: string | null
+	/** 原始 i18n key（R2：solution 角色安装期解析锚；custom/builtin 为 null，UI 据此实时翻译） */
+	title_key: string | null
 	description: string | null
 	builtin: boolean
 	deprecated: boolean
@@ -60,7 +62,7 @@ async function invalidateHolders(roleName: string): Promise<void> {
 }
 
 export async function listRoles(): Promise<RoleRow[]> {
-	const roles = await db.table("sys_role").select(["name", "module", "title", "description", "builtin", "deprecated"]).orderBy([{ field: "name" }]).all() as Array<Record<string, unknown>>;
+	const roles = await db.table("sys_role").select(["name", "module", "title", "title_key", "description", "builtin", "deprecated"]).orderBy([{ field: "name" }]).all() as Array<Record<string, unknown>>;
 	const holders = await db.table("sys_user_role").select(["role_name", { fn: "count", as: "c" }]).groupBy(["role_name"]).all() as Array<{ role_name: string, c: number }>;
 	const binds = await db.table("sys_role_permission").select(["role_name", "permission_code"]).orderBy([{ field: "permission_code" }]).all() as Array<{ role_name: string, permission_code: string }>;
 	const holderMap = new Map(holders.map(h => [h.role_name, Number(h.c)]));
@@ -71,6 +73,7 @@ export async function listRoles(): Promise<RoleRow[]> {
 		name: String(r.name),
 		module: String(r.module),
 		title: r.title == null ? null : String(r.title),
+		title_key: r.title_key == null ? null : String(r.title_key),
 		description: r.description == null ? null : String(r.description),
 		builtin: Number(r.builtin) === 1,
 		deprecated: Number(r.deprecated) === 1,

package/templates/src/app/api/_platform/_shared/service/domain/solution-perms.ts

@@ -7,7 +7,10 @@
 export interface SolutionRoleDecl {
 	/** 完整角色名（含 `<module>.` 前缀，AC1-11 由安装器侧前缀校验） */
 	name: string
+	/** 解析后的可读文本（站点默认语言；解析失败 = 原始 key，R1 回退） */
 	title: string
+	/** 原始 i18n key（R2：UI 实时翻译锚，对齐 sys_permission.title_key 先例；解析失败与 title 同值） */
+	title_key?: string
 	/** 声明绑定：insert-if-absent 写入，管理员调整永不被覆写（AC1-15） */
 	permissions?: string[]
 }
@@ -37,12 +40,13 @@ export async function upsertSolutionPerms(m: SolutionManifest): Promise<UpsertRe
 
 	for (const role of m.roles) {
 		const existing = await db.table("sys_role").select(["name"]).where({ field: "name", op: "eq", value: role.name }).all() as unknown[];
-		// upsert：行存在只覆盖元数据（title），name/builtin 不动（AC2-2 元数据覆盖）
+		// upsert：行存在只覆盖元数据（title/title_key——R3 升级即重解析：新包 locale 改进随升级传播），
+		// name/builtin 不动（AC2-2 元数据覆盖）
 		if (existing.length) {
-			await db.table("sys_role").update({ title: role.title }).where({ field: "name", op: "eq", value: role.name }).run();
+			await db.table("sys_role").update({ title: role.title, title_key: role.title_key ?? null }).where({ field: "name", op: "eq", value: role.name }).run();
 		}
 		else {
-			await db.table("sys_role").insert({ name: role.name, module: m.module, title: role.title, builtin: 0 }).run();
+			await db.table("sys_role").insert({ name: role.name, module: m.module, title: role.title, title_key: role.title_key ?? null, builtin: 0 }).run();
 			// 声明绑定只在角色创建时写一次（角色级 insert-if-absent，AC1-15 红线）：
 			// 升级/重装对已存在角色永不补写声明绑定——管理员撤过的绑定不复活；
 			// 新版本给既有角色新增权限点时，由管理员显式勾选（insert-if-absent 的取舍边界，§9.5）。

package/templates/src/app/api/_platform/migrations/0018__sys_role_title_key.mysql.sql

@@ -0,0 +1,3 @@
+-- 0018__sys_role_title_key（mysql 方言）：列语义同 0018__sys_role_title_key.sql 头注释（R2 回填）。
+ALTER TABLE sys_role ADD COLUMN title_key TEXT NULL;
+UPDATE sys_role SET title_key = title WHERE builtin = 0 AND title REGEXP '^[a-z][A-Za-z0-9_-]*:';

package/templates/src/app/api/_platform/migrations/0018__sys_role_title_key.pg.sql

@@ -0,0 +1,3 @@
+-- 0018__sys_role_title_key（postgres 方言）：列语义同 0018__sys_role_title_key.sql 头注释（R2 回填）。
+ALTER TABLE sys_role ADD COLUMN title_key TEXT;
+UPDATE sys_role SET title_key = title WHERE builtin = 0 AND title ~ '^[a-z][A-Za-z0-9_-]*:';

package/templates/src/app/api/_platform/migrations/0018__sys_role_title_key.sql

@@ -0,0 +1,8 @@
+-- 0018__sys_role_title_key（sqlite 方言）：角色显示名双列（R2，计划 docs/plans/20261103-0948-role-title-translate）。
+-- title = 安装期解析文本（站点默认语言）；title_key = 原始 i18n key（UI 实时翻译锚，
+-- 对齐 sys_permission.title_key 先例）。可空：内置角色与 custom 角色无 key。
+-- 回填口径：builtin=0 且 title 命中裸 key 形状。sqlite 无 REGEXP → GLOB '[a-z]*:*'
+-- （首字符小写字母 + 含冒号的近似）；真实数据里含冒号的 title 只可能是裸 key
+-- （内置中文/管理员文本不含冒号），pg/mysql 两侧用完整正则同义钉死。
+ALTER TABLE sys_role ADD COLUMN title_key TEXT;
+UPDATE sys_role SET title_key = title WHERE builtin = 0 AND title GLOB '[a-z]*:*';

package/templates/src/app/api/_platform/schema.yaml

@@ -100,6 +100,8 @@ tables:
       name: {type: text, null: false}
       module: {type: text, null: false}
       title: {type: text}
+      # 原始 i18n key（R2，0018）：title = 安装期解析文本，本列存原文供 UI 实时翻译（sys_permission 先例）
+      title_key: {type: text}
       description: {type: text}
       builtin: {type: integer, null: false}
       deprecated: {type: integer, null: false}

package/templates/src/app/api/system/roles/api.ts

@@ -19,11 +19,12 @@ get.response = {
 	type: "array",
 	items: {
 		type: "object",
-		required: ["name", "module", "title", "description", "builtin", "deprecated", "holders", "permissions"],
+		required: ["name", "module", "title", "title_key", "description", "builtin", "deprecated", "holders", "permissions"],
 		properties: {
 			name: { type: "string" },
 			module: { type: "string" },
 			title: { type: ["string", "null"] },
+			title_key: { type: ["string", "null"] },
 			description: { type: ["string", "null"] },
 			builtin: { type: "boolean" },
 			deprecated: { type: "boolean" },

package/templates/src/app/web/system/__client/api.schemas.ts

@@ -175,6 +175,7 @@ export const schemas = {
 	"name": z.string(),
 	"module": z.string(),
 	"title": z.string().nullable(),
+	"title_key": z.string().nullable(),
 	"description": z.string().nullable(),
 	"builtin": z.boolean(),
 	"deprecated": z.boolean(),

package/templates/src/app/web/system/pages/roles/index.tsx

@@ -38,7 +38,13 @@ export default function RolesPage() {
 			),
 		},
 		{ title: "module", dataIndex: "module" },
-		{ title: "title", dataIndex: "title" },
+		{
+			// R2：solution 角色带 title_key → 按当前语言实时翻译，title（安装期解析文本）兜底；
+			// custom/builtin 无 key 原样显示 title（对齐下方权限点 title_key 的渲染先例）
+			title: "title",
+			dataIndex: "title",
+			render: (_: string, row: RoleRow) => (row.title_key ? t(row.title_key, { defaultValue: row.title ?? "" }) : row.title),
+		},
 		{ title: t("system:rolesPage.holders"), dataIndex: "holders" },
 		{
 			title: t("system:rolesPage.permissions"),