@oj-module/cli 0.1.20 → 0.2.1

package/shell-dist/index.html

@@ -5,9 +5,9 @@
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<link rel="icon" href="/favicon.ico" />
 		<title>React Antd Admin · Shell</title>
-		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-aMxR7a5yEi7eE8DlhFuiNg=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
+		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-mWZBL1v96uMHEClxtdmRpA=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
 
-		<script type="importmap" nonce="aMxR7a5yEi7eE8DlhFuiNg==">{
+		<script type="importmap" nonce="mWZBL1v96uMHEClxtdmRpA==">{
   "imports": {
     "react": "/assets/react.js",
     "react/jsx-runtime": "/assets/jsx-runtime.js",
@@ -133,7 +133,7 @@
     "dayjs/locale/zh-cn": "/assets/ojm-dayjs-locale-zh-cn.js"
   }
 }</script>
-		<script type="module" crossorigin src="/assets/index-BUyoDvUl.js"></script>
+		<script type="module" crossorigin src="/assets/index-CLdhl3Qd.js"></script>
 	</head>
 	<body>
 		<div id="root"></div>

package/shell-dist/versions.json

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

package/src/build.ts

@@ -60,6 +60,31 @@ export const fetchMenuList = _fn;
 export const fetchAddMenuItem = _fn;
 export const fetchUpdateMenuItem = _fn;
 export const fetchDeleteMenuItem = _fn;
+// RBAC（阶段 C 增补，与 runtime api/rbac 对齐）
+export const fetchRbacRoleList = _fn;
+export const fetchRbacPermissionList = _fn;
+export const fetchRbacCreateRole = _fn;
+export const fetchRbacUpdateBindings = _fn;
+export const fetchRbacDeleteRole = _fn;
+export const fetchRbacUserList = _fn;
+export const fetchRbacCreateUser = _fn;
+export const fetchRbacUpdateUserRoles = _fn;
+export const fetchRbacAdminResetPassword = _fn;
+export const fetchRbacSetForbidden = _fn;
+export const fetchRbacOplog = _fn;
+export const fetchRbacSettings = _fn;
+export const fetchRbacUpdateSetting = _fn;
+export const fetchRbacContacts = _fn;
+export const fetchRbacContactDetail = _fn;
+export const fetchLoginMethods = _fn;
+export const fetchChangePassword = _fn;
+export const fetchLdapLogin = _fn;
+export const roleLabel = _fn;
+export const canEditRoleBindings = _fn;
+export const canDeleteRole = _fn;
+export const canAssignRole = _fn;
+export const bindingDiff = _fn;
+export const groupByModule = _fn;
 // hooks 与权限常量
 export const useAccess = _fn;
 export const usePreferences = _fn;
@@ -74,6 +99,8 @@ export const permissionPrefix = "permission:button";
 export const useAuthStore = _fn;
 export const useUserStore = _fn;
 export const useTabsStore = _fn;
+// 页签 key 唯一正确取口（keepAlive 下 useLocation 是激活页位置，0.1.21）
+export const useTabKey = _fn;
 // 图标
 export const menuIcons = _obj;
 export const EmbeddedIcon = _fn;

package/src/init.ts

@@ -328,8 +328,11 @@ function generatePackageJson(cliRoot: string, projectName: string) {
 		"@ant-design/icons": pin("@ant-design/icons"),
 		// personal-center 的 ProForm 用到——仅取**类型**（运行时由宿主 importmap 提供单例）
 		"@ant-design/pro-components": pin("@ant-design/pro-components"),
+		// system 模块页面数据层 + i18n 类型（TFunction）用到——仅取**类型**（运行时由宿主提供单例）
+		"@tanstack/react-query": pin("@tanstack/react-query"),
 		"@types/react": pin("@types/react"),
 		"antd": pin("antd"),
+		"i18next": pin("i18next"),
 		// home 首页图表演示用到——仅取**类型**（运行时由宿主 importmap 提供单例）
 		"dayjs": pin("dayjs"),
 		"echarts": pin("echarts"),

package/templates/README.md

@@ -13,6 +13,21 @@ pnpm preview    # 预览：oj migrate + server（release 产物）
 
 登录账号：`admin` / `123456`（见 `api/src/_platform/seed.sql`）。
 
+## 系统管理模块
+
+`web/src/system/`（用户管理 / 成员资格 / 角色权限 / 操作日志 / 站点设置 / 登录方式）
+的前端 API 客户端 `__client/` 是生成物、不随模板分发，**首次使用前生成一次**：
+
+```bash
+pnpm dev                              # 终端 A：起 oj 后端 + 前端
+bin/oj openapi -c config.yaml -d api/src -b /api -o openapi.json   # 终端 B：产出契约
+pnpm exec ojm api                     # 生成 web/src/*/__client（dev 检测到 openapi.json 变化也会自动重生成）
+```
+
+生成后重启 `pnpm dev`，「系统管理」菜单即可用（生成前该模块加载失败属预期）。
+改了 `api/src` 的 handler `.schema`/`.response` 后同样重跑这两条保持同步
+（`ojm api --check` 可对账，零漂移为发布门禁）。成员资格页仅 superadmin 可见。
+
 ## 目录
 
 ```

package/templates/api/config.yaml

@@ -42,11 +42,25 @@ server:
     credentials: false
 db:
   default: 'sqlite://db.sqlite' # 相对 config 目录；缺文件自动建空库
+
+# ---- LDAP 连接段（D1/PRD §4.5 两段式之连接段；oj 插件严格解析本段，未知键启动 fail-fast——只写下列键）----
+# 取消注释并填值即接通目录服务；应用映射段在 DB/设置页（ldap.enabled、ldap_base_dn、
+# ldap_uid_attr、ldap_email_attr，group=ldap，即时生效）。本段改动属 restart_pending，需重启。
+# ldap:
+#  url: "ldap://127.0.0.1:389"
+#  bind_dn: ""
+#  bind_pw: ""
+#  timeout_ms: 3000
+#  start_tls: false
+#  tls_skip_verify: false
 auth:
   jwt_secret: __JWT_SECRET__ # init 随机生成；生产必须更换
   access_token_duration: 2h
   refresh_token_duration: 720h
   anonymous_paths: # auth 端点是业务路由，必须显式匿名（漏列则握手 401，见 ojm 开发手册 §8）
     - /auth/login
+    - /auth/ldap-login # D1/AC1-12：LDAP 目录登录（匿名）
     - /auth/refresh
     - /auth/logout
+    # 登录页登录方式 Tabs 数据源（C5/AC2-2）：未登录即可读
+    - /system/login-methods

package/templates/api/seed.mysql.sql

@@ -0,0 +1,5 @@
+-- 系统设置默认值（PRD §4.3；注释内禁英文分号）
+INSERT IGNORE INTO sys_setting (key, module, `group`, type, value, default_value, label_key, secret, update_time) VALUES ('framework.site_title', 'framework', 'general', 'string', 'React Antd Admin', 'React Antd Admin', 'system:setting.site_title', 0, 0);
+INSERT IGNORE INTO sys_setting (key, module, `group`, type, value, default_value, label_key, secret, update_time) VALUES ('market.cdn_url', 'market', 'security', 'string', '', '', 'system:setting.market_cdn_url', 0, 0);
+INSERT IGNORE INTO sys_setting (key, module, `group`, type, value, default_value, label_key, secret, update_time) VALUES ('ldap.enabled', 'ldap', 'login', 'bool', '0', '0', 'system:setting.ldap_enabled', 0, 0);
+INSERT IGNORE INTO sys_setting (key, module, `group`, type, value, default_value, label_key, secret, update_time) VALUES ('sso.enabled', 'sso', 'login', 'bool', '0', '0', 'system:setting.sso_enabled', 0, 0);

package/templates/api/seed.pg.sql

@@ -0,0 +1,5 @@
+-- 系统设置默认值（PRD §4.3；注释内禁英文分号）
+INSERT INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('framework.site_title', 'framework', 'general', 'string', 'React Antd Admin', 'React Antd Admin', 'system:setting.site_title', 0, 0) ON CONFLICT DO NOTHING;
+INSERT INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('market.cdn_url', 'market', 'security', 'string', '', '', 'system:setting.market_cdn_url', 0, 0) ON CONFLICT DO NOTHING;
+INSERT INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('ldap.enabled', 'ldap', 'login', 'bool', '0', '0', 'system:setting.ldap_enabled', 0, 0) ON CONFLICT DO NOTHING;
+INSERT INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('sso.enabled', 'sso', 'login', 'bool', '0', '0', 'system:setting.sso_enabled', 0, 0) ON CONFLICT DO NOTHING;

package/templates/api/src/_platform/_shared/respond.ts

@@ -0,0 +1,18 @@
+// 统一异常出口（handler 层编排约定）：
+// service / 守卫层抛 Error & { status?, ...extra }（见 service/roles.ts fail()），
+// 但 oj 运行时对未捕获异常一律落 500 信封（不读 err.status）——
+// 所有 handler 的业务体必须经 respond 收口成 json.fail(status, msg, extra)，
+// 否则 D14 统一 401 / B5 429 retryAfterMs / 403 must_change / 409 holders 全被抹成 500。
+export async function respond<T>(fn: () => Promise<T>): Promise<void> {
+	try {
+		json.ok(await fn());
+	}
+	catch (e) {
+		const err = e as Error & { status?: number } & Record<string, unknown>;
+		const data = Object.fromEntries(Object.entries(err).filter(([k]) => k !== "status" && k !== "message"));
+		if (Object.keys(data).length > 0)
+			json.fail(err.status ?? 500, err.message, data);
+		else
+			json.fail(err.status ?? 500, err.message);
+	}
+}

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

@@ -0,0 +1,99 @@
+// 判权应用出口（D10）：DB 权威源 + 短 TTL 缓存 + 写时失效 = 撤销即强退。
+// 领域决策在 guard.ts（decideAccess 纯函数，AC1-1~6 矩阵）；本层只做 IO：加载/缓存/失效/抛错。
+// 错误约定：拒权抛 Error & { status: 403 }（应用 handler 层映射 json.fail，与 oj-wiki 先例一致）。
+// 反常识注记：oj 每请求重建模块实例，本缓存恒不命中（每请求直查 DB）——正确性无损
+// （撤销即强退反而成为平凡真），缓存/写时失效仅在同请求多断言时有意义；保留以兼容调用面。
+import { decideAccess } from "./guard";
+
+/** 短 TTL 仅兜底（进程崩溃/漏失效），正常撤销走写时 invalidateUser（设计文档 D10）。 */
+const TTL_MS = 10_000;
+
+interface AccessSnapshot {
+	roles: string[]
+	bindings: Record<string, string[]>
+	forbidden: boolean
+	/** 首登/重置口令后的强制改密悬挂（D12/AC1-27）：悬挂期判权出口全拒（改密端点不经过本层） */
+	mustChange: boolean
+	at: number
+}
+
+const cache = new Map<number, AccessSnapshot>();
+
+async function loadSnapshot(userId: number): Promise<AccessSnapshot> {
+	const userRows = await db.query("select is_forbidden, must_change from users where id = ?", [userId]);
+	const roleRows = await db.query("select role_name from sys_user_role where user_id = ?", [userId]);
+	const roles = roleRows.map((r: { role_name: string }) => r.role_name);
+	// 只捞该用户角色的绑定（参数化 IN，三方言纪律）；deprecated 不过滤（判权职责，§5）
+	const bindRows = roles.length
+		? await db.query(
+			`select role_name, permission_code from sys_role_permission where role_name in (${roles.map(() => "?").join(",")})`,
+			roles,
+		)
+		: [];
+	const bindings: Record<string, string[]> = {};
+	for (const r of bindRows as { role_name: string, permission_code: string }[])
+		(bindings[r.role_name] ??= []).push(r.permission_code);
+	return {
+		roles,
+		bindings,
+		forbidden: Number((userRows[0] || {}).is_forbidden) === 1,
+		mustChange: Number((userRows[0] || {}).must_change) === 1,
+		at: Date.now(),
+	};
+}
+
+async function snapshot(userId: number): Promise<AccessSnapshot> {
+	const hit = cache.get(userId);
+	if (hit && Date.now() - hit.at < TTL_MS)
+		return hit;
+	const snap = await loadSnapshot(userId);
+	cache.set(userId, snap);
+	return snap;
+}
+
+/** 写路径（角色分配/绑定调整/紧急吊销/禁用）同步调用：撤销下一次请求即生效。 */
+export function invalidateUser(userId: number): void {
+	cache.delete(userId);
+}
+
+export function invalidateAllUsers(): void {
+	cache.clear();
+}
+
+function deny(): never {
+	throw Object.assign(new Error("forbidden"), { status: 403 });
+}
+
+/** 当前请求的访问快照；未认证/禁用/改密悬挂即拒（403 不泄露账号存在性）。 */
+async function currentAccess(): Promise<AccessSnapshot> {
+	const uid = http.user?.id;
+	if (uid == null)
+		deny();
+	const snap = await snapshot(uid);
+	if (snap.forbidden)
+		deny();
+	if (snap.mustChange)
+		throw Object.assign(new Error("password change required"), { status: 403, code: "must_change" });
+	return snap;
+}
+
+/** 四级链判权（AC1-1~6）。code 首段由 guard.moduleOf 在 JS 侧切（防三方言字符串函数分叉）。 */
+export async function assertPermission(code: string): Promise<void> {
+	const { roles, bindings } = await currentAccess();
+	if (!decideAccess({ roles, bindings }, code))
+		deny();
+}
+
+/** 系统管理员及以上（superadmin 或 admin）。 */
+export async function assertSystemAdmin(): Promise<void> {
+	const { roles } = await currentAccess();
+	if (!roles.includes("superadmin") && !roles.includes("admin"))
+		deny();
+}
+
+/** 仅超级管理员：成员资格管理/卸载/市场安全设置/审计导出等安全敏感项（D11，这些项不落权限点表）。 */
+export async function assertSuperAdmin(): Promise<void> {
+	const { roles } = await currentAccess();
+	if (!roles.includes("superadmin"))
+		deny();
+}

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

@@ -0,0 +1,90 @@
+// 审计出口（AC1-29）：recordOp 落 sys_oplog；auditOp fire-and-forget（失败静默，不阻断业务）；
+// auditDeny 按 (user_id, code) 分钟窗口聚合——首条落表，窗口内只更新计数，1000 次循环不逐条落表。
+// 反常识修正：oj 每请求重建模块实例，聚合窗口状态以 sys_oplog 自身为锚（分钟内最近一条同 (user,code)
+// 的 auth.deny 行），进程内 Map 方案在真实运行时每请求恒为空、恒逐条落表（语义破坏已实测）。
+// 脱敏红线：detail 由调用方保证不含口令/密钥/token（本层只做 JSON 序列化）。
+import { moduleOf } from "./guard";
+
+export interface OpEntry {
+	/** 动作标识，点分：`role.create` / `user.roles.update`（C 区页面筛选项） */
+	action: string
+	/** 归属模块（sys_oplog.module；聚合/筛选用） */
+	module: string
+	version?: string
+	/** 操作对象标识（角色名/用户名/方案名），可空 */
+	target?: string
+	/** 结构化明细；本层 JSON 序列化。脱敏红线：不得含口令/密钥/token */
+	detail?: unknown
+	/** syslog 级，默认 6(info)；403 拒绝为 4(warning) */
+	level?: number
+}
+
+async function usernameOf(userId: number): Promise<string> {
+	if (!userId)
+		return "system";
+	const rows = await db.query("select username from users where id = ?", [userId]);
+	return rows[0] ? String(rows[0].username) : "unknown";
+}
+
+/** 同步落表。关键路径（如 A6 角色管理）直接 await；一般路径用 auditOp。 */
+export async function recordOp(entry: OpEntry): Promise<void> {
+	const uid = http.user?.id ?? 0;
+	await db.exec(
+		"insert into sys_oplog (create_time, user_id, username, action, module, version, target, detail, level) values (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+		[
+			Date.now(),
+			uid,
+			await usernameOf(uid),
+			entry.action,
+			entry.module,
+			entry.version ?? null,
+			entry.target ?? null,
+			entry.detail == null ? null : JSON.stringify(entry.detail),
+			entry.level ?? 6,
+		],
+	);
+}
+
+/** fire-and-forget：审计失败静默（写日志也失败的极端场景下，业务正确性优先）。 */
+export function auditOp(entry: OpEntry): void {
+	recordOp(entry).catch(() => {});
+}
+
+const DENY_WINDOW_MS = 60_000;
+// 串行队列：把同请求内多次 auditDeny 的「查锚点行→更新/插入」串行化（AC1-29 同窗口只许一行首条）。
+// 跨请求并发首条可能落两行（锚点查询非原子）——人去重后并发 403 同 (user,code) 极罕见，可容忍。
+// ponytail: 模块级队列在 oj 每请求重建语义下只管得住单请求内，跨请求靠 DB 行自身作锚。
+let denyQueue: Promise<void> = Promise.resolve();
+
+/**
+ * 403 失败审计入口（判权出口调用）：(user_id, code) 分钟窗口聚合，首条 + 计数。
+ *  uid 在调用瞬间同步捕获——http.user 是可变全局，异步队列执行时再读会被后续请求覆盖。
+ */
+export function auditDeny(code: string): void {
+	const uid = http.user?.id ?? 0;
+	denyQueue = denyQueue.then(() => recordDeny(uid, code)).catch(() => {});
+}
+
+/** 清窗口状态：窗口锚点即 sys_oplog 行本身——测试夹具/运维直接清表即重置，本函数仅为兼容既有调用面。 */
+export function resetDenyAudit(): void {
+	// no-op（状态在 DB；详见文件头反常识修正）
+}
+
+async function recordDeny(uid: number, code: string): Promise<void> {
+	const now = Date.now();
+	// 窗口锚点 = 分钟内最近一条同 (user, code) 的 auth.deny 行；命中只更新计数，否则落首条。
+	const rows = await db.query(
+		"select id, detail from sys_oplog where user_id = ? and action = 'auth.deny' and target = ? and create_time > ? order by id desc limit 1",
+		[uid, code, now - DENY_WINDOW_MS],
+	);
+	const hit = rows[0] as { id: number, detail: string } | undefined;
+	if (hit) {
+		const count = (JSON.parse(hit.detail) as { count: number }).count + 1;
+		await db.exec("update sys_oplog set detail = ? where id = ?", [JSON.stringify({ code, count }), hit.id]);
+		return;
+	}
+	await db.exec(
+		"insert into sys_oplog (create_time, user_id, username, action, module, target, detail, level) values (?, ?, ?, 'auth.deny', ?, ?, ?, 4)",
+		[now, uid, await usernameOf(uid), moduleOf(code), code, JSON.stringify({ code, count: 1 })],
+	);
+}

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

@@ -0,0 +1,36 @@
+// 通讯录读模型（D9：users 即通讯录；AC1-22~25）。
+// 目录红线：只出 id/username/display_name——不含 email/avatar/roles（防低权账号拖走全员邮箱喂钓鱼，安全评审 P2）；
+// 详情端点才给 email/avatar。默认排除 is_forbidden=1（AC1-23：管理域仍可见，目录与管理分离）。
+// keyword≥2、LIKE 转义复用 query.ts；solutions 同 isolate import searchContacts 直调，无 HTTP 往返（AC1-25）。
+import { likePattern } from "./query";
+
+export interface ContactRow {
+	id: number
+	username: string
+	display_name: string | null
+}
+
+const DEFAULT_LIMIT = 200;
+const MAX_LIMIT = 200;
+
+export async function searchContacts(keyword: unknown, opts: { limit?: unknown } = {}): Promise<ContactRow[]> {
+	const pattern = likePattern(keyword); // <2 字符在此抛 400（AC1-22）
+	const rawLimit = Number.parseInt(String(opts.limit ?? ""), 10);
+	const limit = Number.isFinite(rawLimit) && rawLimit >= 1 ? Math.min(MAX_LIMIT, rawLimit) : DEFAULT_LIMIT;
+	return await db.query(
+		`select id, username, display_name from users
+		 where is_forbidden = 0 and (username like ? escape '!' or display_name like ? escape '!')
+		 order by username limit ?`,
+		[pattern, pattern, limit],
+	) as ContactRow[];
+}
+
+export async function contactDetail(id: number): Promise<Record<string, unknown>> {
+	const rows = await db.query(
+		"select id, username, display_name, email, avatar_base64 from users where id = ? and is_forbidden = 0",
+		[id],
+	);
+	if (!rows[0])
+		throw Object.assign(new Error("contact not found"), { status: 404 });
+	return rows[0] as Record<string, unknown>;
+}

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

@@ -0,0 +1,30 @@
+// 判权领域核心（DDD 领域服务）：四级链的纯函数决策——IO（DB 加载/缓存失效）在应用层
+// （阶段 A3），本层不感知，天然可测。decideAccess 的输入即 AC1-1~6 的判定矩阵。
+//
+// 通过条件任一命中：
+//   1. 持 superadmin        → 通过一切 code
+//   2. 持 admin             → 通过一切 code
+//   3. 持 <code 首段>.admin → 通过该模块全部 code（零配置推导）
+//   4. 持角色的绑定精确命中 code（含 deprecated——判权不过滤，设计文档 §5）
+
+/** code 首段 = 模块名（推导锚定 manifest.name 而非 api.prefix，设计文档 §4A.1 细则 1）。 */
+export function moduleOf(code: string): string {
+	const i = code.indexOf(".");
+	return i === -1 ? code : code.slice(0, i);
+}
+
+export interface AccessInput {
+	/** 用户持有角色（sys_user_role 权威源的投影） */
+	roles: string[]
+	/** 角色 → 已绑定权限点（sys_role_permission 投影；deprecated 不过滤） */
+	bindings: Record<string, string[]>
+}
+
+export function decideAccess(input: AccessInput, code: string): boolean {
+	const { roles, bindings } = input;
+	if (roles.includes("superadmin") || roles.includes("admin"))
+		return true;
+	if (roles.includes(`${moduleOf(code)}.admin`))
+		return true;
+	return roles.some(r => (bindings[r] ?? []).includes(code));
+}

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

@@ -0,0 +1,47 @@
+// 操作日志查询（AC1-29/D13：admin 可查；读操作不记审计的红线不适用——本表本身就是审计）。
+// 过滤维度：action 精确 / username 前缀 / module 精确；分页复用 query.ts（limit 钳 200/truncated）。
+import { likePattern, paged } from "./query";
+
+export interface OplogRow {
+	id: number
+	create_time: number
+	user_id: number
+	username: string
+	action: string
+	module: string
+	version: string | null
+	target: string | null
+	detail: string | null
+	level: number
+}
+
+export interface OplogPage {
+	list: OplogRow[]
+	total: number
+	truncated: boolean
+}
+
+export async function searchOplog(filter: { action?: unknown, username?: unknown, module?: unknown, limit?: unknown }): Promise<OplogPage> {
+	const conds: string[] = [];
+	const params: unknown[] = [];
+	if (filter.action) {
+		conds.push("action = ?");
+		params.push(String(filter.action));
+	}
+	if (filter.module) {
+		conds.push("module = ?");
+		params.push(String(filter.module));
+	}
+	if (filter.username) {
+		conds.push("username like ? escape '!'");
+		params.push(likePattern(filter.username));
+	}
+	const where = conds.length ? `where ${conds.join(" and ")}` : "";
+	const r = await paged<OplogRow>(
+		`select * from sys_oplog ${where} order by id desc`,
+		`select count(*) as c from sys_oplog ${where}`,
+		params,
+		{ size: filter.limit },
+	);
+	return { list: r.list, total: r.total, truncated: r.truncated };
+}

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

@@ -0,0 +1,53 @@
+// 查询工具（DRY 收敛，AC1-22/24）：全部列表接口复用——
+// paged：limit 钳 200（静默）、truncated 标记（offset+list.length < total）、count+list 双查询；
+// likePattern：keyword 长度红线（默认 2~64，越界 400）、LIKE 元字符转义（ESCAPE '!' 三方言同语义）。
+// 错误约定与判权出口一致：Error & { status }。
+
+export interface PageResult<T> {
+	list: T[]
+	total: number
+	page: number
+	size: number
+	/** 还有未返回数据（AC1-24：多取一条判截断） */
+	truncated: boolean
+}
+
+const MAX_SIZE = 200;
+const DEFAULT_SIZE = 20;
+
+function pageArgs(input: { page?: unknown, size?: unknown }): { page: number, size: number, offset: number } {
+	const rawPage = Number.parseInt(String(input.page ?? ""), 10);
+	const rawSize = Number.parseInt(String(input.size ?? ""), 10);
+	const page = Number.isFinite(rawPage) && rawPage >= 1 ? rawPage : 1;
+	// 非法/<1 回落默认 20，再钳上限 200（AC1-24 静默钳制）
+	const size = Math.min(MAX_SIZE, Number.isFinite(rawSize) && rawSize >= 1 ? rawSize : DEFAULT_SIZE);
+	return { page, size, offset: (page - 1) * size };
+}
+
+/** 双查询分页：listSql/countSql 共用 params（调用方同一 WHERE），limit/offset 参数化（三方言安全）。 */
+export async function paged<T>(
+	listSql: string,
+	countSql: string,
+	params: unknown[],
+	input: { page?: unknown, size?: unknown },
+): Promise<PageResult<T>> {
+	const { page, size, offset } = pageArgs(input);
+	const total = Number((await db.query(countSql, params) as Array<Record<string, unknown>>)[0]?.c ?? 0);
+	const list = await db.query(`${listSql} limit ? offset ?`, [...params, size, offset]) as T[];
+	return { list, total, page, size, truncated: offset + list.length < total };
+}
+
+/**
+ * LIKE 模式：修剪后校验长度（默认 2~64），元字符 % _ ! 加 ! 转义，两侧包 %。
+ *  SQL 侧必须写 `like ? escape '!'`（三方言同语义；sqlite 默认无转义符，mysql/pg 默认不是 !）。
+ */
+export function likePattern(keyword: unknown, opts: { minLen?: number, maxLen?: number } = {}): string {
+	const kw = String(keyword ?? "").trim();
+	const min = opts.minLen ?? 2;
+	const max = opts.maxLen ?? 64;
+	if (kw.length < min)
+		throw Object.assign(new Error(`keyword too short (min ${min})`), { status: 400 });
+	if (kw.length > max)
+		throw Object.assign(new Error(`keyword too long (max ${max})`), { status: 400 });
+	return `%${kw.replace(/[!%_]/g, m => `!${m}`)}%`;
+}

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

@@ -0,0 +1,79 @@
+// 限速出口（B5/AC1-26 + 接口级限速）。反常识修正：oj 运行时每请求重建模块实例，
+// 进程内 Map 不跨请求存活（实测模块级计数器恒为初值）——状态全部落库：
+// sys_rate_window（滑动窗口计数）/ sys_login_throttle（连败 + 指数 backoff）。
+// 落库后重启保留、多实例天然同源（原先「多实例换 Redis」的已知上限就此消除）。
+// ponytail: SELECT→DELETE+INSERT/UPDATE 两步写，高并发下窗口计数可能丢几拍——限速场景可容忍。
+
+export interface RateLimitOpts {
+	/** 时钟注入（测试用）；缺省 Date.now() */
+	now?: () => number
+}
+
+/** key 维度（如 `contacts:<uid>` / `login:ip:<ip>`）：窗口内超 limit → 429。 */
+export async function rateLimit(key: string, limit: number, windowMs: number, opts: RateLimitOpts = {}): Promise<void> {
+	const now = opts.now?.() ?? Date.now();
+	const rows = await db.query("select window_start, count from sys_rate_window where rate_key = ?", [key]);
+	const w = rows[0] as { window_start: number, count: number } | undefined;
+	if (!w || now - Number(w.window_start) >= windowMs) {
+		await db.exec("delete from sys_rate_window where rate_key = ?", [key]);
+		await db.exec("insert into sys_rate_window (rate_key, window_start, count) values (?, ?, 1)", [key, now]);
+		return;
+	}
+	const count = Number(w.count) + 1;
+	await db.exec("update sys_rate_window set count = ? where rate_key = ?", [count, key]);
+	if (count > limit)
+		throw Object.assign(new Error("rate limited"), { status: 429 });
+}
+
+// ---- 登录限速（AC1-26）：(IP, username) 连败阈值 → 429 + 指数 backoff（状态在 sys_login_throttle）----
+
+export interface LoginThrottleOpts extends RateLimitOpts {
+	/** 连败阈值（默认 6，AC1-26） */
+	threshold?: number
+	/** 基础 backoff（默认 15s）；第 n 次超阈失败阻断 base × 2^(n - threshold) */
+	baseBackoffMs?: number
+}
+
+interface LoginThrottleRow {
+	fail_count: number
+	blocked_until: number
+}
+
+/** 登录失败计数 +1；达到阈值即按指数 backoff 设阻断窗口。返回累计连败数。 */
+export async function loginFailed(key: string, opts: LoginThrottleOpts = {}): Promise<number> {
+	const threshold = opts.threshold ?? 6;
+	const base = opts.baseBackoffMs ?? 15_000;
+	const now = opts.now?.() ?? Date.now();
+	const rows = await db.query("select fail_count, blocked_until from sys_login_throttle where pair_key = ?", [key]);
+	const s = rows[0] as LoginThrottleRow | undefined;
+	const count = (s ? Number(s.fail_count) : 0) + 1;
+	const blockedUntil = count >= threshold ? now + base * 2 ** (count - threshold) : (s ? Number(s.blocked_until) : 0);
+	await db.exec("delete from sys_login_throttle where pair_key = ?", [key]);
+	await db.exec("insert into sys_login_throttle (pair_key, fail_count, blocked_until) values (?, ?, ?)", [key, count, blockedUntil]);
+	return count;
+}
+
+/** 登录前检查：阻断期内抛 429；且每次尝试都累加失败并指数延长（防阻断期无脑重试）。 */
+export async function loginBlocked(key: string, opts: LoginThrottleOpts = {}): Promise<void> {
+	const threshold = opts.threshold ?? 6;
+	const base = opts.baseBackoffMs ?? 15_000;
+	const now = opts.now?.() ?? Date.now();
+	const rows = await db.query("select fail_count, blocked_until from sys_login_throttle where pair_key = ?", [key]);
+	const s = rows[0] as LoginThrottleRow | undefined;
+	if (!s || Number(s.blocked_until) <= now)
+		return;
+	const count = Number(s.fail_count) + 1;
+	const blockedUntil = now + base * 2 ** (count - threshold);
+	await db.exec("update sys_login_throttle set fail_count = ?, blocked_until = ? where pair_key = ?", [count, blockedUntil, key]);
+	throw Object.assign(new Error("too many login attempts"), { status: 429, retryAfterMs: blockedUntil - now });
+}
+
+/** 登录成功清零连败。 */
+export async function loginSucceeded(key: string): Promise<void> {
+	await db.exec("delete from sys_login_throttle where pair_key = ?", [key]);
+}
+
+/** 清登录限速状态（测试夹具/运维排障用）。 */
+export async function resetLoginThrottle(): Promise<void> {
+	await db.exec("delete from sys_login_throttle", []);
+}