@oj-module/cli 0.1.21 → 0.2.1

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

@@ -0,0 +1,137 @@
+// 角色管理应用服务（管理域 /api/system/roles，AC1-15~20/28/30）。
+// 规则锚：custom 机器名强制（AC1-17）、builtin 角色绑定/删除硬拒（AC1-19）、占用禁删（AC1-20）、
+// 绑定调整 = 紧急吊销出口（AC1-30，写后按持有者失效判权缓存）、写审计 await recordOp（AC1-28 关键路径）。
+// 判权本身不经过这里——调用 handler 先过 assertSystemAdmin（H2，管理类端点）。
+import { invalidateUser } from "./access";
+import { recordOp } from "./audit";
+
+export interface RoleRow {
+	name: string
+	module: string
+	title: string | null
+	description: string | null
+	builtin: boolean
+	deprecated: boolean
+	/** 持有者人数（占用禁删判据） */
+	holders: number
+	/** 已绑定权限点（含 deprecated——判权不过滤，标灰是 UI 职责） */
+	permissions: string[]
+}
+
+export interface PermissionRow {
+	code: string
+	module: string
+	title_key: string | null
+	deprecated: boolean
+}
+
+function fail(status: number, message: string, extra?: Record<string, unknown>): never {
+	throw Object.assign(new Error(message), { status }, extra);
+}
+
+/** custom 角色机器名：custom.<slug>，slug 小写字母数字连字符（AC1-17 命名空间强制）。 */
+const CUSTOM_NAME = /^custom\.[a-z0-9][a-z0-9-]*$/;
+/** 框架保留名（solutions 命名空间 <name>.* 天然被 custom. 前缀排除） */
+const RESERVED = new Set(["superadmin", "admin", "editor", "viewer"]);
+
+async function assertNotBuiltin(roleName: string): Promise<void> {
+	const rows = await db.query("select builtin from sys_role where name = ?", [roleName]);
+	if (!rows[0])
+		fail(404, `role not found: ${roleName}`);
+	if (Number((rows[0] as { builtin: unknown }).builtin) === 1)
+		fail(403, "builtin role is managed by framework");
+}
+
+async function assertCodesExist(codes: string[]): Promise<void> {
+	if (!codes.length)
+		return;
+	const marks = codes.map(() => "?").join(",");
+	const rows = await db.query(`select code from sys_permission where code in (${marks})`, codes);
+	const known = new Set(rows.map((r: { code: string }) => r.code));
+	const unknown = codes.filter(c => !known.has(c));
+	if (unknown.length)
+		fail(400, `unknown permission codes: ${unknown.join(", ")}`);
+}
+
+/** 绑定/删除写后按持有者逐人失效判权缓存（D10 撤销即强退的 service 级出口）。 */
+async function invalidateHolders(roleName: string): Promise<void> {
+	const rows = await db.query("select user_id from sys_user_role where role_name = ?", [roleName]);
+	for (const r of rows as Array<{ user_id: number }>)
+		invalidateUser(Number(r.user_id));
+}
+
+export async function listRoles(): Promise<RoleRow[]> {
+	const roles = await db.query("select * from sys_role order by name") as Array<Record<string, unknown>>;
+	const holders = await db.query("select role_name, count(*) as c from sys_user_role group by role_name") as Array<{ role_name: string, c: number }>;
+	const binds = await db.query("select role_name, permission_code from sys_role_permission order by permission_code") as Array<{ role_name: string, permission_code: string }>;
+	const holderMap = new Map(holders.map(h => [h.role_name, Number(h.c)]));
+	const bindMap = new Map<string, string[]>();
+	for (const b of binds)
+		(bindMap.get(b.role_name) ?? bindMap.set(b.role_name, []).get(b.role_name))!.push(b.permission_code);
+	return roles.map(r => ({
+		name: String(r.name),
+		module: String(r.module),
+		title: r.title == null ? null : String(r.title),
+		description: r.description == null ? null : String(r.description),
+		builtin: Number(r.builtin) === 1,
+		deprecated: Number(r.deprecated) === 1,
+		holders: holderMap.get(String(r.name)) ?? 0,
+		permissions: bindMap.get(String(r.name)) ?? [],
+	}));
+}
+
+export async function listPermissions(): Promise<PermissionRow[]> {
+	const rows = await db.query("select * from sys_permission order by code") as Array<Record<string, unknown>>;
+	return rows.map(r => ({
+		code: String(r.code),
+		module: String(r.module),
+		title_key: r.title_key == null ? null : String(r.title_key),
+		deprecated: Number(r.deprecated) === 1,
+	}));
+}
+
+export async function createRole(input: { name: string, title: string, permissions?: string[] }): Promise<{ name: string, module: string }> {
+	const name = String(input.name ?? "").trim();
+	if (!CUSTOM_NAME.test(name) || RESERVED.has(name))
+		fail(400, `role name must be custom.<slug> (reserved/framework/solution namespaces rejected): ${name}`);
+	const permissions = [...new Set((input.permissions ?? []).map(String))];
+	await assertCodesExist(permissions);
+	await db.tx(async (t) => {
+		await t.exec("insert into sys_role (name, module, title, builtin, deprecated) values (?, 'custom', ?, 0, 0)", [name, String(input.title ?? "")]);
+		for (const code of permissions)
+			await t.exec("insert into sys_role_permission (role_name, permission_code) values (?, ?)", [name, code]);
+	});
+	await recordOp({ action: "role.create", module: "framework", target: name, detail: { title: String(input.title ?? ""), permissions } });
+	return { name, module: "custom" };
+}
+
+export async function updateBindings(roleName: string, codes: string[]): Promise<void> {
+	await assertNotBuiltin(roleName);
+	const next = [...new Set(codes.map(String))];
+	await assertCodesExist(next);
+	const before = (await db.query("select permission_code from sys_role_permission where role_name = ?", [roleName])) as Array<{ permission_code: string }>;
+	const beforeSet = new Set(before.map(b => b.permission_code));
+	await db.tx(async (t) => {
+		await t.exec("delete from sys_role_permission where role_name = ?", [roleName]);
+		for (const code of next)
+			await t.exec("insert into sys_role_permission (role_name, permission_code) values (?, ?)", [roleName, code]);
+	});
+	await invalidateHolders(roleName);
+	const added = next.filter(c => !beforeSet.has(c));
+	const removed = [...beforeSet].filter(c => !next.includes(c));
+	await recordOp({ action: "role.bindings.update", module: "framework", target: roleName, detail: { added, removed } });
+}
+
+export async function deleteRole(roleName: string): Promise<void> {
+	await assertNotBuiltin(roleName);
+	const holders = await db.query("select count(*) as c from sys_user_role where role_name = ?", [roleName]);
+	const n = Number((holders[0] as { c: unknown }).c);
+	if (n > 0)
+		fail(409, `role has ${n} holder(s)`, { holders: n });
+	await db.tx(async (t) => {
+		await t.exec("delete from sys_role_permission where role_name = ?", [roleName]);
+		await t.exec("delete from sys_role where name = ?", [roleName]);
+	});
+	await invalidateHolders(roleName);
+	await recordOp({ action: "role.delete", module: "framework", target: roleName });
+}

