@oj-module/cli 0.2.67 → 0.2.68

package/templates/src/README.md

@@ -0,0 +1,37 @@
+# src/ 目录说明（动手前必读）
+
+这个目录里有两类东西，规矩不一样。
+
+## 框架自带的模块（不许改）
+
+- `src/app/` —— 框架内置页面与后端（登录、首页、个人中心、通知、系统管理、认证等）
+- `src/oj-market/` —— 解决方案市场
+
+它们由上游统一维护、跟着框架版本走。**请不要修改、也不要删除这里的文件**：
+
+- `ojm build` 打包前会逐文件核对这两个目录，发现与官方版本不一致（改过、删过、
+  或多出文件）会**直接拒绝构建**，并列出差异清单。
+- 为什么这么严：你今天改一行，下次升级就对不上——轻则构建失败，重则升级后
+  功能悄悄丢失。上游修过的 bug，会在你本地"复活"。
+- 想改功能、加需求？给上游提 issue，等新版本下发后运行：
+
+  ```
+  ojm init --yes
+  ```
+
+  它会把这两个目录恢复成当前版本的官方内容。注意：**会丢弃你在里面的本地修改**，
+  执行前先备份。你自己的模块和 config.yaml 等工程配置不受影响。
+- 真的不想要某个自带能力？在 `web.config.ts` 里把对应条目写 `enabled: false`，
+  不要删目录。
+- 删除 `src/.ojm-builtin.json` 会整个关掉上面的检查——不建议，出了问题没人替你兜底。
+
+## 你自己的模块（随便改）
+
+- `src/<你的模块名>/` —— 用 `ojm new <名字>` 生成，或手工建 `src/<名字>/{api,web}`。
+
+这里是你的地盘：框架不检查、也不会覆盖。
+
+## 一句话总结
+
+> `src/app` 和 `src/oj-market` 是"公家"的，`src/` 下其他目录是你自己的。
+> 公家的不许动（动了 `ojm build` 会拦）；要动找上游；升级后跑 `ojm init --yes` 同步。

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

@@ -302,11 +302,15 @@ export function declOf(req: InstallRequest): SolutionDecl {
 			title_key: typeof r.title_key === "string" ? r.title_key : undefined,
 			permissions: Array.isArray(r.permissions) ? r.permissions.map(String) : [],
 		})),
-		// 顶层 permissions[] 的 code：无角色权限点（系统预置点）唯一能落库的来源，别在此丢弃
+		// 顶层 permissions[] 透传 code + title_key（R2 展示锚随落库走，别在校验后丢弃）：
+		// 无角色权限点（系统预置点）唯一能落库的来源
 		permissions: (Array.isArray(m.permissions) ? m.permissions : [])
 			.filter(isObj)
