@oj-module/cli 0.2.8 → 0.2.14

package/src/versions.ts

@@ -100,9 +100,37 @@ export function validateSharedVersions(
 	return errors;
 }
 
+/**
+ * 源码形态守卫（R5 prepack 断言的本地版）：cli 源码树内 shell-dist 与
+ * packages/runtime 同源于一次宿主构建，升 runtime 后忘跑 build:shell 会让
+ * versions.json 停在旧版本，门禁误报「请对齐版本后重新安装」。此处先对比
+ * 两者版本，过期直接报真因。发布形态（pack 后）无同级 runtime 目录，跳过。
+ */
+export function hostArtifactFreshnessError(
+	hostRuntime: string | undefined,
+	workspaceRuntime: string | undefined,
+): string | undefined {
+	if (!hostRuntime || !workspaceRuntime || hostRuntime === workspaceRuntime)
+		return undefined;
+	return `内置宿主产物（shell-dist/versions.json）过期：其中 runtime 版本（${hostRuntime}）≠ 本仓 packages/runtime 版本（${workspaceRuntime}）。
+这是升 runtime 后未重建宿主导致的漂移，请执行：pnpm --filter @oj-module/cli build:shell`;
+}
+
 /** 校验模块工程的共享依赖版本矩阵，违规直接抛错并打印期望值 */
 export function checkSharedVersions(projectRoot: string, shellDist: string): void {
 	const versions = readHostVersions(shellDist);
+
+	let workspaceRuntime: string | undefined;
+	try {
+		workspaceRuntime = JSON.parse(fs.readFileSync(path.join(CLI_ROOT, "..", "runtime", "package.json"), "utf-8")).version;
+	}
+	catch {
+		/* 发布形态：cli 包旁无 runtime 源码目录，跳过守卫 */
+	}
+	const stale = hostArtifactFreshnessError(versions["@oj-module/runtime"], workspaceRuntime);
+	if (stale)
+		throw new Error(stale);
+
 	const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, "package.json"), "utf-8"));
 	const errors = validateSharedVersions(pkg, versions, spec => readInstalledVersion(projectRoot, spec));
 

package/templates/api/.ojm-api-exempt.json

@@ -1,5 +1,9 @@
 {
 	"_comment": "ojm api --check 豁免清单（D12/F19）：把契约与 oj 路由对账中「确认无害」的差异降级为 skip。modules=整模块跳过双向对账（值是 oj 后端模块名，即 api/src/<模块> 的目录名）；paths=按路径跳过，'/xxx/*' 为一层通配（只盖 /xxx/<单段>），其余为精确前缀匹配。仅降级 error→skip，绝不引入新错误；文件缺失或 JSON 损坏时静默按空豁免处理。注意：本文件是严格 JSON，写 // 注释会导致解析失败、豁免静默全失效——说明请写在本 _comment 字段。",
-	"modules": ["web", "notifications"],
-	"paths": ["/auth/*"]
+	"modules": [
+		"web"
+	],
+	"paths": [
+		"/auth/*"
+	]
 }

package/templates/api/config.yaml

@@ -29,6 +29,11 @@
 mounts:
   - prefix: /api # api 挂载：/api/<module>/...（目录相对 config 所在目录 → api/src）
     api: src
+  # 本地模拟 CDN：直出工程根 cdn/（内容见 cdn/README.md）。
+  # 红线：生产请删掉这一条挂载，并把 system 设置 framework.market_cdn_url 指向真 CDN。
+  # 不得给此挂载设 spa——缺文件必须返回 404，回落 index.html 会让市场解析崩。
+  - prefix: /cdn
+    web: ../cdn
   # 生产若由 oj 直出前端（前后端同进程，即 ojm preview 的生产形态），
   # 取消下一行注释并先 build 出 web/dist（preview 会自动注入等价挂载，无需手改）：
   # - prefix: "/"
@@ -76,6 +81,12 @@ vars:
 # ---- 平台 exec 白名单（ojm install 的解压/迁移两处消费；模板逐字对齐 lifecycle steps 命令构造，
 # 不得增删——多一个 token 都会 NotCapable）----
 platform:
