@oj-module/cli 0.1.21 → 0.2.1

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

@@ -0,0 +1,159 @@
+// BDD：角色管理应用服务——CRUD 契约、命名空间红线、binding 编辑（含紧急吊销=写时失效）、占用禁删、写审计。
+// AC 锚点：AC1-16/17（建角色）、AC1-18（声明角色绑定可调整）、AC1-19（builtin 无编辑入口）、
+//          AC1-20（占用禁删）、AC1-28（写审计三动作）、AC1-30（摘绑定下一次请求即 403）。
+/* eslint-disable test/prefer-lowercase-title -- AC 编号是验收锚点，保留大写 */
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+
+import { assertPermission } from "../src/_platform/_shared/service/access";
+import { createRole, deleteRole, listPermissions, listRoles, updateBindings } from "../src/_platform/_shared/service/roles";
+import { installDb } from "./fixture";
+
+let dbo: ReturnType<typeof installDb>;
+const g = globalThis as any;
+
+function mkUser(username: string): number {
+	dbo.prepare("INSERT INTO users (username, password_hash) VALUES (?, 'x')").run(username);
+	return (dbo.prepare("SELECT id FROM users WHERE username = ?").get(username) as { id: number }).id;
+}
+
+function bindRole(userId: number, role: string) {
+	dbo.prepare("INSERT OR IGNORE INTO sys_user_role (user_id, role_name) VALUES (?, ?)").run(userId, role);
+}
+
+function seedPerm(code: string, deprecated = 0) {
+	dbo.prepare("INSERT OR IGNORE INTO sys_permission (code, module, deprecated) VALUES (?, ?, ?)")
+		.run(code, code.split(".")[0], deprecated);
+}
+
+function oplog(action: string) {
+	return dbo.prepare("SELECT * FROM sys_oplog WHERE action = ? ORDER BY id").all(action) as Record<string, unknown>[];
+}
+
+beforeAll(() => {
+	dbo = installDb();
+	g.http = { user: { id: 1 } }; // admin 操作者（审计 username 解析用）
+});
+
+afterEach(() => {
+	dbo.exec("DELETE FROM sys_role_permission");
+	dbo.exec("DELETE FROM sys_role");
+	dbo.exec("DELETE FROM sys_user_role");
+	dbo.exec("DELETE FROM sys_permission");
+	dbo.exec("DELETE FROM sys_oplog");
+	dbo.exec("DELETE FROM users WHERE username LIKE 'u%'");
+});
+
+describe("AC1-16/17：建角色（custom 命名空间强制 + 绑定写入）", () => {
+	it("建 custom.reviewer 并勾选绑定：sys_role + sys_role_permission 双写，module=custom", async () => {
+		seedPerm("wiki.doc.create");
+		seedPerm("crm.contact.create");
+		const role = await createRole({
+			name: "custom.reviewer",
+			title: "内容审核员",
+			permissions: ["wiki.doc.create", "crm.contact.create"],
+		});
+		expect(role.name).toBe("custom.reviewer");
+		expect(role.module).toBe("custom");
+		const row = dbo.prepare("SELECT builtin FROM sys_role WHERE name = 'custom.reviewer'").get() as { builtin: number };
+		expect(Number(row.builtin)).toBe(0);
+		const binds = dbo.prepare("SELECT permission_code FROM sys_role_permission WHERE role_name = 'custom.reviewer' ORDER BY permission_code").all();
+		expect(binds.map((b: any) => b.permission_code)).toEqual(["crm.contact.create", "wiki.doc.create"]);
+	});
+
+	it("AC1-17 保留名/ solutions 命名空间/裸名一律 400", async () => {
+		await expect(createRole({ name: "admin", title: "x" })).rejects.toMatchObject({ status: 400 });
+		await expect(createRole({ name: "wiki.admin", title: "x" })).rejects.toMatchObject({ status: 400 });
+		await expect(createRole({ name: "reviewer", title: "x" })).rejects.toMatchObject({ status: 400 });
+	});
+
+	it("不存在的权限点拒绝（绑定必须落真实权限点）", async () => {
+		await expect(createRole({ name: "custom.ops", title: "x", permissions: ["ghost.act"] }))
+			.rejects
+			.toMatchObject({ status: 400 });
+	});
+
+	it("AC1-28 role.create 写审计（module=framework）", async () => {
+		await createRole({ name: "custom.audited", title: "审计钉" });
+		const [r] = oplog("role.create");
+		expect(r).toBeDefined();
+		expect(r.module).toBe("framework");
+		expect(r.target).toBe("custom.audited");
+	});
+});
+
+describe("AC1-18/19/30：绑定编辑", () => {
+	it("AC1-18 声明角色绑定可调整：替换写 sys_role_permission", async () => {
+		dbo.prepare("INSERT INTO sys_role (name, module, builtin) VALUES ('wiki.editor', 'wiki', 0)").run();
+		seedPerm("wiki.doc.create");
+		seedPerm("wiki.doc.delete");
+		await updateBindings("wiki.editor", ["wiki.doc.delete"]);
+		const codes = dbo.prepare("SELECT permission_code FROM sys_role_permission WHERE role_name = 'wiki.editor'").all();
+		expect(codes.map((c: any) => c.permission_code)).toEqual(["wiki.doc.delete"]);
+	});
+
+	it("AC1-19 builtin 角色（superadmin/admin/editor/viewer）绑定编辑 403 硬拒", async () => {
+		dbo.prepare("INSERT INTO sys_role (name, module, builtin) VALUES ('editor', 'framework', 1)").run();
+		await expect(updateBindings("editor", ["wiki.doc.create"])).rejects.toMatchObject({ status: 403 });
+	});
+
+	it("AC1-30 紧急吊销：superadmin 摘绑定 → 持有者下一次判权即 403（写时失效）", async () => {
+		seedPerm("wiki.doc.create");
+		await createRole({ name: "custom.dave", title: "dave", permissions: ["wiki.doc.create"] });
+		const uid = mkUser("udave");
+		bindRole(uid, "custom.dave");
+		g.http = { user: { id: uid } };
+		await expect(assertPermission("wiki.doc.create")).resolves.toBeUndefined();
+		g.http = { user: { id: 1 } };
+		await updateBindings("custom.dave", []);
+		g.http = { user: { id: uid } };
+		await expect(assertPermission("wiki.doc.create")).rejects.toMatchObject({ status: 403 });
+	});
+
+	it("AC1-28 role.bindings.update 审计带增删明细", async () => {
+		seedPerm("wiki.a");
+		seedPerm("wiki.b");
+		await createRole({ name: "custom.diff", title: "x", permissions: ["wiki.a"] });
+		await updateBindings("custom.diff", ["wiki.b"]);
+		const [r] = oplog("role.bindings.update");
+		expect(JSON.parse(String(r.detail))).toEqual({ added: ["wiki.b"], removed: ["wiki.a"] });
+	});
+});
+
+describe("AC1-20：占用禁删", () => {
+	it("有持有者的角色删除被拒并给出人数；清空后可删", async () => {
+		await createRole({ name: "custom.held", title: "x" });
+		const u1 = mkUser("u1");
+		const u2 = mkUser("u2");
+		bindRole(u1, "custom.held");
+		bindRole(u2, "custom.held");
+		await expect(deleteRole("custom.held")).rejects.toMatchObject({ status: 409, holders: 2 });
+		dbo.exec("DELETE FROM sys_user_role WHERE role_name = 'custom.held'");
+		await expect(deleteRole("custom.held")).resolves.toBeUndefined();
+		expect(dbo.prepare("SELECT * FROM sys_role WHERE name = 'custom.held'").get()).toBeUndefined();
+	});
+
+	it("builtin 角色删除 403；AC1-28 role.delete 审计落表", async () => {
+		dbo.prepare("INSERT INTO sys_role (name, module, builtin) VALUES ('viewer', 'framework', 1)").run();
+		await expect(deleteRole("viewer")).rejects.toMatchObject({ status: 403 });
+		await createRole({ name: "custom.todel", title: "x" });
+		await deleteRole("custom.todel");
+		expect(oplog("role.delete").length).toBe(1);
+	});
+});
+
+describe("列表支撑（C2 页面数据源）", () => {
+	it("listRoles 带持有计数与绑定数；listPermissions 带 deprecated 标灰标记", async () => {
+		seedPerm("wiki.old", 1);
+		seedPerm("wiki.new");
+		await createRole({ name: "custom.ls", title: "列表", permissions: ["wiki.old"] });
+		const uid = mkUser("uls");
+		bindRole(uid, "custom.ls");
+		const roles = await listRoles();
+		const r = roles.find(x => x.name === "custom.ls");
+		expect(r?.holders).toBe(1);
+		expect(r?.permissions).toEqual(["wiki.old"]);
+		const perms = await listPermissions();
+		expect(perms.find(p => p.code === "wiki.old")?.deprecated).toBe(true);
+		expect(perms.find(p => p.code === "wiki.new")?.deprecated).toBe(false);
+	});
+});