package/templates/api/src/_platform/_shared/service/settings.ts

@@ -0,0 +1,67 @@
+// 系统设置（PRD §4.3）+ 登录方式发现（C5/D2）。
+// secret 项读取掩码（***）；market.* 安全项写操作须 superadmin 操作者（D11 边界在 service 按 actor 角色查）。
+import { recordOp } from "./audit";
+
+export interface SettingItem {
+	key: string
+	module: string
+	group: string
+	type: string
+	/** secret 项恒为 "***"（读取面掩码） */
+	value: string | null
+	default_value: string | null
+	label_key: string | null
+	options: string | null
+	secret: boolean
+	update_time: number
+}
+
+export interface SettingGroup {
+	group: string
+	items: SettingItem[]
+}
+
+/** 安全敏感组：写操作须 superadmin（D11：不建模为权限点，物理判断）。 */
+const SUPER_ONLY_GROUPS = new Set(["security"]);
+
+export async function listSettings(): Promise<SettingGroup[]> {
+	const rows = await db.query("select * from sys_setting order by \"group\", key") as Array<Record<string, unknown>>;
+	const groups = new Map<string, SettingItem[]>();
+	for (const r of rows) {
+		const item: SettingItem = {
+			key: String(r.key),
+			module: String(r.module),
+			group: String(r.group),
+			type: String(r.type),
+			value: Number(r.secret) === 1 ? "***" : (r.value == null ? null : String(r.value)),
+			default_value: r.default_value == null ? null : String(r.default_value),
+			label_key: r.label_key == null ? null : String(r.label_key),
+			options: r.options == null ? null : String(r.options),
+			secret: Number(r.secret) === 1,
+			update_time: Number(r.update_time),
+		};
+		(groups.get(item.group) ?? groups.set(item.group, []).get(item.group))!.push(item);
+	}
+	return [...groups.entries()].map(([group, items]) => ({ group, items }));
+}
+
+export async function updateSetting(actorId: number, key: string, value: string): Promise<void> {
+	const rows = await db.query("select * from sys_setting where key = ?", [key]) as Array<Record<string, unknown>>;
+	if (!rows.length)
+		throw Object.assign(new Error(`setting not found: ${key}`), { status: 404 });
+	const row = rows[0];
+	if (SUPER_ONLY_GROUPS.has(String(row.group))) {
+		const actorRoles = await db.query("select role_name from sys_user_role where user_id = ?", [actorId]) as Array<{ role_name: string }>;
+		if (!actorRoles.some(r => r.role_name === "superadmin"))
+			throw Object.assign(new Error("security settings require superadmin"), { status: 403 });
+	}
+	await db.exec("update sys_setting set value = ?, update_time = ? where key = ?", [String(value ?? ""), Date.now(), key]);
+	await recordOp({ action: "setting.update", module: String(row.module), target: key });
+}
+
+/** C5/D2：登录方式发现的数据源——local 恒在，ldap/sso 由设置项开关。 */
+export async function listLoginMethods(): Promise<{ methods: string[] }> {
+	const rows = await db.query("select key, value from sys_setting where key in ('ldap.enabled', 'sso.enabled')") as Array<{ key: string, value: string | null }>;
+	const enabled = (k: string) => rows.find(r => r.key === k)?.value === "1";
+	return { methods: ["local", ...(enabled("ldap.enabled") ? ["ldap" as const] : []), ...(enabled("sso.enabled") ? ["sso" as const] : [])] };
+}

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

