@oj-module/cli 0.2.56 → 0.2.62

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"),

package/templates/tests/lifecycle/role-title-translate.spec.ts

@@ -0,0 +1,171 @@
+// BDD：solution 角色 title 落库时同步翻译（R1–R6，计划 docs/plans/20261103-0948-role-title-translate）。
+// title = 解析文本（站点默认语言）、title_key = 原文（UI 实时翻译锚）；解析失败回退裸 key，
+// 绝不失败安装（R1）；升级元数据覆盖 = 重解析（R3）；迁移 0018 对存量 solution 角色回填、
+// builtin 不动（R2/AC4）；sys_permission 不变（R5）；name/code/绑定不变（R6）。
+/* eslint-disable test/prefer-lowercase-title -- AC 编号是验收锚点，保留大写（register.spec 同约定） */
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+import { registerSolution, resolveDeclTitles, siteLanguage } from "../../src/app/api/_platform/_lifecycle/steps/register";
+import { installDb } from "../fixture";
+
+const req = createRequire(import.meta.url);
+const { DatabaseSync } = req("node:sqlite");
+const { readFileSync } = req("node:fs");
+const { dirname, join } = req("node:path");
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const enc = new TextEncoder();
+
+let dbo: ReturnType<typeof installDb>;
+const g = globalThis as any;
+
+beforeAll(() => {
+	dbo = installDb();
+	g.http = {};
+});
+
+afterEach(() => {
+	g.http = {};
+	dbo.exec("DELETE FROM sys_role_permission");
+	dbo.exec("DELETE FROM sys_user_role");
+	dbo.exec("DELETE FROM sys_permission");
+	dbo.exec("DELETE FROM sys_role");
+	dbo.exec("DELETE FROM sys_solution_route");
+	dbo.exec("DELETE FROM sys_setting");
+	dbo.exec("DELETE FROM sys_oplog");
+});
+
+function roleRows() {
+	return dbo.prepare("SELECT name, title, title_key FROM sys_role ORDER BY name").all() as Array<{ name: string, title: string | null, title_key: string | null }>;
+}
+
+/** readFile 假面：包内 locales 按路径精确映射，未命中即「文件不存在」 */
+function fakeReadFile(staging: string, files: Record<string, string>) {
+	return async (p: string) => {
+		const hit = files[p];
+		if (hit === undefined)
+			throw new Error(`ENOENT: ${p}`);
+		return enc.encode(hit);
+	};
+}
+
+const STAGING = "/staging";
+const PM_LOCALES = {
+	[`${STAGING}/web/modules/pm/locales/zh-CN.json`]: JSON.stringify({ role: { sales: "销售", admin: "方案管理员" } }),
+	[`${STAGING}/web/modules/pm/locales/en-US.json`]: JSON.stringify({ role: { sales: "Sales", admin: "Solution Admin" } }),
+};
+
+function pmDecl(title: string) {
+	return {
+		module: "pm",
+		version: "1.0.0",
+		roles: [{ name: "pm.sales", title, title_key: title, permissions: ["pm.doc.create"] as string[] }],
+		permissions: ["pm.doc.create"],
+	};
+}
+
+describe("R4 语言取值", () => {
+	it("缺省 zh-CN（sys_setting 无 site.language 行）", async () => {
+		expect(await siteLanguage()).toBe("zh-CN");
+	});
+
+	it("站点设置 site.language 生效（R4：站点默认语言）", async () => {
+		await g.db.table("sys_setting").insert({ key: "site.language", module: "framework", group: "site", type: "string", value: "en-US", update_time: Date.now(), deprecated: 0 }).run();
+		expect(await siteLanguage()).toBe("en-US");
+	});
+});
+
+describe("R1 注册时解析（resolveDeclTitles）", () => {
+	it("AC1 首装：title_key 解析为站点语言 locale 文本", async () => {
+		const resolved = await resolveDeclTitles(pmDecl("pm:role.sales"), STAGING, "zh-CN", fakeReadFile(STAGING, PM_LOCALES));
+		expect(resolved.roles[0]!.title).toBe("销售");
+		expect(resolved.roles[0]!.title_key).toBe("pm:role.sales");
+	});
+
+	it("R4：语言参数决定读取的 locale 文件", async () => {
+		const resolved = await resolveDeclTitles(pmDecl("pm:role.sales"), STAGING, "en-US", fakeReadFile(STAGING, PM_LOCALES));
+		expect(resolved.roles[0]!.title).toBe("Sales");
+	});
+
+	it("AC3 缺 key：保留裸 key（title 原样），绝不抛错", async () => {
+		const files = { [`${STAGING}/web/modules/pm/locales/zh-CN.json`]: JSON.stringify({ role: { sales: "销售" } }) };
+		const resolved = await resolveDeclTitles(pmDecl("pm:role.admin"), STAGING, "zh-CN", fakeReadFile(STAGING, files));
+		expect(resolved.roles[0]!.title).toBe("pm:role.admin");
+	});
+
+	it("R1 边界：locale 文件缺失 / 坏 JSON / 非 string 值 / 空 key 形状不符 → 原文保留", async () => {
+		const noFile = await resolveDeclTitles(pmDecl("pm:role.sales"), STAGING, "zh-CN", fakeReadFile(STAGING, {}));
+		expect(noFile.roles[0]!.title).toBe("pm:role.sales");
+
+		const badJson = await resolveDeclTitles(pmDecl("pm:role.sales"), STAGING, "zh-CN", fakeReadFile(STAGING, { [`${STAGING}/web/modules/pm/locales/zh-CN.json`]: "{not-json" }));
+		expect(badJson.roles[0]!.title).toBe("pm:role.sales");
+
+		const nonString = await resolveDeclTitles(pmDecl("pm:role.sales"), STAGING, "zh-CN", fakeReadFile(STAGING, { [`${STAGING}/web/modules/pm/locales/zh-CN.json`]: JSON.stringify({ role: { sales: 42 } }) }));
+		expect(nonString.roles[0]!.title).toBe("pm:role.sales");
+
+		// 非 key 形状（中文文本）不做解析尝试——已解析文本二次注册不被误改
+		const plain = await resolveDeclTitles(pmDecl("销售"), STAGING, "zh-CN", fakeReadFile(STAGING, PM_LOCALES));
+		expect(plain.roles[0]!.title).toBe("销售");
+	});
+
+	it("R1 边界：ns ≠ 模块名不越界解析（跨 ns 无本包 locale）", async () => {
+		const decl = { ...pmDecl("wiki:role.sales"), module: "pm" };
+		const resolved = await resolveDeclTitles(decl, STAGING, "zh-CN", fakeReadFile(STAGING, PM_LOCALES));
+		expect(resolved.roles[0]!.title).toBe("wiki:role.sales");
+	});
+});
+
+describe("R1–R3 落库（registerSolution 消费解析后的 decl）", () => {
+	it("AC1 首装：sys_role 落 (title=销售, title_key=pm:role.sales)，权限点照常", async () => {
+		const resolved = await resolveDeclTitles(pmDecl("pm:role.sales"), STAGING, "zh-CN", fakeReadFile(STAGING, PM_LOCALES));
+		const r = await registerSolution(resolved);
+		expect(r.ok).toBe(true);
+		const rows = roleRows();
+		expect(rows).toEqual([{ name: "pm.sales", title: "销售", title_key: "pm:role.sales" }]);
+		const perms = dbo.prepare("SELECT code FROM sys_permission").all() as Array<{ code: string }>;
+		expect(perms.map(p => p.code)).toEqual(["pm.doc.create"]);
+	});
+
+	it("AC2 升级：元数据覆盖写新解析文本 + title_key 刷新（R3 locale 改进随升级传播）", async () => {
+		await registerSolution(await resolveDeclTitles(pmDecl("pm:role.sales"), STAGING, "zh-CN", fakeReadFile(STAGING, PM_LOCALES)));
+		const improved = fakeReadFile(STAGING, { [`${STAGING}/web/modules/pm/locales/zh-CN.json`]: JSON.stringify({ role: { sales: "销售冠军" } }) });
+		const r = await registerSolution(await resolveDeclTitles(pmDecl("pm:role.sales"), STAGING, "zh-CN", improved));
+		expect(r.ok).toBe(true);
+		expect(roleRows()).toEqual([{ name: "pm.sales", title: "销售冠军", title_key: "pm:role.sales" }]);
+	});
+
+	it("AC3 缺 key：注册不失败，title = 裸 key（现行回退形态）", async () => {
+		const r = await registerSolution(await resolveDeclTitles(pmDecl("pm:role.viewer"), STAGING, "zh-CN", fakeReadFile(STAGING, PM_LOCALES)));
+		expect(r.ok).toBe(true);
+		expect(roleRows()).toEqual([{ name: "pm.sales", title: "pm:role.viewer", title_key: "pm:role.viewer" }]);
+	});
+});
+
+describe("R2 迁移 0018（sys_role.title_key 回填）", () => {
+	it("AC4 夹具真实迁移后 sys_role 带 title_key 列（列进库 ↔ schema.yaml 一致守卫的库侧半边）", () => {
+		const cols = (dbo.prepare("PRAGMA table_info(sys_role)").all() as Array<{ name: string }>).map(c => c.name);
+		expect(cols).toContain("title_key");
+	});
+
+	it("AC4 存量 solution 角色按 key 形状回填，builtin 角色不动、title 原文不改", () => {
+		const raw = new DatabaseSync(":memory:");
+		raw.exec(`
+			CREATE TABLE sys_role (
+				name TEXT PRIMARY KEY, module TEXT NOT NULL, title TEXT, description TEXT,
+				builtin INTEGER NOT NULL DEFAULT 0, deprecated INTEGER NOT NULL DEFAULT 0
+			);
+			INSERT INTO sys_role (name, module, title, builtin) VALUES
+				('pm.sales', 'pm', 'pm:role.sales', 0),
+				('wiki.admin', 'wiki', 'wiki:role.admin', 0),
+				('admin', 'framework', '系统管理员', 1);
+		`);
+		raw.exec(readFileSync(join(HERE, "../../src/app/api/_platform/migrations/0018__sys_role_title_key.sql"), "utf8"));
+		const rows = raw.prepare("SELECT name, title, title_key FROM sys_role ORDER BY name").all() as Array<{ name: string, title: string, title_key: string | null }>;
+		expect(rows).toEqual([
+			{ name: "admin", title: "系统管理员", title_key: null },
+			{ name: "pm.sales", title: "pm:role.sales", title_key: "pm:role.sales" },
+			{ name: "wiki.admin", title: "wiki:role.admin", title_key: "wiki:role.admin" },
+		]);
+	});
+});