package/templates/api/tests/rbac-seed.spec.ts

@@ -0,0 +1,54 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// BDD：seed 契约——框架内置角色 + seed 超管绑定 + must_change 首登改密（D12/AC1-27）。
+// 夹具重放真实 migrations + seed.sql 文件，本 spec 即「seed 与文件不漂移」的钉子。
+import { beforeAll, describe, expect, it } from "vitest";
+
+import { installDb } from "./fixture";
+
+const SEED = join(dirname(fileURLToPath(import.meta.url)), "..", "src", "_platform", "seed.sql");
+let dbo: ReturnType<typeof installDb>;
+
+beforeAll(() => {
+	dbo = installDb();
+	// 清空夹具预插的 users，让 seed 成为 users 数据的唯一来源（INSERT OR IGNORE 依赖空表语义）
+	dbo.prepare("DELETE FROM users").run();
+	// seed 朴素按分号切分（与 oj 运行时同规则；注释内禁英文分号是 seed.sql 头的纪律）；
+	// 每个语句块先剥掉整行注释再执行（注释与语句同行出现是 seed 文件自身的纪律约束）
+	for (const stmt of readFileSync(SEED, "utf8").split(";")) {
+		const sql = stmt.split("\n").filter(l => !l.trim().startsWith("--")).join("\n").trim();
+		if (sql)
+			dbo.exec(sql);
+	}
+});
+
+describe("框架内置角色（ROLES 常量单一真相，PRD §4.2）", () => {
+	it.each([
+		["superadmin", "超级管理员"],
+		["admin", "系统管理员"],
+		["editor", "编辑"],
+		["viewer", "访客"],
+	])("seed 出 builtin 角色 %s", (name, title) => {
+		const row = dbo.prepare("SELECT * FROM sys_role WHERE name = ?").get(name) as Record<string, unknown>;
+		expect(row).toBeDefined();
+		expect(row.module).toBe("framework");
+		expect(Number(row.builtin)).toBe(1);
+		expect(row.title).toBe(title);
+	});
+});
+
+describe("seed 超管（D12）", () => {
+	// AUTOINCREMENT 不复用 id（sqlite_sequence 语义），统一按 username 动态解析，不钉死 id
+	const adminId = () => (dbo.prepare("SELECT id FROM users WHERE username = 'admin'").get() as { id: number }).id;
+
+	it("admin 账号绑定 superadmin 角色（sys_user_role 权威源）", () => {
+		const row = dbo.prepare("SELECT * FROM sys_user_role WHERE user_id = ? AND role_name = 'superadmin'").get(adminId());
+		expect(row).toBeDefined();
+	});
+
+	it("must_change=1：首登强制改密（AC1-27 前提）", () => {
+		const row = dbo.prepare("SELECT must_change FROM users WHERE id = ?").get(adminId()) as { must_change: number };
+		expect(Number(row.must_change)).toBe(1);
+	});
+});