@@ -0,0 +1,94 @@
+// 解决方案权限声明的升级/卸载规则出口（设计 §5「减法唯一出口 = 卸载」；AC2-1~6 / AC1-14/15）。
+// 安装器本体属 PRD M5；本出口即 M5 之前钉死规则的承载面——安装器唯一要遵守的纪律：
+// 安装 = upsertSolutionPerms（只做加法 + 元数据覆盖 + 声明消失标 deprecated），
+// 卸载 = uninstallSolution（双维度级联清理）；除此之外不得直写 sys_role/sys_permission 两表。
+// deprecated 双向过滤红线（§5）：判权链不过滤 deprecated（本文件不做任何判权过滤），
+// 管理 UI 过滤——管理面在 roles service（listPermissions 带标记，前端标灰）。
+export interface SolutionRoleDecl {
+	/** 完整角色名（含 `<module>.` 前缀，AC1-11 由安装器侧前缀校验） */
+	name: string
+	title: string
+	/** 声明绑定：insert-if-absent 写入，管理员调整永不被覆写（AC1-15） */
+	permissions?: string[]
+}
+
+export interface SolutionManifest {
+	module: string
+	roles: SolutionRoleDecl[]
+}
+
+export interface UpsertResult {
+	/** 本次被标 deprecated 的 code/name 清单——安装器据此强告警「N 个权限点需重新分配」（AC2-4） */
+	deprecated: string[]
+}
+
+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 ?? []));
+
+	for (const role of m.roles) {
+		const existing = await db.query("select name from sys_role where name = ?", [role.name]) as unknown[];
+		// upsert：行存在只覆盖元数据（title），name/builtin 不动（AC2-2 元数据覆盖）
+		if (existing.length) {
+			await db.exec("update sys_role set title = ? where name = ?", [role.title, role.name]);
+		}
+		else {
+			await db.exec("insert into sys_role (name, module, title, builtin) values (?, ?, ?, 0)", [role.name, m.module, role.title]);
+			// 声明绑定只在角色创建时写一次（角色级 insert-if-absent，AC1-15 红线）：
+			// 升级/重装对已存在角色永不补写声明绑定——管理员撤过的绑定不复活；
+			// 新版本给既有角色新增权限点时，由管理员显式勾选（insert-if-absent 的取舍边界，§9.5）。
+			for (const code of role.permissions ?? []) {
+				const bound = await db.query("select role_name from sys_role_permission where role_name = ? and permission_code = ?", [role.name, code]) as unknown[];
+				if (!bound.length)
+					await db.exec("insert into sys_role_permission (role_name, permission_code) values (?, ?)", [role.name, code]);
+			}
+		}
+	}
+
+	// 权限点行独立于角色创建：声明里的新 code 一律 upsert 插入（AC2-1「新增声明 → upsert 插入新行」——
+	// 含既有角色新增权限点的场景；绑定是否自动挂上由上面的角色级规则决定）
+	for (const code of declaredPerms) {
+		const p = await db.query("select code from sys_permission where code = ?", [code]) as unknown[];
+		if (!p.length)
+			await db.exec("insert into sys_permission (code, module) values (?, ?)", [code, m.module]);
+	}
+
+	// 声明消失 → 行保留标 deprecated（AC2-3/4）：行与绑定全留，判决不突变；
+	// 重命名的旧 code 走同一条规则（视为删除+新增），deprecated 清单交给安装器告警。
+	const oldPerms = await db.query("select code from sys_permission where module = ? and deprecated = 0", [m.module]) as Array<{ code: string }>;
+	for (const r of oldPerms) {
+		if (!declaredPerms.has(String(r.code))) {
+			await db.exec("update sys_permission set deprecated = 1 where code = ?", [r.code]);
+			deprecated.push(String(r.code));
+		}
+	}
+	const oldRoles = await db.query("select name from sys_role where module = ? and builtin = 0 and deprecated = 0", [m.module]) as Array<{ name: string }>;
+	for (const r of oldRoles) {
+		if (!declaredRoles.has(String(r.name))) {
+			await db.exec("update sys_role set deprecated = 1 where name = ?", [r.name]);
+			deprecated.push(String(r.name));
+		}
+	}
+	return { deprecated };
+}
+
+/**
+ * 卸载级联清理（AC2-6，唯一减法出口）——双维度：
+ * ① 该 module 的角色行 + 这些角色的全部绑定 + 用户成员资格；
+ * ② permission_code 属该 module 的绑定（含 custom 角色上的）+ 权限点行——
+ *   漏维度②会让 custom 角色残留绑定在重装时静默复活旧授权。custom 角色本体保留（空绑定）。
+ * AC2-7：业务表不属本出口，运维手工处理（Q4）。
+ */
+export async function uninstallSolution(module: string): Promise<void> {
+	const roles = await db.query("select name from sys_role where module = ?", [module]) as Array<{ name: string }>;
+	for (const r of roles) {
+		await db.exec("delete from sys_role_permission where role_name = ?", [r.name]);
+		await db.exec("delete from sys_user_role where role_name = ?", [r.name]);
+	}
+	await db.exec("delete from sys_role where module = ?", [module]);
+	// module 名是 slug（[a-z0-9_-]），LIKE 前缀匹配的转义纪律同 query.ts（ESCAPE '!' 三方言同义）
+	const prefix = `${module.replace(/[!%_]/g, c => `!${c}`)}.%`;
+	await db.exec("delete from sys_role_permission where permission_code like ? escape '!'", [prefix]);
+	await db.exec("delete from sys_permission where module = ?", [module]);
+}