+  # 平台特权模块名单：方案安装器的 reloading 段调 server.reloadConfig 触发热更。
+  # 缺这条 → 装在最后一步报 NotCapable: module '_platform' is not platform-privileged。
+  modules: [_platform]
+  # 受控挂载根 = api 挂载目录（dev 形态 src）。ojm preview 派生 config 时会改写为 dist，
+  # 保持与 `--api-path` 同源；手写部署请按实际模块根填写。
+  root: src
   # ---- U6 信任库加固（P3-1；P2-2 红线 spike 结论）----
   # 威胁：devkit 0.1.75 语义下 fs: 段对全部模块生效（jail = fs.root），且 trusted_paths 只增不减——
   # 信任库落在第三方方案模块可写的 fs.root 内即可被其伪造信任锚。加固须两端配合：
@@ -92,6 +103,15 @@ platform:
         - 'tar -xzf ${path:archive} -C ${path:dest}'
         - 'oj migrate --format json -d ${path:dir} ${raw:module}'
 
+# ---- 方案安装器的落盘面（fs.* 全局）----
+# 安装器要解包到 modules/.staging、写 dist/modules、备份 db.sqlite——全在 config 目录内。
+# 缺本段 = fs.* 抛 NotCapable，且失败发生在任务文件落盘之前：表现为「POST 安装返回 200、
+# 但 task 查询恒 404」，排查成本极高。生产收紧口径见上面 platform 段的 U6 说明
+# （fs.root 收窄到安装子树 + third-party 模块 jail 隔离属部署清单项）。
+fs:
+  root: .
+  readonly: false
+
 # ---- LDAP 连接段（D1/PRD §4.5 两段式之连接段；oj 插件严格解析本段，未知键启动 fail-fast——只写下列键）----
 # 取消注释并填值即接通目录服务；应用映射段在 DB/设置页（ldap.enabled、ldap_base_dn、
 # ldap_uid_attr、ldap_email_attr，group=ldap，即时生效）。本段改动属 restart_pending，需重启。

package/templates/api/src/_platform/_lifecycle/steps/extract.ts