package/templates/api/tests/rbac-settings.spec.ts

@@ -0,0 +1,79 @@
+// BDD：后端 C 期补口——操作日志查询（AC1-29/D13 admin 可查）、系统设置（PRD §4.3）、登录方式发现（C5/D2 匿名）。
+/* eslint-disable test/prefer-lowercase-title -- AC 编号是验收锚点，保留大写 */
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+
+import { searchOplog } from "../src/_platform/_shared/service/oplog";
+import { listLoginMethods, listSettings, updateSetting } from "../src/_platform/_shared/service/settings";
+import { installDb } from "./fixture";
+
+let dbo: ReturnType<typeof installDb>;
+const g = globalThis as any;
+
+function mkOplog(username: string, action: string, module: string, level = 6) {
+	dbo.prepare("INSERT INTO sys_oplog (create_time, user_id, username, action, module, level) VALUES (?, 1, ?, ?, ?, ?)")
+		.run(1000, username, action, module, level);
+}
+
+beforeAll(() => {
+	dbo = installDb();
+});
+
+afterEach(() => {
+	g.http = {};
+	dbo.exec("DELETE FROM sys_oplog");
+	dbo.exec("DELETE FROM sys_setting");
+});
+
+describe("AC1-29/D13：操作日志查询（admin 可查）", () => {
+	it("按 action/username/module 过滤 + 分页截断标记", async () => {
+		mkOplog("alice", "role.create", "framework");
+		mkOplog("alice", "user.create", "framework");
+		mkOplog("bob", "role.create", "framework");
+		const all = await searchOplog({});
+		expect(all.total).toBe(3);
+		const byAction = await searchOplog({ action: "user.create" });
+		expect(byAction.list.map(r => r.username)).toEqual(["alice"]);
+		const byUser = await searchOplog({ username: "bob" });
+		expect(byUser.total).toBe(1);
+	});
+
+	it("403 拒绝类（auth.deny）可在日志中检索", async () => {
+		mkOplog("mallory", "auth.deny", "wiki", 4);
+		const r = await searchOplog({ action: "auth.deny" });
+		expect(r.total).toBe(1);
+	});
+});
+
+describe("PRD §4.3：系统设置", () => {
+	it("按 group 返回设置项（secret 项掩码）", async () => {
+		dbo.prepare("INSERT INTO sys_setting (key, module, \"group\", type, value, secret, update_time) VALUES ('framework.site_title', 'framework', 'general', 'string', 'ACME', 0, 0)").run();
+		dbo.prepare("INSERT INTO sys_setting (key, module, \"group\", type, value, secret, update_time) VALUES ('market.cdn_url', 'market', 'security', 'string', 'https://cdn.example.com', 1, 0)").run();
+		const groups = await listSettings();
+		const general = groups.find(x => x.group === "general");
+		expect(general?.items.find(i => i.key === "framework.site_title")?.value).toBe("ACME");
+		const security = groups.find(x => x.group === "security");
+		expect(security?.items.find(i => i.key === "market.cdn_url")?.value).toBe("***");
+	});
+
+	it("更新写值 + update_time + 审计（market 安全项须 superadmin 操作者）", async () => {
+		dbo.prepare("INSERT INTO sys_setting (key, module, \"group\", type, value, secret, update_time) VALUES ('framework.site_title', 'framework', 'general', 'string', 'ACME', 0, 0)").run();
+		dbo.prepare("INSERT INTO sys_setting (key, module, \"group\", type, value, secret, update_time) VALUES ('market.cdn_url', 'market', 'security', 'string', 'x', 1, 0)").run();
+		await updateSetting(1, "framework.site_title", "NEW");
+		expect(String((dbo.prepare("SELECT value FROM sys_setting WHERE key = 'framework.site_title'").get() as { value: string }).value)).toBe("NEW");
+		expect(dbo.prepare("SELECT * FROM sys_oplog WHERE action = 'setting.update'").get()).toBeDefined();
+		// 非 superadmin 操作 market 安全项 → 403
+		await expect(updateSetting(1, "market.cdn_url", "https://evil.example.com")).rejects.toMatchObject({ status: 403 });
+	});
+
+	it("未知 key → 404", async () => {
+		await expect(updateSetting(1, "ghost.key", "v")).rejects.toMatchObject({ status: 404 });
+	});
+});
+
+describe("C5/D2：登录方式发现（匿名端点数据源）", () => {
+	it("默认仅 local；LDAP/SSO 开关来自设置项", async () => {
+		expect((await listLoginMethods()).methods).toEqual(["local"]);
+		dbo.prepare("INSERT INTO sys_setting (key, module, \"group\", type, value, update_time) VALUES ('ldap.enabled', 'ldap', 'login', 'bool', '1', 0)").run();
+		expect((await listLoginMethods()).methods).toEqual(["local", "ldap"]);
+	});
+});

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