package/templates/api/src/_platform/_shared/service/users.ts

@@ -0,0 +1,163 @@
+// 账号管理应用服务（管理域 /api/system/users，AC1-7~10 + B6 建号加固）。
+// 红线：admin 不碰 superadmin/admin 成员资格（AC1-8，service 按 actor 角色自查）；
+// 禁止操作自己（AC1-10 注）；最后 superadmin 兜底（服务端二次防线）；
+// 角色唯一权威源 sys_user_role + 写时失效（AC1-7/D10）；禁用/重置口令级联删 refresh（§3.1）。
+// bcrypt 经注入（Node 侧全局不可 stub，同 session.ts 约定）。
+import { invalidateUser } from "./access";
+import { recordOp } from "./audit";
+
+export interface UserDeps {
+	bcryptHash: (pw: string) => Promise<string>
+}
+
+export interface UserRow {
+	id: number
+	username: string
+	display_name: string | null
+	email: string | null
+	is_forbidden: boolean
+	must_change: boolean
+	roles: string[]
+}
+
+function fail(status: number, message: string): never {
+	throw Object.assign(new Error(message), { status });
+}
+
+/** 外来号命名空间抢占红线（B6）：本地建号拒收 ldap:/sso: 前缀用户名。 */
+const RESERVED_PREFIX = /^(?:ldap|sso):/i;
+
+async function rolesOf(uid: number): Promise<string[]> {
+	const rows = await db.query("select role_name from sys_user_role where user_id = ?", [uid]) as Array<{ role_name: string }>;
+	return rows.map(r => r.role_name);
+}
+
+async function usernameOf(uid: number): Promise<string> {
+	const rows = await db.query("select username from users where id = ?", [uid]) as Array<{ username: string }>;
+	return rows[0] ? String(rows[0].username) : `#${uid}`;
+}
+
+function assertNotSelf(actorId: number, targetUid: number): void {
+	if (Number(actorId) === Number(targetUid))
+		fail(400, "cannot operate on yourself");
+}
+
+/** AC1-8：成员资格（superadmin/admin 分配）仅 superadmin 可动。 */
+async function assertMembershipAllowed(actorId: number, nextRoles: string[]): Promise<void> {
+	if (!nextRoles.includes("superadmin") && !nextRoles.includes("admin"))
+		return;
+	const actorRoles = await rolesOf(Number(actorId));
+	if (!actorRoles.includes("superadmin"))
+		fail(403, "membership management requires superadmin");
+}
+
+export async function listUsers(): Promise<UserRow[]> {
+	const rows = await db.query(
+		"select id, username, display_name, email, is_forbidden, must_change from users order by username",
+	) as Array<Record<string, unknown>>;
+	const roleRows = await db.query("select user_id, role_name from sys_user_role") as Array<{ user_id: number, role_name: string }>;
+	const roleMap = new Map<number, string[]>();
+	for (const r of roleRows)
+		(roleMap.get(Number(r.user_id)) ?? roleMap.set(Number(r.user_id), []).get(Number(r.user_id)))!.push(r.role_name);
+	return rows.map(r => ({
+		id: Number(r.id),
+		username: String(r.username),
+		display_name: r.display_name == null ? null : String(r.display_name),
+		email: r.email == null ? null : String(r.email),
+		is_forbidden: Number(r.is_forbidden) === 1,
+		must_change: Number(r.must_change) === 1,
+		roles: roleMap.get(Number(r.id)) ?? [],
+	}));
+}
+
+/** B6：建号——拒外来号前缀、口令 ≥6、默认 must_change=1。返回新用户 id。 */
+export async function createUser(input: { username: string, password: string, displayName?: string, email?: string }, deps: UserDeps): Promise<number> {
+	const username = String(input.username ?? "").trim();
+	if (!username)
+		fail(400, "username required");
+	if (RESERVED_PREFIX.test(username))
+		fail(400, "username prefix reserved for external identity sources");
+	if (!input.password || String(input.password).length < 6)
+		fail(400, "password too short (min 6)");
+	const exists = await db.query("select id from users where username = ?", [username]);
+	if (exists.length)
+		fail(400, "username exists");
+	const hash = await deps.bcryptHash(String(input.password));
+	const rows = await db.query(
+		"insert into users (username, password_hash, display_name, email, must_change) values (?, ?, ?, ?, 1) returning id",
+		[username, hash, input.displayName ?? null, input.email ?? null],
+	) as Array<{ id: number }>;
+	const uid = Number(rows[0].id);
+	await recordOp({ action: "user.create", module: "framework", target: username });
+	return uid;
+}
+
+/** AC1-7：整集替换角色（sys_user_role 权威源），写后失效持有者判权缓存。 */
+export async function updateUserRoles(actorId: number, targetUid: number, roles: string[]): Promise<void> {
+	assertNotSelf(actorId, targetUid);
+	const target = await db.query("select id from users where id = ?", [targetUid]);
+	if (!target.length)
+		fail(404, "user not found");
+	const next = [...new Set(roles.map(String))];
+	if (next.length) {
+		const marks = next.map(() => "?").join(",");
+		const known = await db.query(`select name from sys_role where name in (${marks})`, next);
+		const knownSet = new Set(known.map((r: { name: string }) => r.name));
+		const unknown = next.filter(r => !knownSet.has(r));
+		if (unknown.length)
+			fail(400, `unknown roles: ${unknown.join(", ")}`);
+	}
+	await assertMembershipAllowed(actorId, next);
+	const before = await rolesOf(Number(targetUid));
+	const beforeSet = new Set(before);
+	// AC1-10 兜底：撤掉最后一个 superadmin 拒绝（现实可达路径已被「禁止操作自己」拦截）
+	if (beforeSet.has("superadmin") && !next.includes("superadmin")) {
+		const supers = await db.query("select count(*) c from sys_user_role where role_name = 'superadmin'") as Array<{ c: number }>;
+		if (Number(supers[0].c) <= 1)
+			fail(400, "cannot revoke the last superadmin");
+	}
+	await db.tx(async (t) => {
+		await t.exec("delete from sys_user_role where user_id = ?", [targetUid]);
+		for (const role of next)
+			await t.exec("insert into sys_user_role (user_id, role_name) values (?, ?)", [targetUid, role]);
+	});
+	invalidateUser(Number(targetUid));
+	await recordOp({
+		action: "user.roles.update",
+		module: "framework",
+		target: await usernameOf(Number(targetUid)),
+		detail: { added: next.filter(r => !beforeSet.has(r)), removed: [...beforeSet].filter(r => !next.includes(r)) },
+	});
+}
+
+/** B7：管理员重置口令——must_change=1 + 级联删 refresh + 写时失效。 */
+export async function changePasswordByAdmin(actorId: number, targetUid: number, newPassword: string, deps: UserDeps): Promise<void> {
+	assertNotSelf(actorId, targetUid);
+	if (!newPassword || String(newPassword).length < 6)
+		fail(400, "password too short (min 6)");
+	const rows = await db.query("select id from users where id = ?", [targetUid]);
+	if (!rows.length)
+		fail(404, "user not found");
+	const hash = await deps.bcryptHash(String(newPassword));
+	await db.tx(async (t) => {
+		await t.exec("update users set password_hash = ?, must_change = 1 where id = ?", [hash, targetUid]);
+		await t.exec("delete from sys_refresh_token where user_id = ?", [targetUid]);
+	});
+	invalidateUser(Number(targetUid));
+	await recordOp({ action: "user.password.reset", module: "framework", target: await usernameOf(Number(targetUid)) });
+}
+
+/** B7：禁用/解禁——禁用级联删 refresh + 写时失效。 */
+export async function setForbidden(actorId: number, targetUid: number, forbidden: boolean): Promise<void> {
+	assertNotSelf(actorId, targetUid);
+	const rows = await db.query("select id from users where id = ?", [targetUid]);
+	if (!rows.length)
+		fail(404, "user not found");
+	await db.tx(async (t) => {
+		await t.exec("update users set is_forbidden = ? where id = ?", [forbidden ? 1 : 0, targetUid]);
+		if (forbidden)
+			await t.exec("delete from sys_refresh_token where user_id = ?", [targetUid]);
+	});
+	invalidateUser(Number(targetUid));
+	await recordOp({ action: "user.forbidden.update", module: "framework", target: await usernameOf(Number(targetUid)), detail: { forbidden } });
+}