@@ -122,10 +122,13 @@ const NATIVE_KEYS = new Set(["name", "desc", "version", "config", "db", "tables"
 /**
  * C2-31 安装期复核纯函数（双端 DRY 于夹具，preflight 同纪律；构建侧同形实现在
  * packages/cli/src/bundle.ts checkModuleManifest）：包内 oj 原生清单 ↔ C2 Form A 逐项钉住——
- * name/version 三方一致、desc === summary（构建期映射真源；summary 缺省/多字节/空白边界）、
- * 七键白名单（白名单外键 = OJ-X 红线，oj 不拒但契约拒）。只验不写：安装期改写 desc 等于
- * 掩盖上游映射被篡改，必须拒装（附录 B-11 裁决备选的落地形态：bundle 侧 ojm build --bundle
- * 已写原生清单，安装期复核即映射消费点）。
+ * name/version 三方一致、七键白名单（白名单外键 = OJ-X 红线，oj 不拒但契约拒）。
+ * 只验不写：安装期改写原生清单等于掩盖上游不一致。
+ *
+ * 变更（2026-10-21）：**desc === summary 的等值校验已移除**。该等值要求把「构建期映射」
+ * 当成安装期契约，于是 fixture/手写包只要 desc 与 summary 有一字之差就整包装不上——
+ * 校验成本远高于它拦下的风险（desc 只是模块描述文本，非安全边界）。现只保留
+ * 「summary 必填（C2-04）」与「desc 必填非空（oj 启动装配面）」两项。
  */
 export function checkModuleManifest(
 	c2: unknown,
@@ -138,15 +141,12 @@ export function checkModuleManifest(
 	}
 	const summary = isObj(c2) && typeof c2.summary === "string" ? c2.summary : undefined;
 	if (summary === undefined || summary.trim() === "") {
-		return { ok: false, message: "C2 manifest summary 缺省或空白——desc 映射无真源（C2-31/C2-04）" };
+		return { ok: false, message: "C2 manifest summary 缺省或空白（C2-04 必填字段）——C2-31" };
 	}
 	const desc = native.desc;
 	if (typeof desc !== "string" || desc.trim() === "") {
 		return { ok: false, message: "包内原生清单 desc 缺失或空白（oj Manifest 必填字段，serve 装配即失败）——C2-31" };
 	}
-	if (desc !== summary) {
-		return { ok: false, message: "包内原生清单 desc 与 C2 summary 不一致（构建期映射被篡改或上游不一致，拒装）——C2-31" };
-	}
 	if (native.name !== name) {
 		return { ok: false, message: `包内原生清单 name「${String(native.name)}」与安装身份「${name}」不一致——C2-31` };
 	}

package/templates/api/src/_platform/_lifecycle/uninstall.ts

@@ -18,14 +18,12 @@ import { readLock, writeLock } from "./lock";
 
 // db 为 oj isolate 注入全局（同模板 service 层惯例，installer.ts 同款；测试由夹具装 globalThis.db）
 declare const db: {
-	exec: (sql: string, params: unknown[]) => Promise<unknown>
-	query: (sql: string, params?: unknown[]) => Promise<unknown>
-	/** 安全查询构造器（迁移目标；与 query 同返回行数组） */
+	/** 安全查询构造器（与 db.query 同返回行数组） */
 	table: (name: string) => any
-	/** 当前方言（sqlite/mysql/pg）；缺省 sqlite。Q4 业务表目录查询方言无关 */
-	dialect?: () => string
+	/** 目录自省（v0.1.82）：当前库全部/前缀匹配的表名（方言无关；前缀 %/_ 由引擎转义） */
+	listTables: (prefix?: string) => Promise<string[]>
 	/** 单一 DB 事务包裹（P3-3）：回调内语句共享一个 BEGIN/COMMIT/ROLLBACK 边界，异常即整段回滚 */
-	tx: <T>(fn: (t: { exec: (sql: string, params?: unknown[]) => Promise<unknown>, query: (sql: string, params?: unknown[]) => Promise<unknown>, table: (name: string) => any }) => Promise<T>) => Promise<T>
+	tx: <T>(fn: (t: { table: (name: string) => any }) => Promise<T>) => Promise<T>
 };
 
 function isObj(v: unknown): v is Record<string, unknown> {
@@ -62,45 +60,13 @@ function manifestTables(yamlText: string): string[] {
 	return out;
 }
 
-/** 当前方言（oj 注入 db.dialect，缺省 sqlite） */
-function currentDialect(): string {
-	const d = (db as { dialect?: () => string }).dialect;
-	return typeof d === "function" ? d() : "sqlite";
-}
-
-/** 表目录查询片段（方言无关：sqlite=sqlite_master，mysql/pg=information_schema） */
-export function catalogSpec(dialect: string): { existing: string, like: (pat: string) => [string, unknown[]] } {
-	if (dialect === "sqlite") {
-		return {
-			existing: "SELECT name FROM sqlite_master WHERE type='table'",
-			like: pat => ["SELECT name FROM sqlite_master WHERE type='table' AND name LIKE ? ESCAPE '!'", [pat]],
-		};
-	}
-	const schemaExpr = dialect === "mysql" ? "DATABASE()" : "'public'";
-	return {
-		existing: `SELECT table_name AS name FROM information_schema.tables WHERE table_schema = ${schemaExpr}`,
-		like: pat => [`SELECT table_name AS name FROM information_schema.tables WHERE table_schema = ${schemaExpr} AND table_name LIKE ? ESCAPE '!'`, [pat]],
-	};
-}
-
-/** 当前库实际存在的表名集合 */
-async function listExistingTables(dialect: string): Promise<Set<string>> {
-	// 保留 db.query：方言相关表目录查询（sqlite_master / information_schema），构造器无法表达
-	const rows = (await db.query(catalogSpec(dialect).existing)) as Array<{ name: string }>;
-	return new Set(rows.map(r => r.name));
-}
-
-/** 模块 slug 规范化 + LIKE 转义（沿用 RBAC 权限命名空间约定：!%_ 转义，连字符→下划线作表前缀） */
-export function tablePrefixPattern(name: string): string {
-	const slug = name.replace(/-/g, "_").replace(/[!%_]/g, c => `!${c}`);
-	// 表名用下划线分隔（非权限码的 `.`）：slug_ + 通配符 %（末尾 % 不转义，保持通配语义）
-	return `${slug}_%`;
+/** 模块 slug 规范化（连字符→下划线）作表前缀；db.listTables 内部按字面量前缀匹配（自动转义 %/_），无需手拼通配 */
+export function moduleTablePrefix(name: string): string {
+	return `${name.replace(/-/g, "_")}_`;
 }
 
 /** 收集需保留的业务表（Q4）：声明 + 前缀兜底；仅返回实际存在的表名 */
 export async function collectRetainedTables(name: string, manifestPath: string): Promise<string[]> {
-	const dialect = currentDialect();
-	const existing = await listExistingTables(dialect);
 	const candidates = new Set<string>();
 	// ① 声明式权威源：manifest.tables（通知等模块已在 manifest 声明业务表归属）
 	try {
@@ -111,17 +77,17 @@ export async function collectRetainedTables(name: string, manifestPath: string):
 	catch {
 		// manifest 缺失（api-only 方案）→ 仅前缀兜底
 	}
-	// ② 前缀兜底：扫描当前库匹配模块前缀的表，覆盖未声明场景
+	// ② 前缀兜底：db.listTables（v0.1.82，方言无关，前缀转义引擎做）枚举当前库匹配模块前缀的
+	//    实际表，覆盖未声明场景。listTables 已只返回存在的表，故前缀命中的候选天然存在。
 	try {
-		// 保留 db.query：LIKE ? ESCAPE '!' 转义子句，构造器 like 无 ESCAPE 支持
-		const [sql, params] = catalogSpec(dialect).like(tablePrefixPattern(name));
-		const rows = (await db.query(sql, params)) as Array<{ name: string }>;
-		for (const r of rows)
-			candidates.add(r.name);
+		for (const t of await db.listTables(moduleTablePrefix(name)))
+			candidates.add(t);
 	}
 	catch {
 		// 兜底扫描失败不阻断卸载
 	}
+	// 仅回传实际存在的表（manifest 声明的表若物理不存在则不回传）
+	const existing = new Set(await db.listTables());
 	return [...candidates].filter(t => existing.has(t));
 }
 
@@ -163,12 +129,14 @@ export async function computeUninstallImpact(input: UninstallInput): Promise<Uni
 	const roleNames = roles.map(r => r.name);
 	let affectedUsers = 0;
 	if (roleNames.length > 0) {
-		// 保留 db.query：IN 占位符经 JS 字符串拼接动态生成（动态 SQL），构造器 in 仅接受静态数组值
-		const rows = await db.query(
-			`select distinct user_id from sys_user_role where role_name in (${roleNames.map(() => "?").join(",")})`,
-			roleNames,
-		) as Array<{ user_id: number }>;
-		affectedUsers = rows.length;
+		// 构造器（v0.1.82）：count(distinct) 聚合一行返回，不受 LIMIT 钳制——
+		// 旧 distinct().all().length 因顶层隐式 LIMIT（默认 100）/ 显式 clamp（max_limit 默认 1000）
+		// 在受影响用户 >1000 时静默漏算（今天就有正确性风险，须尽快迁移）。
+		const rows = await db.table("sys_user_role")
+			.select([{ fn: "count", distinct: true, field: "user_id", as: "c" }])
+			.where({ field: "role_name", op: "in", value: roleNames })
+			.all() as Array<{ c: number }>;
+		affectedUsers = rows[0]?.c ?? 0;
 	}
 	return { name, affectedRoles: roleNames.length, affectedUsers };
 }

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

@@ -2,8 +2,6 @@
 // 目录红线：只出 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 "../infra/query";
-
 export interface ContactRow {
 	id: number
 	username: string
@@ -14,16 +12,23 @@ 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）
+	// 长度红线（默认 2~64，越界 400）——与 query.ts likePattern 同口径；contains 自动转义 %/_/!，无需手写 ESCAPE。
+	const kw = String(keyword ?? "").trim();
+	if (kw.length < 2 || kw.length > 64)
+		throw Object.assign(new Error(kw.length < 2 ? "keyword too short (min 2)" : "keyword too long (max 64)"), { status: 400 });
 	const rawLimit = Number.parseInt(String(opts.limit ?? ""), 10);
 	const limit = Number.isFinite(rawLimit) && rawLimit >= 1 ? Math.min(MAX_LIMIT, rawLimit) : DEFAULT_LIMIT;
-	// 保留 db.query：模糊搜索需 ESCAPE '!'(构造器 like 无 escape 子句；mysql 默认 sql_mode 下 ESCAPE '\' 即 1064)
-	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 unknown as ContactRow[];
+	// 构造器（v0.1.81）：模糊搜索走语义 op contains（自动转义 + 包 %），OR 用条件树 or，方言无关。
+	return await db.table("users")
+		.select(["id", "username", "display_name"])
+		.where({ field: "is_forbidden", op: "eq", value: 0 })
+		.where({ or: [
+			{ field: "username", op: "contains", value: kw },
+			{ field: "display_name", op: "contains", value: kw },
+		] })
+		.orderBy([{ field: "username", dir: "asc" }])
+		.limit(limit)
+		.all() as unknown as ContactRow[];
 }
 
 export async function contactDetail(id: number): Promise<Record<string, unknown>> {

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

@@ -73,10 +73,12 @@ export async function upsertSolutionPerms(m: SolutionManifest): Promise<UpsertRe
 	return { deprecated };
 }
 
-/** 事务/非事务统一的 db 面（P3-3：可传入 db.tx 的事务句柄以纳入单一事务） */
+/**
+ * 事务/非事务统一的 db 面（P3-3：可传入 db.tx 的事务句柄以纳入单一事务）。
+ *  只收 table——全构造器化后（v0.1.81 startswith 补齐最后缺口）本出口不再走裸 SQL，
+ *  契约随实现收窄：tx 句柄（{table}）与全局 db 均可传入。
+ */
 interface DbLike {
-	query: (sql: string, params?: unknown[]) => Promise<unknown>
-	exec: (sql: string, params?: unknown[]) => Promise<unknown>
 	table: DBInstance["table"]
 }
 
@@ -95,8 +97,8 @@ export async function uninstallSolution(module: string, d: DbLike = db): Promise
 		await d.table("sys_user_role").where({ field: "role_name", op: "eq", value: r.name }).delete().run();
 	}
 	await d.table("sys_role").where({ field: "module", op: "eq", value: module }).delete().run();
-	// 保留 d.exec：LIKE ? escape '!' 转义子句构造器 like 不支持（三方言 ESCAPE 同义纪律见 query.ts）
-	const prefix = `${module.replace(/[!%_]/g, c => `!${c}`)}.%`;
-	await d.exec("delete from sys_role_permission where permission_code like ? escape '!'", [prefix]);
+	// startswith（v0.1.81）：语义化前缀匹配（⇒ `v%`），引擎自动转义 %/_/!——
+	// 替代旧「手工 escape 拼接 + 裸 SQL like ? escape '!'」（三方言 ESCAPE 同义纪律见 query.ts）
+	await d.table("sys_role_permission").where({ field: "permission_code", op: "startswith", value: `${module}.` }).delete().run();
 	await d.table("sys_permission").where({ field: "module", op: "eq", value: module }).delete().run();
 }

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

@@ -1,6 +1,6 @@
 // 操作日志查询（AC1-29/D13：admin 可查；读操作不记审计的红线不适用——本表本身就是审计）。
-// 过滤维度：action 精确 / username 前缀 / module 精确；分页复用 query.ts（limit 钳 200/truncated）。
-import { likePattern, paged } from "./query";
+// 过滤维度：action 精确 / username 包含 / module 精确；分页复用 query.ts 的 pagedFactory（构造器工厂）。
+import { pagedFactory } from "./query";
 
 export interface OplogRow {
 	id: number
@@ -22,26 +22,19 @@ export interface OplogPage {
 }
 
 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 },
-	);
+	// 构造器（v0.1.82）：可选过滤走 whereIf，条件写一份（mk 工厂），count + list 复用；
+	// username 走语义 op contains（引擎转义 %/_/!，等价旧 LIKE ? ESCAPE '!' 的 %kw%）。
+	// 照抄口径：devkit scenarios 场景 42 ④。
+	// 注意 whereIf 的跳过集是 undefined/null/false/[]——**"" 是合法值会保留**（api-manual
+	// §1153），故缺失值必须归一化为 undefined（不能图省事用 ""，否则会发射 `action = ''`
+	// 把结果过滤空——与旧 if (filter.x) 的「假值整条跳过」语义相悖）。
+	const action = filter.action ? String(filter.action) : undefined;
+	const module = filter.module ? String(filter.module) : undefined;
+	const username = filter.username ? String(filter.username) : undefined;
+	const mk = () => db.table("sys_oplog")
+		.whereIf(action, { field: "action", op: "eq", value: action })
+		.whereIf(module, { field: "module", op: "eq", value: module })
+		.whereIf(username, { field: "username", op: "contains", value: username });
+	const r = await pagedFactory<OplogRow>(mk, { size: filter.limit });
 	return { list: r.list, total: r.total, truncated: r.truncated };
 }

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

@@ -37,6 +37,24 @@ export async function paged<T>(
 	return { list, total, page, size, truncated: offset + list.length < total };
 }
 
+// 构造器分页工厂（v0.1.82）：条件写一份（mk 工厂），count + list 各跑一次（count 用聚合，
+// 不受 LIMIT 钳制）；替代「接受任意 SQL 片段」的旧 paged（裸 SQL 包装器）。条件收敛到构造器
+// （contains 替代 LIKE ? ESCAPE '!'），残留任意 SQL 的场景才继续走旧 paged。
+type Builder = ReturnType<typeof db.table>;
+export async function pagedFactory<T>(
+	mk: () => Builder,
+	input: { page?: unknown, size?: unknown } = {},
+): Promise<PageResult<T>> {
+	const { page, size, offset } = pageArgs(input);
+	const total = Number(
+		(await mk().select([{ fn: "count", as: "c" }]).all() as Array<Record<string, unknown>>)[0]?.c ?? 0,
+	);
+	const list = total === 0
+		? []
+		: await mk().orderBy([{ field: "id", dir: "desc" }]).limit(size).offset(offset).all() as T[];
+	return { list, total, page, size, truncated: total > page * size };
+}
+
 /**
  * LIKE 模式：修剪后校验长度（默认 2~64），元字符 % _ ! 加 ! 转义，两侧包 %。
  *  SQL 侧必须写 `like ? escape '!'`（三方言同语义；sqlite 默认无转义符，mysql/pg 默认不是 !）。

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

@@ -75,5 +75,8 @@ export async function loginSucceeded(key: string): Promise<void> {
 
 /** 清登录限速状态（测试夹具/运维排障用）。 */
 export async function resetLoginThrottle(): Promise<void> {
-	await db.exec("delete from sys_login_throttle", []);
+	// 构造器（v0.1.82）：truncate() 是唯一的「无 where 清空」写动词，命名式、可 grep，
+	// 取代裸 db.exec("delete from …")（审查上像漏写 where 的 delete）。渲染 DELETE FROM t，
+	// 租户守卫照常注入（本表非租户表=整表清空）。
+	await db.table("sys_login_throttle").truncate().run();
 }

package/templates/api/src/_platform/fixtures/l1-test-user.sql

@@ -0,0 +1,13 @@
+-- L1 测试账号（仅 `oj test` 经 fixtures 灌入，不进 release 产物）。
+--
+-- 为什么不能用 seed 的 admin 跑 L1 登录：
+--   ① seed 的 admin 是 must_change=1 首登改密态（D12 生产语义），且初始口令 123456
+--      只是开发便利——用户在 dev 库改过口令后（产品主动引导），admin 口令即漂移，
+--      L1 若绑 admin/123456 会随机 401（本地实测踩过：dev 库口令被改成 12345678）。
+--   ② 判权类端点（currentAccess/assertPermission）对 must_change=1 恒 403。
+-- 故 additive 建一个专用账号：INSERT OR IGNORE 幂等，反复重放终态一致，
+-- 不碰 admin 既有行（用户的口令/状态不受 `oj test` 影响）。
+-- 按分号朴素切分（S006）：语句内不得含分号字面量。
+INSERT OR IGNORE INTO users (username, password_hash, avatar_base64, source, display_name, must_change, is_forbidden) VALUES ('l1tester', '$2b$10$/0DuEHsBLYp6.5ZLJCFafOOvksLbruMvs9aMhUqRSpbdY52D9RaXS', '', 'local', 'L1 测试账号', 0, 0);
+-- 绑 superadmin：L1 若打判权类端点可直通（账号生命周期 B6 建号默认 must_change=1，这里显式 0）
+INSERT OR IGNORE INTO sys_user_role (user_id, role_name) SELECT id, 'superadmin' FROM users WHERE username = 'l1tester';

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

@@ -2,6 +2,7 @@ name: _platform
 desc: 平台内核（非业务模块、无自身业务路由前缀）。含三类：① 跨模块服务 _shared/service（infra 基础设施 + domain 管理域）；② 生命周期引擎 _lifecycle（方案安装/卸载/注册/验签/信任状态机）；③ 平台编排 API 面 /api/_platform/{contacts,market,solutions}（由 market/api.ts、contacts/api.ts、solutions/api.ts 暴露，全 superadmin 门禁）。运行时安装的方案包不在此树。
 version: 0.1.0
 tables:
+  - _oj_migrations
   - users
   - sys_setting
   - sys_oplog

package/templates/api/src/_platform/migrations/0013__users_profile.sql

@@ -0,0 +1,4 @@
+-- 个人中心资料字段：phone_number/description 可空列——「我的资料」表单
+-- POST /api/personal-center/profile 入库用；可空先例同 0007（email）。
+ALTER TABLE users ADD COLUMN phone_number TEXT;
+ALTER TABLE users ADD COLUMN description TEXT;

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

@@ -1,7 +1,17 @@
 # 框架级共有表上收 _platform 伪模块（§3-D2）：归属图单源，杜绝「散在模块 seed」。
 # 与 manifest.tables 双向一致（S005）；auth 模块跨模块读 users 经 deps 声明。
 # D10：users.roles JSON 列已移除——角色唯一权威源为 sys_user_role 关系表。
+# _oj_migrations 为 oj 迁移 journal 内建表（oj 自建自管 DDL）；此处声明只为让 db.table
+# 元数据校验放行（journalHeadOf：深检 ledger 复核 + P3-11 预锁 guard 的真源），列与 oj 真表逐列对齐。
 tables:
+  _oj_migrations:
+    pk: [module, version]
+    columns:
+      module: {type: text, null: false}
+      version: {type: integer, null: false}
+      name: {type: text}
+      applied_on: {type: text}
+      checksum: {type: text}
   users:
     pk: id
     columns:
@@ -14,6 +24,8 @@ tables:
       must_change: {type: integer, null: false}
       is_forbidden: {type: integer, null: false}
       email: {type: text}
+      phone_number: {type: text}
+      description: {type: text}
   sys_setting:
     pk: key
     columns:

package/templates/api/src/auth/_shared/session.ts

@@ -111,8 +111,8 @@ export function createSession(deps: SessionDeps = runtimeDeps()) {
 
 		/** B3：刷新——轮换作旧；reuse 检测（已吊销串二次出现）全族吊销 + 审计。 */
 		async refresh(token: string): Promise<TokenBundle> {
-			// 保留 db.query：select * 无已知列清单（规则6）
-			const rows = await db.query("select * from sys_refresh_token where token_hash = ?", [hashOf(String(token ?? ""))]) as Array<Record<string, unknown>>;
+			// 构造器（v0.1.81）：select(["*"]) 显式拉全列，无已知列清单也能用，方言无关。
+			const rows = await db.table("sys_refresh_token").select(["*"]).where({ field: "token_hash", op: "eq", value: hashOf(String(token ?? "")) }).all() as Array<Record<string, unknown>>;
 			const row = rows[0];
 			if (!row)
 				fail(401, "invalid or expired refresh token");

package/templates/api/src/demo/todos/api.ts

@@ -6,16 +6,15 @@
 const todos = {
 	async get() {
 		const kw = http.query.keyword;
-		const where = kw ? "WHERE title LIKE ?" : "";
-		const params = kw ? [`%${kw}%`] : [];
+		const hasKw = typeof kw === "string" && kw.length > 0;
+		// 构造器：模糊过滤走语义 op（contains 自动转义 %/_/!），count 走聚合，方言无关。
+		const build = () => db.table("todos").whereIf(hasKw, { field: "title", op: "contains", value: kw });
 		try {
-			// 保留 db.query：WHERE 由 JS 字符串拼接动态生成（规则5）
-			const totalRows = await db.query(`SELECT COUNT(*) AS c FROM todos ${where}`, params);
-			const total = Number(totalRows[0]?.c ?? 0);
-			const rows = await db.query(
-				`SELECT id, title, done, create_time, update_time FROM todos ${where} ORDER BY id ASC`,
-				params,
-			);
+			const total = Number((await build().select([{ fn: "count", as: "c" }]).all())[0]?.c ?? 0);
+			const rows = await build()
+				.select(["id", "title", "done", "create_time", "update_time"])
+				.orderBy([{ field: "id", dir: "asc" }])
+				.all();
 			const list = rows.map(r => ({
 				id: Number(r.id),
 				title: String(r.title),