@@ -0,0 +1,168 @@
+// BDD：权限数据升级稳定性（设计 §5 / AC2-1~6）——「模拟安装器 upsert 逻辑」单元层钉死规则。
+// 安装器本体属 PRD M5；本文件钉死的是安装器必须调用的框架规则出口（upsert/uninstall），
+// 端到端（真 manifest 走真安装器）延后至 M5 验收。
+/* eslint-disable test/prefer-lowercase-title -- AC 编号是验收锚点，保留大写 */
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+
+import { uninstallSolution, upsertSolutionPerms } from "../src/_platform/_shared/service/solution-perms";
+import { installDb } from "./fixture";
+
+let dbo: ReturnType<typeof installDb>;
+
+beforeAll(() => {
+	dbo = installDb();
+});
+
+afterEach(() => {
+	dbo.exec("DELETE FROM sys_role_permission");
+	dbo.exec("DELETE FROM sys_user_role WHERE role_name != 'superadmin'"); // 夹具超管绑定常驻
+	dbo.exec("DELETE FROM users WHERE username LIKE 'u_%'");
+	dbo.exec("DELETE FROM sys_permission");
+	dbo.exec("DELETE FROM sys_role WHERE builtin = 0");
+	dbo.exec("UPDATE sys_role SET deprecated = 0");
+	dbo.exec("UPDATE sys_permission SET deprecated = 0");
+});
+
+/** 模拟 wiki 0.1.9 首次安装：声明 editor/admin 两角色与两个权限点。 */
+async function installWikiV019() {
+	await upsertSolutionPerms({
+		module: "wiki",
+		roles: [
+			{ name: "wiki.admin", title: "管理员", permissions: ["wiki.doc.create", "wiki.space.create"] },
+			{ name: "wiki.editor", title: "编辑", permissions: ["wiki.doc.create"] },
+		],
+	});
+}
+
+function rows(sql: string) {
+	return dbo.prepare(sql).all() as Record<string, unknown>[];
+}
+
+describe("AC2-1/2/5：升级只做加法与元数据覆盖", () => {
+	it("AC2-1 新增声明 → upsert 插入新行；既有绑定与判决不变", async () => {
+		await installWikiV019();
+		// 管理员手动撤掉 wiki.editor 的 wiki.doc.create（AC1-15 前态）
+		dbo.exec("DELETE FROM sys_role_permission WHERE role_name = 'wiki.editor' AND permission_code = 'wiki.doc.create'");
+		const before = rows("SELECT * FROM sys_role_permission ORDER BY role_name, permission_code");
+		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"] },
+				{ name: "wiki.guest", title: "访客", permissions: ["wiki.doc.read"] },
+			],
+		});
+		// 新角色/权限点插入
+		expect(rows("SELECT * FROM sys_role WHERE name = 'wiki.guest'").length).toBe(1);
+		expect(rows("SELECT * FROM sys_permission WHERE code = 'wiki.doc.read'").length).toBe(1);
+		// 既有绑定零变动（AC2-5 零减法的一部分：升级不删 sys_role_permission 行）；
+		// after = before + guest 新声明绑定恰好 1 行
+		const after = rows("SELECT * FROM sys_role_permission ORDER BY role_name, permission_code");
+		expect(after.length).toBe(before.length + 1);
+		for (const b of before)
+			expect(after).toContainEqual(b);
+		// guest 的声明绑定 insert-if-absent 写入
+		expect(rows("SELECT * FROM sys_role_permission WHERE role_name = 'wiki.guest' AND permission_code = 'wiki.doc.read'").length).toBe(1);
+		expect(r.deprecated).toEqual([]);
+	});
+
+	it("AC2-2 title 元数据覆盖；判决依据 name/code 不变", async () => {
+		await installWikiV019();
+		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((rows("SELECT title FROM sys_role WHERE name = 'wiki.editor'")[0]).title).toBe("编辑者（新版）");
+		expect(rows("SELECT * FROM sys_role_permission WHERE role_name = 'wiki.editor'").length).toBe(1);
+	});
+
+	it("AC1-15 重复安装同一版本：管理员调整永不被声明覆写（insert-if-absent）", async () => {
+		await installWikiV019();
+		dbo.exec("DELETE FROM sys_role_permission WHERE role_name = 'wiki.editor' AND permission_code = 'wiki.doc.create'");
+		await installWikiV019(); // 同版本重装/重启重放
+		expect(rows("SELECT * FROM sys_role_permission WHERE role_name = 'wiki.editor'").length).toBe(0);
+	});
+});
+
+describe("AC2-3/4：声明消失与重命名 → deprecated 保留（判决不突变）", () => {
+	it("AC2-3 声明消失 → 行保留标 deprecated；持有者绑定继续生效（判权不过滤 deprecated）", async () => {
+		await installWikiV019();
+		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"] },
+			],
+		});
+		const p = rows("SELECT deprecated FROM sys_permission WHERE code = 'wiki.space.create'");
+		expect(p.length).toBe(1); // 行保留
+		expect(Number(p[0].deprecated)).toBe(1); // 标 deprecated
+		// 既有绑定保留（判权链不过滤 deprecated——§5 双向过滤的方向红线）
+		expect(rows("SELECT * FROM sys_role_permission WHERE permission_code = 'wiki.space.create'").length).toBe(1);
+		expect(r.deprecated).toContain("wiki.space.create");
+	});
+
+	it("AC2-4 重命名 = 旧 code 标 deprecated + 新 code 插入；安装器据 deprecated 清单强告警", async () => {
+		await installWikiV019();
+		const r = await upsertSolutionPerms({
+			module: "wiki",
+			roles: [
+				{ name: "wiki.admin", title: "管理员", permissions: ["wiki.doc.write", "wiki.space.create"] }, // doc.create → doc.write
+				{ name: "wiki.editor", title: "编辑", permissions: ["wiki.doc.write"] },
+			],
+		});
+		expect(Number(rows("SELECT deprecated FROM sys_permission WHERE code = 'wiki.doc.create'")[0].deprecated)).toBe(1);
+		expect(rows("SELECT * FROM sys_permission WHERE code = 'wiki.doc.write'").length).toBe(1);
+		// 旧绑定继续生效（不静默变），安装器拿到清单提示「需重新分配」
+		expect(rows("SELECT * FROM sys_role_permission WHERE permission_code = 'wiki.doc.create'").length).toBe(2);
+		expect(r.deprecated).toContain("wiki.doc.create");
+	});
+
+	it("deprecated 角色同样保留标灰：角色行不删、绑定不删", async () => {
+		await installWikiV019();
+		await upsertSolutionPerms({
+			module: "wiki",
+			roles: [{ name: "wiki.admin", title: "管理员", permissions: ["wiki.doc.create", "wiki.space.create"] }], // editor 消失
+		});
+		expect(Number(rows("SELECT deprecated FROM sys_role WHERE name = 'wiki.editor'")[0].deprecated)).toBe(1);
+		expect(rows("SELECT * FROM sys_role_permission WHERE role_name = 'wiki.editor'").length).toBe(1);
+	});
+});
+
+describe("AC2-6：卸载级联清理（唯一减法出口）", () => {
+	it("双维度删除：wiki 角色及其绑定 + 属 wiki 的权限点绑定（含 custom 角色上的）；custom 角色本体保留", async () => {
+		await installWikiV019();
+		// custom 角色跨模块绑了 wiki 权限点
+		dbo.exec("INSERT INTO sys_role (name, module, title) VALUES ('custom.reviewer', 'custom', '审核')");
+		dbo.exec("INSERT INTO sys_role_permission (role_name, permission_code) VALUES ('custom.reviewer', 'wiki.doc.create')");
+		// 两个用户持 wiki 角色
+		dbo.exec("INSERT INTO users (username, password_hash) VALUES ('u_carol', 'x'), ('u_dave', 'x')");
+		dbo.exec("INSERT INTO sys_user_role (user_id, role_name) SELECT id, 'wiki.editor' FROM users WHERE username = 'u_dave'");
+		dbo.exec("INSERT INTO sys_user_role (user_id, role_name) SELECT id, 'wiki.admin' FROM users WHERE username = 'u_carol'");
+
+		await uninstallSolution("wiki");
+
+		// 维度①：wiki 角色行 + 其绑定 + 用户成员资格全清
+		expect(rows("SELECT * FROM sys_role WHERE module = 'wiki'").length).toBe(0);
+		expect(rows("SELECT * FROM sys_role_permission WHERE role_name IN ('wiki.admin','wiki.editor')").length).toBe(0);
+		expect(rows("SELECT * FROM sys_user_role WHERE role_name IN ('wiki.admin','wiki.editor')").length).toBe(0);
+		// 维度②：permission_code 属 wiki 的绑定（custom 角色上的）也清——防重装复活旧授权
+		expect(rows("SELECT * FROM sys_role_permission WHERE permission_code LIKE 'wiki.%'").length).toBe(0);
+		expect(rows("SELECT * FROM sys_permission WHERE module = 'wiki'").length).toBe(0);
+		// custom 角色本体保留（空绑定）
+		expect(rows("SELECT * FROM sys_role WHERE name = 'custom.reviewer'").length).toBe(1);
+	});
+
+	it("AC2-5 卸载也不动其他模块：framework builtin 角色与绑定原样", async () => {
+		await installWikiV019();
+		// 夹具只重放迁移不落 seed——显式补超管绑定作对照组
+		dbo.exec("INSERT OR IGNORE INTO sys_user_role (user_id, role_name) SELECT id, 'superadmin' FROM users WHERE username = 'admin'");
+		const before = rows("SELECT * FROM sys_role WHERE module = 'framework'");
+		await uninstallSolution("wiki");
+		expect(rows("SELECT * FROM sys_role WHERE module = 'framework'")).toEqual(before);
+		expect(rows("SELECT * FROM sys_user_role WHERE role_name = 'superadmin'").length).toBe(1);
+	});
+});