package/templates/api/src/_platform/contacts/api.ts

@@ -0,0 +1,22 @@
+import { respond } from "../_shared/respond";
+// 平台共享服务域 /api/_platform/contacts（D207：登录即可，不挂权限点，H12）。
+// 读操作不记审计（设计 §4B）；接口级限速（设计 line 199）经 rate.ts（B5 复用同源）。
+// 单条详情走子组 /api/_platform/contacts/detail?id=（detail/api.ts，含 email/avatar）。
+import { searchContacts } from "../_shared/service/contacts";
+import { rateLimit } from "../_shared/service/rate";
+
+export default {
+	// GET /api/_platform/contacts?keyword=&limit= —— 人员目录（AC1-22~24）。
+	async get() {
+		await respond(async () => {
+			const uid = http.user?.id;
+			if (!uid) {
+				json.fail(401, "unauthorized");
+				return;
+			}
+			await rateLimit(`contacts:${uid}`, 60, 60_000);
+			const q = http.query as Record<string, unknown>;
+			return searchContacts(q.keyword, { limit: q.limit });
+		});
+	},
+};

package/templates/api/src/_platform/contacts/detail/api.ts

@@ -0,0 +1,18 @@
+import { respond } from "../../_shared/respond";
+// GET /api/_platform/contacts/detail?id= —— 单条详情（含 email/avatar，设计 §4B）。
+import { contactDetail } from "../../_shared/service/contacts";
+import { rateLimit } from "../../_shared/service/rate";
+
+export default {
+	async get() {
+		await respond(async () => {
+			const uid = http.user?.id;
+			if (!uid) {
+				json.fail(401, "unauthorized");
+				return;
+			}
+			await rateLimit(`contacts:${uid}`, 60, 60_000);
+			return contactDetail(Number((http.query as Record<string, unknown>).id));
+		});
+	},
+};