package/templates/tests/rbac-roles.spec.ts

@@ -157,6 +157,15 @@ describe("列表支撑（C2 页面数据源）", () => {
 		expect(perms.find(p => p.code === "wiki.new")?.deprecated).toBe(false);
 	});
 
+	it("listRoles 带出 title_key（R2：solution 角色 UI 实时翻译锚；custom/builtin 为 null）", async () => {
+		// solution 角色带 title_key（0018 起）；custom 角色管理员手填 title、无 key
+		dbo.prepare("INSERT INTO sys_role (name, module, title, title_key, builtin) VALUES ('pm.sales', 'pm', '销售', 'pm:role.sales', 0)").run();
+		await createRole({ name: "custom.tk", title: "手填" });
+		const roles = await listRoles();
+		expect(roles.find(x => x.name === "pm.sales")?.title_key).toBe("pm:role.sales");
+		expect(roles.find(x => x.name === "custom.tk")?.title_key).toBe(null);
+	});
+
 	it("listRoles 原样返回 superadmin（只在 /system/roles 展示层隐去）", async () => {
 		// 成员资格页（users/roles.tsx）把 superadmin 当可授予项（仅 superadmin 可勾选），
 		// 页面数据源里少了它会让「授予超级管理员」直接不可用。过滤只做在展示层。

package/vendor/host-versions.json

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