-			.map(p => (typeof p.code === "string" ? p.code : ""))
-			.filter(Boolean),
+			.map(p => ({
+				code: typeof p.code === "string" ? p.code : "",
+				title_key: typeof p.title_key === "string" ? p.title_key : undefined,
+			}))
+			.filter(p => p.code !== ""),
 		settings,
 		routes: (Array.isArray(m.routes) ? m.routes : []).filter(isObj).map(r => ({
 			path: typeof r.path === "string" ? r.path : "",

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

@@ -15,16 +15,22 @@ export interface SolutionRoleDecl {
 	permissions?: string[]
 }
 
+export interface SolutionPermDecl {
+	code: string
+	/** 原始 i18n key（R2 展示锚：C2-15 必填校验的落地处，缺省 null = 展示回退裸 code） */
+	title_key?: string
+}
+
 export interface SolutionManifest {
 	module: string
 	roles: SolutionRoleDecl[]
 	/**
-	 * 顶层 `permissions[]` 的 code 清单（契约 C2-15 的声明面）。
+	 * 顶层 `permissions[]` 声明（契约 C2-15；code + title_key）。
 	 * 与 `roles[].permissions` **不是**上下级关系：C2-16 只要求角色引用的 code 先在此声明，
 	 * 反过来「声明了但没有任何角色引用」是合法形态（系统预置权限点，由管理员在管理面自行分配）。
 	 * 漏收集的后果是这类权限点根本不落库 → 管理面绑不上 → 声明形同虚设。
 	 */
-	permissions?: string[]
+	permissions?: SolutionPermDecl[]
 }
 
 export interface UpsertResult {
@@ -35,15 +41,21 @@ export interface UpsertResult {
 export async function upsertSolutionPerms(m: SolutionManifest): Promise<UpsertResult> {
 	const deprecated: string[] = [];
 	const declaredRoles = new Set(m.roles.map(r => r.name));
-	// 权限点全集 = 角色引用的 ∪ 顶层独立声明的（后者是无角色权限点唯一能落库的来源）
-	const declaredPerms = new Set([...m.roles.flatMap(r => r.permissions ?? []), ...(m.permissions ?? [])]);
+	// 权限点全集 = 角色引用的 ∪ 顶层独立声明的（后者是无角色权限点唯一能落库的来源）；
+	// title_key 是 R2 展示锚，随 code 一起落库
+	const declaredPerms = new Map<string, string | undefined>([
+		// 角色引用的裸 code 先入（无 title_key），顶层声明（C2-15 携 title_key）后入覆盖——后者权威
+		...m.roles.flatMap(r => r.permissions ?? []).map(c => [c, undefined] as const),
+		...m.permissions?.map(p => [p.code, p.title_key] as const) ?? [],
+	]);
 
 	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/title_key——R3 升级即重解析：新包 locale 改进随升级传播），
+		// upsert：行存在只覆盖元数据（title/title_key——R3 升级即重解析：新包 locale 改进随升级传播；
+		// deprecated 复位 = 重声明回到声明态，对齐 settings/routes 注册面纪律），
 		// name/builtin 不动（AC2-2 元数据覆盖）
 		if (existing.length) {
-			await db.table("sys_role").update({ title: role.title, title_key: role.title_key ?? null }).where({ field: "name", op: "eq", value: role.name }).run();
+			await db.table("sys_role").update({ title: role.title, title_key: role.title_key ?? null, deprecated: 0 }).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, title_key: role.title_key ?? null, builtin: 0 }).run();
@@ -58,12 +70,15 @@ export async function upsertSolutionPerms(m: SolutionManifest): Promise<UpsertRe
 		}
 	}
 
-	// 权限点行独立于角色创建：声明里的新 code 一律 upsert 插入（AC2-1「新增声明 → upsert 插入新行」——
-	// 含既有角色新增权限点的场景；绑定是否自动挂上由上面的角色级规则决定）
-	for (const code of declaredPerms) {
+	// 权限点行独立于角色创建：声明里的新 code 一律 upsert（AC2-1「新增声明 → 插入新行」——
+	// 含既有角色新增权限点的场景；绑定是否自动挂上由上面的角色级规则决定）。
+	// 既有行覆写 title_key（R3）并复位 deprecated（重声明回到声明态）；code 是行身份，不动。
+	for (const [code, titleKey] of declaredPerms) {
 		const p = await db.table("sys_permission").select(["code"]).where({ field: "code", op: "eq", value: code }).all() as unknown[];
 		if (!p.length)
-			await db.table("sys_permission").insert({ code, module: m.module }).run();
+			await db.table("sys_permission").insert({ code, module: m.module, title_key: titleKey ?? null }).run();
+		else
+			await db.table("sys_permission").update({ title_key: titleKey ?? null, deprecated: 0 }).where({ field: "code", op: "eq", value: code }).run();
 	}
 
 	// 声明消失 → 行保留标 deprecated（AC2-3/4）：行与绑定全留，判决不突变；

package/templates/tests/lifecycle/register.spec.ts

@@ -8,6 +8,7 @@
 /* eslint-disable test/prefer-lowercase-title -- 任务/AC 编号是验收锚点，保留大写（DB/P1-5） */
 import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 
+import { declOf } from "../../src/app/api/_platform/_lifecycle/installer";
 import { checkOccupancy, queryAllRegistered, queryRegistered, registerSolution } from "../../src/app/api/_platform/_lifecycle/steps/register";
 import { installDb } from "../fixture";
 
@@ -192,3 +193,24 @@ describe("审计：auditOp 落 solution.register", () => {
 		expect(JSON.parse(String(r.detail))).toEqual({ routes: 2, settings: 2, deprecated: [] });
 	});
 });
+
+describe("C2 manifest → SolutionDecl 映射（declOf，installer 侧纯函数）", () => {
+	it("permissions[].title_key 透传为对象数组（R2 展示锚：C2-15 收藏的字段不得在数据面丢弃）", () => {
+		const decl = declOf({
+			name: "wiki",
+			version: "1.0.0",
+			manifest: {
+				permissions: [
+					{ code: "wiki.doc.read", title_key: "wiki:perm.doc_read" },
+					{ code: "wiki.doc.export", title_key: "wiki:perm.doc_export" },
+				],
+				roles: [{ name: "wiki.reader", title_key: "wiki:role.reader", permissions: ["wiki.doc.read"] }],
+			},
+		} as any);
+		expect(decl.permissions).toEqual([
+			{ code: "wiki.doc.read", title_key: "wiki:perm.doc_read" },
+			{ code: "wiki.doc.export", title_key: "wiki:perm.doc_export" },
+		]);
+		expect(decl.roles[0].title_key).toBe("wiki:role.reader");
+	});
+});

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

@@ -51,8 +51,8 @@ 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"],
+		roles: [{ name: "pm.sales", title, title_key: title, permissions: ["pm.doc.create"] }],
+		permissions: [{ code: "pm.doc.create" }],
 	};
 }
 