package/templates/api/src/_platform/manifest.yaml

@@ -1,5 +1,13 @@
 name: _platform
-desc: 框架级共有表（users 鉴权）——普通模块、无路由（参考 sample/src/_platform）
+desc: 框架级共有表（users 鉴权 + RBAC 六表 + 设置/日志/路由注册）——普通模块、无路由（参考 sample/src/_platform）
 version: 0.1.0
 tables:
   - users
+  - sys_setting
+  - sys_oplog
+  - sys_solution_route
+  - sys_role
+  - sys_permission
+  - sys_role_permission
+  - sys_user_role
+  - sys_refresh_token

package/templates/api/src/_platform/migrations/0001__create_users.mysql.sql

@@ -0,0 +1,9 @@
+-- users 表 mysql 方言覆盖（方言覆盖文件必胜，通用文件兜底，oj-bin docs/migration.md §3.1；约定同 oj-wiki 先例）。
+-- 差异：AUTOINCREMENT → BIGINT AUTO_INCREMENT；username TEXT 改 VARCHAR(255)（mysql TEXT 不能带 UNIQUE）；
+-- roles TEXT 默认值写表达式 DEFAULT ('[]')（mysql ≥8.0.13 对 TEXT/BLOB 只允许表达式默认值）。
+CREATE TABLE IF NOT EXISTS users (
+  id BIGINT AUTO_INCREMENT PRIMARY KEY,
+  username VARCHAR(255) NOT NULL UNIQUE,
+  password_hash TEXT NOT NULL,
+  roles TEXT NOT NULL DEFAULT ('[]')
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

package/templates/api/src/_platform/migrations/0001__create_users.pg.sql

@@ -0,0 +1,9 @@
+-- users 表 pg 方言覆盖（方言覆盖文件必胜，oj-bin docs/migration.md §3.1；约定同 oj-wiki 先例）。
+-- 差异：AUTOINCREMENT → BIGSERIAL（GENERATED ALWAYS 系显式插值受限，SERIAL 系允许 seed 显式 id）；
+-- username TEXT UNIQUE 在 pg 合法，保留 TEXT。
+CREATE TABLE IF NOT EXISTS users (
+  id BIGSERIAL PRIMARY KEY,
+  username TEXT NOT NULL UNIQUE,
+  password_hash TEXT NOT NULL,
+  roles TEXT NOT NULL DEFAULT '[]'
+);

package/templates/api/src/_platform/migrations/0002__add_users_avatar_base64.mysql.sql

@@ -0,0 +1,3 @@
+-- users 补 avatar_base64 的 mysql 方言覆盖（oj-wiki 0002 先例逐字同型）。
+-- 差异：TEXT 列默认值必须写成表达式 DEFAULT ('')。
+ALTER TABLE users ADD COLUMN avatar_base64 TEXT NOT NULL DEFAULT ('');

package/templates/api/src/_platform/migrations/0003__users_source_display_name.mysql.sql

@@ -0,0 +1,5 @@
+-- users 扩展列 mysql 方言覆盖（oj-wiki 0005/0006 先例同型）。
+-- 差异：TEXT 默认值写表达式 DEFAULT ('local')；DROP COLUMN mysql 8 原生支持，与基线同语法。
+ALTER TABLE users ADD COLUMN source TEXT NOT NULL DEFAULT ('local');
+ALTER TABLE users ADD COLUMN display_name TEXT;
+ALTER TABLE users DROP COLUMN roles;

package/templates/api/src/_platform/migrations/0003__users_source_display_name.sql

@@ -0,0 +1,5 @@
+-- RBAC 地基：users 扩展列 + 移除 roles JSON 列（D10：sys_user_role 表为唯一权威源）
+-- sqlite 方言（ALTER TABLE DROP COLUMN 需 sqlite ≥ 3.35，Node 22 内建满足）
+ALTER TABLE users ADD COLUMN source TEXT NOT NULL DEFAULT 'local';
+ALTER TABLE users ADD COLUMN display_name TEXT;
+ALTER TABLE users DROP COLUMN roles;

package/templates/api/src/_platform/migrations/0004__sys_rbac.mysql.sql

@@ -0,0 +1,70 @@
+-- 框架 RBAC 六表 mysql 方言覆盖（sqlite 版见 0004__sys_rbac.sql；oj-wiki 先例同型）。
+-- 差异：保留字反引号（mysql 默认 sql_mode 下双引号是字符串字面量）；
+-- AUTO_INCREMENT 替 AUTOINCREMENT，id 取 BIGINT（与 users 同宽度口径）；
+-- 主键/默认值 TEXT → VARCHAR(255) / 表达式默认值（mysql TEXT 不能作主键、不能直接带默认值）。
+CREATE TABLE IF NOT EXISTS sys_setting (
+  `key` VARCHAR(255) PRIMARY KEY,
+  module TEXT NOT NULL,
+  `group` TEXT NOT NULL,
+  type TEXT NOT NULL DEFAULT ('string'),
+  value TEXT,
+  default_value TEXT,
+  label_key TEXT,
+  options TEXT,
+  secret BIGINT NOT NULL DEFAULT 0,
+  update_time BIGINT NOT NULL DEFAULT 0
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE IF NOT EXISTS sys_oplog (
+  id BIGINT AUTO_INCREMENT PRIMARY KEY,
+  create_time BIGINT NOT NULL,
+  user_id BIGINT NOT NULL DEFAULT 0,
+  username TEXT NOT NULL DEFAULT ('system'),
+  action TEXT NOT NULL,
+  module TEXT NOT NULL DEFAULT ('framework'),
+  version TEXT,
+  target TEXT,
+  detail TEXT,
+  level BIGINT NOT NULL DEFAULT 6
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+-- mysql 无 CREATE INDEX IF NOT EXISTS；迁移账本保证一次应用（oj-bin docs/migration.md 语义）
+CREATE INDEX idx_sys_oplog_time ON sys_oplog (create_time, id);
+
+CREATE TABLE IF NOT EXISTS sys_solution_route (
+  name VARCHAR(255) NOT NULL,
+  version VARCHAR(255) NOT NULL,
+  category TEXT NOT NULL,
+  path VARCHAR(255) NOT NULL,
+  `order` BIGINT NOT NULL DEFAULT 0,
+  title_key TEXT,
+  enabled BIGINT NOT NULL DEFAULT 1,
+  PRIMARY KEY (name, version, path)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE IF NOT EXISTS sys_role (
+  name VARCHAR(255) PRIMARY KEY,
+  module TEXT NOT NULL,
+  title TEXT,
+  description TEXT,
+  builtin BIGINT NOT NULL DEFAULT 0,
+  deprecated BIGINT NOT NULL DEFAULT 0
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE IF NOT EXISTS sys_permission (
+  code VARCHAR(255) PRIMARY KEY,
+  module TEXT NOT NULL,
+  title_key TEXT,
+  deprecated BIGINT NOT NULL DEFAULT 0
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE IF NOT EXISTS sys_role_permission (
+  role_name VARCHAR(255) NOT NULL,
+  permission_code VARCHAR(255) NOT NULL,
+  PRIMARY KEY (role_name, permission_code)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE IF NOT EXISTS sys_user_role (
+  user_id BIGINT NOT NULL,
+  role_name VARCHAR(255) NOT NULL,
+  PRIMARY KEY (user_id, role_name)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;