package/templates/api/tests/rbac-tables.spec.ts

@@ -0,0 +1,63 @@
+// BDD：RBAC 六表 + users 扩展列的迁移契约（验收锚点 AC1-7 的数据面；
+// 设计文档 D10/§5.9.2）。夹具重放真实迁移，本 spec 即「迁移与表结构不漂移」的钉子。
+import { beforeAll, describe, expect, it } from "vitest";
+
+import { installDb } from "./fixture";
+
+let dbo: ReturnType<typeof installDb>;
+
+function colsOf(table: string) {
+	return (dbo.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string, notnull: number, dflt_value: unknown }>).map(c => c.name);
+}
+
+beforeAll(() => {
+	dbo = installDb();
+});
+
+describe("sys_* RBAC 表（设计文档 §5.9.2）", () => {
+	it.each([
+		"sys_setting",
+		"sys_oplog",
+		"sys_solution_route",
+		"sys_role",
+		"sys_permission",
+		"sys_role_permission",
+		"sys_user_role",
+	])("迁移建出 %s", (table) => {
+		expect(colsOf(table).length).toBeGreaterThan(0);
+	});
+
+	it("sys_role / sys_permission 带 deprecated 列（升级稳定性 §5 的地基）", () => {
+		expect(colsOf("sys_role")).toContain("deprecated");
+		expect(colsOf("sys_permission")).toContain("deprecated");
+	});
+
+	it("sys_user_role 复合主键 (user_id, role_name)", () => {
+		const pk = dbo.prepare("SELECT COUNT(*) AS n FROM pragma_table_info('sys_user_role') WHERE pk > 0").get() as { n: number };
+		expect(Number(pk.n)).toBe(2);
+	});
+
+	it("sys_oplog 带 (create_time, id) 索引", () => {
+		const idx = dbo.prepare("SELECT name, sql FROM sqlite_master WHERE type='index' AND tbl_name='sys_oplog'").all() as Array<{ name: string, sql: string | null }>;
+		const time = idx.find(i => i.sql?.includes("create_time"));
+		expect(time).toBeDefined();
+		expect(time?.sql).toContain("id");
+	});
+});
+
+describe("users 表扩展（PRD §4.2 数据模型）", () => {
+	it("新增 source / display_name 列", () => {
+		expect(colsOf("users")).toContain("source");
+		expect(colsOf("users")).toContain("display_name");
+	});
+
+	it("移除 users.roles JSON 列（D10：sys_user_role 为唯一权威源）", () => {
+		expect(colsOf("users")).not.toContain("roles");
+	});
+
+	it("source 默认 local（外来号来源标记的默认值）", () => {
+		const info = dbo.prepare("PRAGMA table_info(users)").all() as Array<{ name: string, dflt_value: unknown }>;
+		const source = info.find(c => c.name === "source");
+		expect(String(source?.dflt_value)).toContain("local");
+	});
+});