package/templates/tests/rbac-solution-perms.spec.ts

@@ -132,6 +132,51 @@ describe("AC2-3/4：声明消失与重命名 → deprecated 保留（判决不
 	});
 });
 
+describe("R2/R3：权限点 title_key 落库（多语言展示锚）与重声明复位", () => {
+	it("R2 title_key 随声明落库：permissions[{code,title_key}] → sys_permission.title_key（缺省→null）", async () => {
+		const r = await upsertSolutionPerms({
+			module: "wiki",
+			roles: [{ name: "wiki.reader", title: "wiki:role.reader", title_key: "wiki:role.reader", permissions: ["wiki.doc.read"] }],
+			permissions: [
+				{ code: "wiki.doc.read", title_key: "wiki:perm.doc_read" },
+				{ code: "wiki.doc.export" }, // 无角色引用的独立声明点；title_key 缺省 → null（宽松态合法）
+			],
+		});
+		expect(r.deprecated).toEqual([]);
+		expect(rows("SELECT title_key FROM sys_permission WHERE code = 'wiki.doc.read'")[0].title_key).toBe("wiki:perm.doc_read");
+		expect(rows("SELECT title_key FROM sys_permission WHERE code = 'wiki.doc.export'")[0].title_key).toBeNull();
+		// 角色侧同口径（既有行为再钉一次，防回归）
+		expect(rows("SELECT title_key FROM sys_role WHERE name = 'wiki.reader'")[0].title_key).toBe("wiki:role.reader");
+	});
+
+	it("R3 既有权限点行 title_key 元数据随升级覆盖（新包 locale 改进随升级传播）", async () => {
+		await upsertSolutionPerms({ module: "wiki", roles: [], permissions: [{ code: "wiki.doc.read", title_key: "wiki:perm.old" }] });
+		await upsertSolutionPerms({ module: "wiki", roles: [], permissions: [{ code: "wiki.doc.read", title_key: "wiki:perm.new" }] });
+		expect(rows("SELECT title_key FROM sys_permission WHERE code = 'wiki.doc.read'")[0].title_key).toBe("wiki:perm.new");
+	});
+
+	it("AC2-3 重声明复位 deprecated=0：权限点与角色行回归声明态（对齐 settings/routes 注册面同纪律）", async () => {
+		await installWikiV019();
+		await upsertSolutionPerms({
+			module: "wiki",
+			roles: [{ name: "wiki.admin", title: "管理员", permissions: ["wiki.doc.create"] }], // space.create 与 editor 消失
+		});
+		expect(Number(rows("SELECT deprecated FROM sys_permission WHERE code = 'wiki.space.create'")[0].deprecated)).toBe(1);
+		expect(Number(rows("SELECT deprecated FROM sys_role WHERE name = 'wiki.editor'")[0].deprecated)).toBe(1);
+		// 下一版本把两者重新声明回来 → deprecated 必须复位，装机告警消停
+		const r = await upsertSolutionPerms({
+			module: "wiki",
+			roles: [
+				{ name: "wiki.admin", title: "管理员", permissions: ["wiki.doc.create", "wiki.space.create"] },
+				{ name: "wiki.editor", title: "编辑", permissions: ["wiki.doc.create"] },
+			],
+		});
+		expect(r.deprecated).toEqual([]);
+		expect(Number(rows("SELECT deprecated FROM sys_permission WHERE code = 'wiki.space.create'")[0].deprecated)).toBe(0);
+		expect(Number(rows("SELECT deprecated FROM sys_role WHERE name = 'wiki.editor'")[0].deprecated)).toBe(0);
+	});
+});
+
 describe("AC2-6：卸载级联清理（唯一减法出口）", () => {
 	it("双维度删除：wiki 角色及其绑定 + 属 wiki 的权限点绑定（含 custom 角色上的）；custom 角色本体保留", async () => {
 		await installWikiV019();
@@ -177,7 +222,7 @@ describe("顶层 permissions[]：无角色的权限点也要落库", () => {
 		await upsertSolutionPerms({
 			module: "oj-registry",
 			roles: [],
-			permissions: ["oj-registry.publish", "oj-registry.admin"],
+			permissions: [{ code: "oj-registry.publish" }, { code: "oj-registry.admin", title_key: "oj-registry:perm.admin" }],
 		});
 
 		expect(rows("SELECT code, module FROM sys_permission ORDER BY code")).toEqual([
@@ -187,7 +232,7 @@ describe("顶层 permissions[]：无角色的权限点也要落库", () => {
 	});
 
 	it("AC2-6 卸载后无角色的权限点一并摘干净（含 custom 角色上的绑定）", async () => {
-		await upsertSolutionPerms({ module: "oj-registry", roles: [], permissions: ["oj-registry.publish"] });
+		await upsertSolutionPerms({ module: "oj-registry", roles: [], permissions: [{ code: "oj-registry.publish" }] });
 		dbo.exec("INSERT INTO sys_role (name, module, title) VALUES ('custom.dev', 'custom', '开发者')");
 		dbo.exec("INSERT INTO sys_role_permission (role_name, permission_code) VALUES ('custom.dev', 'oj-registry.publish')");
 
@@ -202,7 +247,7 @@ describe("顶层 permissions[]：无角色的权限点也要落库", () => {
 	it("G7 攻击者视角：声明权限点不等于拿到权限——落库不产生任何绑定", async () => {
 		// 使坏路径：以为「把 code 写进 manifest 就自动获权」。落库的只是权限点标签行，
 		// 判定仍要角色绑定；没有绑定，decideAccess 对该 code 恒 false。
-		await upsertSolutionPerms({ module: "oj-registry", roles: [], permissions: ["oj-registry.publish"] });
+		await upsertSolutionPerms({ module: "oj-registry", roles: [], permissions: [{ code: "oj-registry.publish" }] });
 
 		expect(rows("SELECT * FROM sys_role_permission WHERE permission_code = 'oj-registry.publish'").length).toBe(0);
 	});

package/templates/web.config.ts

@@ -20,7 +20,9 @@ const allModules = [
 	{ name: "app", entry: "src/app/web/entry.ts" },
 	// 解决方案市场：第一方能力（消费 _platform 编排面 /api/_platform/market/*，
 	// R29：第三方方案不得仿照此调用面），默认随脚手架下发。保持独立模块——
-	// 可选能力，删目录即可下线；发布管理页（/publish）也在这个模块里。
+	// 可选能力，不想要就改 `enabled: false`（不要删目录：src/app、src/oj-market
+	// 受完整性门禁保护，删改会让 ojm build 失败，见 src/README.md）；
+	// 发布管理页（/publish）也在这个模块里。
 	{ name: "oj-market", entry: "src/oj-market/web/entry.ts" },
 	// #region demo-only
 	// 以下为模板内置的演示模块（about/access/exception/outside/route-nest），

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.67",
-		"@oj-module/runtime/contract": "0.2.67",
-		"@oj-module/runtime/contract/errors": "0.2.67",
+		"@oj-module/runtime": "0.2.68",
+		"@oj-module/runtime/contract": "0.2.68",
+		"@oj-module/runtime/contract/errors": "0.2.68",
 		"@plane/kit": "0.1.20",
 		"@plane/editor": "0.1.20",
 		"antd": "6.6.1",