@oj-module/cli 0.2.1 → 0.2.5

package/templates/api/src/_platform/market/bootstrap.ts

@@ -0,0 +1,39 @@
+// 第一方 bootstrap key（P2-12，G3 双轨第一轨）：模板内置 oj-market 首包发布方公钥——
+// market 首装免 TOFU（信任库为空时自动播种，直接过验签）。发布流程（devkit「签名与信任」章节，
+// P2-14 引用）：发布人 `ojm keygen` 生成 Ed25519 对（私钥永不出 ~/.ojm/keys/<id>）→ `ojm sign`
+// 签 oj-market 首发包 → 公钥（64 hex）+ key_id 回填本文件随模板发布。**模板内只有公钥**——
+// 私钥入仓即信任根基烧毁（tests/lifecycle/bootstrap.spec 钉全仓 grep 私钥 pattern 零命中）。
+// 播种纪律：只在信任库文件尚不存在时播种一次——不与运维吊销对抗（remove 后不复活，G5 语义）。
+
+import { fsFace } from "../_lifecycle/atomic";
+import { createTrustStore } from "../_lifecycle/trust";
+
+export interface BootstrapKey {
+	key_id: string
+	/** 32B raw Ed25519 公钥 hex（C2-35 口径） */
+	public_key: string
+}
+
+/**
+ * 第一方发布方 key（oj-market 首包）。发布时回填——回填前为 null（播种即 no-op，
+ * 首装走 TOFU 双轨第二轨：needs_trust → ojm trust confirm）。
+ */
+export const BOOTSTRAP_KEY: BootstrapKey | null = null;
+
+/**
+ * 引导播种（installBody 接线，runInstall 之前）：信任库文件尚不存在且 bootstrap key 在场 →
+ * 播种并审计（operator="bootstrap" 标记机器播种）。key 为 null（未回填）或库已初始化 → no-op。
+ */
+export async function seedBootstrapKey(trustPath: string, key: BootstrapKey | null): Promise<void> {
+	if (key === null) {
+		return;
+	}
+	try {
+		await fsFace().readFile(trustPath);
+		return; // 库文件已存在（含空库）= 已初始化过 → 不播种（防吊销复活）
+	}
+	catch {
+		// 不存在 → 首次引导
+	}
+	await createTrustStore(trustPath).add(key.key_id, key.public_key, { operator: "bootstrap" });
+}

package/templates/api/src/_platform/migrations/0010__sys_solution_route.mysql.sql

@@ -0,0 +1,17 @@
+-- 方案注册路由表重构 mysql 方言覆盖（sqlite 版见 0010__sys_solution_route.sql）。
+-- 差异：保留字反引号；整型列取 BIGINT；主键 TEXT → VARCHAR(255)；
+-- ALTER ADD COLUMN / CREATE INDEX 无 IF NOT EXISTS（迁移账本一次应用语义兜底，同 0008）。
+ALTER TABLE sys_setting ADD COLUMN deprecated BIGINT NOT NULL DEFAULT 0;
+
+DROP TABLE IF EXISTS sys_solution_route;
+CREATE TABLE sys_solution_route (
+  path VARCHAR(255) PRIMARY KEY,
+  module TEXT NOT NULL,
+  category TEXT NOT NULL,
+  `order` BIGINT NOT NULL DEFAULT 0,
+  title_key TEXT,
+  required_permission TEXT,
+  deprecated BIGINT NOT NULL DEFAULT 0,
+  enabled BIGINT NOT NULL DEFAULT 1
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+CREATE INDEX idx_sys_solution_route_module ON sys_solution_route (module);

package/templates/api/src/_platform/migrations/0010__sys_solution_route.pg.sql

@@ -0,0 +1,16 @@
+-- 方案注册路由表重构 pg 方言覆盖（sqlite 版见 0010__sys_solution_route.sql）。
+-- 差异：无（ADD COLUMN / DROP TABLE / 双引号保留字 / CREATE INDEX IF NOT EXISTS pg 原生支持）。
+ALTER TABLE sys_setting ADD COLUMN deprecated INTEGER NOT NULL DEFAULT 0;
+
+DROP TABLE IF EXISTS sys_solution_route;
+CREATE TABLE sys_solution_route (
+  path TEXT PRIMARY KEY,
+  module TEXT NOT NULL,
+  category TEXT NOT NULL,
+  "order" INTEGER NOT NULL DEFAULT 0,
+  title_key TEXT,
+  required_permission TEXT,
+  deprecated INTEGER NOT NULL DEFAULT 0,
+  enabled INTEGER NOT NULL DEFAULT 1
+);
+CREATE INDEX IF NOT EXISTS idx_sys_solution_route_module ON sys_solution_route (module);

package/templates/api/src/_platform/migrations/0010__sys_solution_route.sql

@@ -0,0 +1,18 @@
+-- 方案注册路由表重构（P1-8，D10 注册唯一出口的落点）：0004 版以 (name, version, path) 为主键、
+-- 无 module/required_permission/deprecated 列，与「站点级路由注册（path 唯一 + 声明消失标
+-- deprecated，镜像 AC2-3/4）」的语义不兼容；旧表从未被运行时读写（仅存在性断言），DROP 重建零数据损失。
+-- 同时为 sys_setting 补 deprecated 列：设置定义行声明消失同样保留标 deprecated（P1-8 register 语义）。
+ALTER TABLE sys_setting ADD COLUMN deprecated INTEGER NOT NULL DEFAULT 0;
+
+DROP TABLE IF EXISTS sys_solution_route;
+CREATE TABLE sys_solution_route (
+  path TEXT PRIMARY KEY,
+  module TEXT NOT NULL,
+  category TEXT NOT NULL,
+  "order" INTEGER NOT NULL DEFAULT 0,
+  title_key TEXT,
+  required_permission TEXT,
+  deprecated INTEGER NOT NULL DEFAULT 0,
+  enabled INTEGER NOT NULL DEFAULT 1
+);
+CREATE INDEX IF NOT EXISTS idx_sys_solution_route_module ON sys_solution_route (module);

package/templates/api/src/_platform/migrations/0011__sys_setting_group_label.mysql.sql

@@ -0,0 +1,2 @@
+-- sys_setting 补 group_label_key mysql 方言覆盖（0002/0003 先例同型：TEXT 可空列与基线同语法）。
+ALTER TABLE sys_setting ADD COLUMN group_label_key TEXT;

package/templates/api/src/_platform/migrations/0011__sys_setting_group_label.sql

@@ -0,0 +1,4 @@
+-- sys_setting 补 group_label_key：方案设置组标题（C2-22 组级 label_key）落库——
+-- 前端此前只能按 <module>:settings.group.<group> 惯例推导（P1-14 备案：declOf 丢弃组级
+-- label_key），声明键可与惯例不同 → 组标题真实值随注册面回填（P2-15 G7 承载③）。
+ALTER TABLE sys_setting ADD COLUMN group_label_key TEXT;

package/templates/api/src/_platform/migrations/0012__market_history.mysql.sql

@@ -0,0 +1,13 @@
+-- market_history mysql 方言覆盖（方言覆盖必胜，通用兜底；oj-bin docs/migration.md §3.1）。
+-- 差异：AUTOINCREMENT → BIGINT AUTO_INCREMENT；TEXT 列按业务长度收窄为 VARCHAR；
+-- created_at 用 BIGINT（秒级 epoch）。
+CREATE TABLE IF NOT EXISTS market_history (
+  id BIGINT AUTO_INCREMENT PRIMARY KEY,
+  solution VARCHAR(255) NOT NULL,
+  version VARCHAR(255) NOT NULL,
+  action VARCHAR(64) NOT NULL,
+  status VARCHAR(64) NOT NULL,
+  operator VARCHAR(255),
+  message TEXT,
+  created_at BIGINT NOT NULL
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

package/templates/api/src/_platform/migrations/0012__market_history.pg.sql

@@ -0,0 +1,12 @@
+-- market_history pg 方言覆盖（方言覆盖必胜，通用兜底；oj-bin docs/migration.md §3.1）。
+-- 差异：AUTOINCREMENT → BIGSERIAL；TEXT 在 pg 合法，保留 TEXT。
+CREATE TABLE IF NOT EXISTS market_history (
+  id BIGSERIAL PRIMARY KEY,
+  solution TEXT NOT NULL,
+  version TEXT NOT NULL,
+  action TEXT NOT NULL,
+  status TEXT NOT NULL,
+  operator TEXT,
+  message TEXT,
+  created_at BIGINT NOT NULL
+);

package/templates/api/src/_platform/migrations/0012__market_history.sql

@@ -0,0 +1,14 @@
+-- market_history 表上收 _platform（P4 裁决：市场操作历史为平台级审计面，归属平台核心，
+-- 不再由 oj-market 方案包自带迁移创建）。install/enable/disable/uninstall/upgrade/rollback
+-- 六类动作留痕；前端历史抽屉与版本历史对比只读消费。
+-- 结构只进 migrations（S006）；与 schema.yaml 列集一致。
+CREATE TABLE IF NOT EXISTS market_history (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  solution TEXT NOT NULL,
+  version TEXT NOT NULL,
+  action TEXT NOT NULL,
+  status TEXT NOT NULL,
+  operator TEXT,
+  message TEXT,
+  created_at INTEGER NOT NULL
+);

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

@@ -24,8 +24,10 @@ tables:
       value: {type: text}
       default_value: {type: text}
       label_key: {type: text}
+      group_label_key: {type: text}
       options: {type: text}
       secret: {type: integer, null: false}
+      deprecated: {type: integer, null: false}
       update_time: {type: integer, null: false}
   sys_oplog:
     pk: id
@@ -41,14 +43,16 @@ tables:
       detail: {type: text}
       level: {type: integer, null: false}
   sys_solution_route:
-    pk: [name, version, path]
+    # 0010 重构后形状（站点级路由，path 主键；与 migrations/0010__sys_solution_route.sql 逐列一致）。
+    pk: path
     columns:
-      name: {type: text, null: false}
-      version: {type: text, null: false}
-      category: {type: text, null: false}
       path: {type: text, null: false}
+      module: {type: text, null: false}
+      category: {type: text, null: false}
       order: {type: integer, null: false}
       title_key: {type: text}
+      required_permission: {type: text}
+      deprecated: {type: integer, null: false}
       enabled: {type: integer, null: false}
   sys_role:
     pk: name
@@ -84,3 +88,16 @@ tables:
       expires_at: {type: integer, null: false}
       revoked: {type: integer, null: false}
       created_at: {type: integer, null: false}
+  # 市场操作历史（P4 上收 _platform）：install/enable/disable/uninstall/upgrade/rollback 六类动作留痕。
+  # 写入由平台编排面（_lifecycle/history.ts recordHistory）落到本表；市场页只读消费。
+  market_history:
+    pk: id
+    columns:
+      id: {type: integer, autoincrement: true}
+      solution: {type: text, null: false}
+      version: {type: text, null: false}
+      action: {type: text, null: false}
+      status: {type: text, null: false}
+      operator: {type: text}
+      message: {type: text}
+      created_at: {type: integer, null: false}

package/templates/api/src/_platform/seed.sql

@@ -11,9 +11,9 @@ INSERT OR IGNORE INTO sys_role (name, module, title, builtin) VALUES ('editor',
 INSERT OR IGNORE INTO sys_role (name, module, title, builtin) VALUES ('viewer', 'framework', '访客', 1);
 -- seed 超管绑定（sys_user_role 唯一权威源，D10）
 INSERT OR IGNORE INTO sys_user_role (user_id, role_name) SELECT id, 'superadmin' FROM users WHERE username = 'admin';
--- 系统设置默认值（PRD §4.3；C4 设置页 / C5 登录方式发现的数据源；market.cdn_url 安全组仅 superadmin 可改）
+-- 系统设置默认值（PRD §4.3；C4 设置页 / C5 登录方式发现的数据源；framework.market_cdn_url 安全组仅 superadmin 可改）
 INSERT OR 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 OR 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 OR IGNORE INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('framework.market_cdn_url', 'framework', 'security', 'string', '', '', 'system:setting.market_cdn_url', 0, 0);
 INSERT OR 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 OR 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);
 INSERT OR IGNORE INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('ldap_base_dn', 'ldap', 'ldap', 'string', '', '', 'system:setting.ldap_base_dn', 0, 0);

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

@@ -0,0 +1,212 @@
+import type { ModuleEntryIntegrity, SolutionRouteRow, SolutionsEnv, VerifyItem } from "../_lifecycle/verify-checks";
+import type { VerifyReport } from "../_lifecycle/verify-report";
+import type { FetchInitFace } from "../_shared/site-facade";
+// 平台方案路由读端点 /api/_platform/solutions/routes（P1-14，R21 前端归并数据源）+ 深检端点
+// /api/_platform/solutions/verify?name=（P2-7，C2-42；admin 域、全程不触 exec）。
+// 登录即可、只读、无权限点（contacts/api.ts 同纪律）；读操作不记审计。
+// routes：只下发未 deprecated 行全列（required_permission 仅供深检对比，前端不做权限级菜单过滤，R22）。
+// verify：四项检查（路由可达/RBAC/设置/迁移账本）编排 + 可信性项（P2-8 trust_state）+ i18n 依赖项；
+// 返回 VerifyReport{ok,checks,advise} 并落盘 verify-reports（时间序 N=10 留存）。
+// 行序稳定：module → order → path。
+import { fsFace } from "../_lifecycle/atomic";
+import { sha384B64 } from "../_lifecycle/sha384";
+import { createStateStore } from "../_lifecycle/state";
+import {
+	declaredMigrationsOf,
+	declaredSettingsOf,
+	diffLedger,
+	diffPermRows,
+	diffSettingRows,
+	diffWebIntegrity,
+	readSolutionManifest,
+
+	verifyRouteReachability,
+} from "../_lifecycle/verify-checks";
+import { getLastReport, persistReport, verifyReportsDirOf } from "../_lifecycle/verify-report";
+import { respond } from "../_shared/respond";
+import { assertSystemAdmin } from "../_shared/service/access";
+import { journalHeadOf, siteOrigin } from "../_shared/site-facade";
+
+/** 线格式行（与 packages/runtime/src/api/rbac/types.ts 的 SolutionRouteRow 对齐） */
+export type { SolutionRouteRow } from "../_lifecycle/verify-checks";
+
+/** oj serve release 布局生产缺省 */
+export function solutionsEnv(): SolutionsEnv {
+	return {
+		sharedRoot: "dist",
+		statePath: "modules/.solutions/state.yaml",
+		modulesJsonPath: "dist/modules.json",
+		apiPrefix: "/api",
+	};
+}
+
+function fetchOf(env: SolutionsEnv): FetchInitFace {
+	return env.fetch ?? (globalThis as { fetch?: FetchInitFace }).fetch as FetchInitFace;
+}
+
+/** 路由行映射（sys_solution_route → SolutionRouteRow） */
+function rowOf(r: Record<string, unknown>): SolutionRouteRow {
+	return {
+		path: String(r.path),
+		module: String(r.module),
+		category: r.category === "admin" || r.category === "hidden" ? r.category : "main",
+		order: Number(r.order),
+		title_key: r.title_key == null ? null : String(r.title_key),
+		required_permission: r.required_permission == null ? null : String(r.required_permission),
+		enabled: Number(r.enabled) === 1,
+	};
+}
+
+/** 取并校验深检 name 参数（空 → 400；端点门之一） */
+function verifyNameOf(): string {
+	const name = String((globalThis as { http?: { query?: Record<string, unknown> } }).http?.query?.name ?? "").trim();
+	if (name === "")
+		throw Object.assign(new Error("name is required"), { status: 400 });
+	return name;
+}
+
+/**
+ * 可信性项（P2-8）：发布方 key 状态（G5 吊销后已装方案继续运行却无人知晓的补位）。
+ * trusted → 干净不打项；untrusted → error（key 已吊销仍在跑）；absent/未写（P1 遗留）→ info（无法校验来源，非阻断）。
+ */
+async function trustItemOf(env: SolutionsEnv, name: string): Promise<VerifyItem | null> {
+	const state = await createStateStore(env.statePath);
+	const ts = state.read().solutions[name]?.trust_state;
+	if (ts === "trusted")
+		return null;
+	if (ts === "untrusted")
+		return { id: "trust", severity: "error", subject: name, advise_key: "lifecycle.verify.trust.untrusted" };
+	return { id: "trust", severity: "info", subject: name, advise_key: "lifecycle.verify.trust.absent" };
+}
+
+/** 深检主体：四项检查编排 + 可信性项 + i18n 依赖项，组装 VerifyReport{ok,checks,advise}（persist 归端点） */
+async function verifyBody(env: SolutionsEnv, name: string): Promise<VerifyReport> {
+	// 已装校验：sys_solution_route 有该 module 行（未装 → 404，端点门之一）
+	const routeRows = await db.query(
+		`select path, module, category, "order", title_key, required_permission, enabled
+		from sys_solution_route where deprecated = 0 and module = ?`,
+		[name],
+	) as Array<Record<string, unknown>>;
+	if (routeRows.length === 0)
+		throw Object.assign(new Error(`方案「${name}」未安装或无路由注册`), { status: 404 });
+
+	const routes = routeRows.map(rowOf);
+
+	// ① 路由可达性（I/O 探针；siteOrigin 复用 = SSRF 钉② header 清洗，probeUrlOf 内建钉①）
+	const reach = await verifyRouteReachability(fetchOf(env), routes, siteOrigin());
+
+	// ② RBAC 完整性：声明权限点 ↔ sys_permission 实有
+	const declaredPerms = [...new Set(routes.map(r => r.required_permission).filter((p): p is string => p != null))];
+	const permRows = await db.query("select code from sys_permission") as Array<{ code: string }>;
+	const rbac = diffPermRows(declaredPerms, new Set(permRows.map(r => r.code)));
+
+	// ③ 设置完整性：manifest 声明设置 key ↔ sys_setting 实有（永不含值）
+	const manifest = await readSolutionManifest(env, name);
+	const declaredSettings = manifest ? declaredSettingsOf(manifest.manifest) : [];
+	const settingRows = await db.query("select key from sys_setting where module = ? and deprecated = 0", [name]) as Array<{ key: string }>;
+	const settings = diffSettingRows(declaredSettings, new Set(settingRows.map(r => r.key)));
+
+	// ④ 迁移账本：manifest 迁移目录最高版本 ↔ _oj_migrations 实有（journalHeadOf 复用，DRY）
+	const declaredMig = manifest
+		? declaredMigrationsOf(await listMigrationFiles(env, name, manifest.version), name)
+		: [];
+	const applied = new Map<string, number | null>();
+	applied.set(name, Number(await journalHeadOf(name)));
+	const ledger = diffLedger(declaredMig, applied);
+
+	// ⑤ web 入口 integrity（P4-2，P3-10#2 收口）：modules.json 条目 integrity ↔ 本地 dist 资产重算
+	// sha384 比对；SSRF 钉：只比对本地资产，绝不经 fetch 出站（与路由可达性探针严格隔离）。
+	let webChecks: VerifyItem[] = [];
+	try {
+		const mjPath = env.modulesJsonPath;
+		if (typeof mjPath === "string") {
+			const slash = mjPath.lastIndexOf("/");
+			const distRoot = slash === -1 ? "." : mjPath.slice(0, slash);
+			const list = JSON.parse(new TextDecoder().decode(await fsFace().readFile(mjPath))) as unknown[];
+			if (Array.isArray(list))
+				webChecks = await diffWebIntegrity(list as ModuleEntryIntegrity[], distRoot, sha384B64);
+		}
+	}
+	catch {
+		// modules.json 缺失/不可读 → 不打 web 项（非阻断，避免深检自身因装配清单缺失而误报）
+	}
+
+	const checks: VerifyItem[] = [...reach, ...rbac, ...settings, ...ledger, ...webChecks];
+	const trust = await trustItemOf(env, name);
+	if (trust !== null)
+		checks.push(trust);
+
+	// i18n 依赖项（info，非阻断）：本仓只下发待查 key 清单（advise），前端经 oj-market 解析文案；
+	// 缺执行降级「未校验」不阻断。先据既有检查项判定是否需要 i18n 解析，再纳入 advise 清单。
+	const baseAdvise = [...new Set(checks.map(c => c.advise_key))].sort();
+	if (baseAdvise.length > 0)
+		checks.push({ id: "i18n", severity: "info", subject: String(baseAdvise.length), advise_key: "lifecycle.verify.i18n.dependency" });
+
+	const advise = [...new Set(checks.map(c => c.advise_key))].sort();
+	const ok = !checks.some(c => c.severity === "error");
+	return { ok, checks, advise };
+}
+
+/** 版本目录内迁移文件名清单（读不到目录 → 空，意为无迁移声明） */
+async function listMigrationFiles(env: SolutionsEnv, name: string, version: string): Promise<string[]> {
+	try {
+		return await fsFace().readdir(`${env.sharedRoot}/${name}-${version}/migrations`);
+	}
+	catch {
+		return [];
+	}
+}
+
+export function createSolutionsApi(env: SolutionsEnv) {
+	return {
+		// GET /api/_platform/solutions/routes —— 前端归并数据源（登录即可）。
+		routes: {
+			async get() {
+				if (!http.user?.id) {
+					json.fail(401, "unauthorized");
+					return;
+				}
+				await respond(async () => {
+					const rows = await db.query(
+						`select path, module, category, "order", title_key, required_permission, enabled
+						from sys_solution_route where deprecated = 0 order by module, "order", path`,
+					) as Array<Record<string, unknown>>;
+					return rows.map(rowOf);
+				});
+			},
+		},
+		// POST /api/_platform/solutions/verify?name= —— 深检（admin 域；不触 exec）。
+		verify: {
+			async post() {
+				await respond(async () => {
+					if (!http.user?.id)
+						throw Object.assign(new Error("unauthorized"), { status: 401 });
+					await assertSystemAdmin();
+					const name = verifyNameOf();
+					const report = await verifyBody(env, name);
+					// 落盘 verify-reports（时间序 N=10 留存；persist 失败不应阻断响应——但异常须上抛由 respond 收口）
+					await persistReport(verifyReportsDirOf(env), name, report);
+					return report;
+				});
+			},
+			// GET /api/_platform/solutions/verify/last?name= —— 取该方案最新深检报告（登录即可，只读）。
+			last: {
+				async get() {
+					if (!http.user?.id) {
+						json.fail(401, "unauthorized");
+						return;
+					}
+					await respond(async () => {
+						const name = verifyNameOf();
+						const report = await getLastReport(verifyReportsDirOf(env), name);
+						if (report === null)
+							throw Object.assign(new Error(`方案「${name}」暂无深检报告`), { status: 404 });
+						return report;
+					});
+				},
+			},
+		},
+	};
+}
+
+export default createSolutionsApi(solutionsEnv());

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

@@ -0,0 +1,5 @@
+name: demo
+desc: 演示模块（todos 等，P3 接数据层）
+version: 0.1.0
+tables:
+  - todos

package/templates/api/src/demo/migrations/0001__create_todos.sql

@@ -0,0 +1,9 @@
+-- demo 模块建表（P3-2）。todos 待办表，S007 要求序号连续且唯一，单文件 0001。
+-- done 用 INTEGER(0/1) 承载布尔，handler 映射为 boolean。
+CREATE TABLE IF NOT EXISTS todos (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  title TEXT NOT NULL DEFAULT '',
+  done INTEGER NOT NULL DEFAULT 0,
+  create_time INTEGER NOT NULL DEFAULT 0,
+  update_time INTEGER NOT NULL DEFAULT 0
+);

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

@@ -0,0 +1,11 @@
+# 声明式表结构（§4.2 / D1-C）：demo 模块自有表 todos。
+# 加表/加可空列由 reconcile 自动收敛；类型变更/改名走 migrations/。
+tables:
+  todos:
+    pk: id
+    columns:
+      id: {type: integer, autoincrement: true}
+      title: {type: text, null: false}
+      done: {type: integer, null: false}
+      create_time: {type: integer, null: false}
+      update_time: {type: integer, null: false}

package/templates/api/src/demo/seed.sql

@@ -0,0 +1,5 @@
+-- demo 模块种子（P3-2）：示例待办，幂等 INSERT OR IGNORE，按分号朴素切分（S006）。
+INSERT OR IGNORE INTO todos (id, title, done, create_time, update_time) VALUES (1, '学习 uni-dev 契约机制', 1, 0, 0);
+INSERT OR IGNORE INTO todos (id, title, done, create_time, update_time) VALUES (2, '完成 playground-oj system 模块', 0, 0, 0);
+INSERT OR IGNORE INTO todos (id, title, done, create_time, update_time) VALUES (3, '编写 P3 教学文档', 0, 0, 0);
+INSERT OR IGNORE INTO todos (id, title, done, create_time, update_time) VALUES (4, '联调 demo 真实数据层', 0, 0, 0);

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

@@ -0,0 +1,59 @@
+// GET /api/demo/todos —— 演示待办列表（真实化 P3-2，AC-D9 apiPrefix=/demo）。
+// Bearer 守卫保护；keyword 模糊过滤 title；snake_case → camelCase，done 映射布尔。
+
+// 契约（v0.1.71「最新方式」）：动词挂 `.schema` 四通道（params/query/body/response），
+// oj 运行期据此校验入参、并供 `oj openapi` 生成 openapi.json → 前端 `ojm api` 生成 __client。
+const todos = {
+	async get() {
+		const kw = http.query.keyword;
+		const where = kw ? "WHERE title LIKE ?" : "";
+		const params = kw ? [`%${kw}%`] : [];
+		try {
+			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 list = rows.map(r => ({
+				id: Number(r.id),
+				title: String(r.title),
+				done: Number(r.done) === 1,
+			}));
+			json.ok({ list, total });
+		}
+		catch (e) {
+			json.fail(500, String(e));
+		}
+	},
+};
+
+todos.get.schema = {
+	query: {
+		type: "object",
+		properties: { keyword: { type: "string" } },
+	},
+};
+
+// oj v0.1.72 起出参走平级 .response（.schema 只放入参）。
+todos.get.response = {
+	type: "object",
+	required: ["list", "total"],
+	properties: {
+		list: {
+			type: "array",
+			items: {
+				type: "object",
+				required: ["id", "title", "done"],
+				properties: {
+					id: { type: "number" },
+					title: { type: "string" },
+					done: { type: "boolean" },
+				},
+			},
+		},
+		total: { type: "number" },
+	},
+};
+
+export default todos;

package/templates/api/src/home/line/api.ts

@@ -0,0 +1,57 @@
+// POST /api/home/line —— 首页折线（真实化 P4-1，AC-D9 apiPrefix=/home）。
+// 窗口聚合 home_line：range(week/month/year) → 天数；在 [today-N+1, today] 内
+// 逐日取 SUM(value)，缺失日补 0（F6 幂等补数）。返回 number[]（与日序对齐）。
+const RANGE_DAYS: Record<string, number> = { week: 7, month: 30, year: 365 };
+
+// 契约（v0.1.71「最新方式」）：动词挂 `.schema` 四通道。
+const line = {
+	async post() {
+		try {
+			const range = String((http.body && (http.body as Record<string, unknown>).range) ?? "week");
+			const days = RANGE_DAYS[range] ?? 7;
+			const today = Math.floor(Date.now() / 86400000);
+			const start = today - days + 1;
+
+			const rows = await db.query(
+				"SELECT day, SUM(value) AS v FROM home_line WHERE day >= ? AND day <= ? GROUP BY day",
+				[start, today],
+			);
+			const map = new Map<number, number>();
+			for (const r of rows)
+				map.set(Number(r.day), Number(r.v));
+
+			let out: number[] = Array.from({ length: today - start + 1 }, (_, i) => {
+				const d = start + i;
+				return map.get(d) ?? 0;
+			});
+
+			// 懒补数（F6）：窗口内完全无 seed（seed 随时间变旧）时，回落确定式趋势，
+			// 保证图表非空；有 seed 时仅对缺失日补 0（上面 ?? 0 已处理）。
+			if (out.every(v => v === 0)) {
+				out = Array.from({ length: today - start + 1 }, (_, i) => {
+					const d = start + i;
+					return 50 + Math.round(40 * Math.sin(d / 3)) + (d % 7) * 3;
+				});
+			}
+			json.ok(out);
+		}
+		catch (e) {
+			json.fail(500, String(e));
+		}
+	},
+};
+
+line.post.schema = {
+	body: {
+		type: "object",
+		required: ["range"],
+		properties: { range: { type: "string" } },
+	},
+};
+
+line.post.response = {
+	type: "array",
+	items: { type: "number" },
+};
+
+export default line;

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

@@ -0,0 +1,6 @@
+name: home
+desc: 首页图表模块（pie/line，P4 接数据层）
+version: 0.1.0
+tables:
+  - home_pie
+  - home_line

package/templates/api/src/home/migrations/0001__create_home_tables.sql

@@ -0,0 +1,13 @@
+-- home 模块建表（P4-1）。home_pie 五分类聚合源；home_line 日窗口时间序列。
+-- S007 要求序号连续且唯一，两表并入单文件 0001。day 用 epoch-day 整数便于窗口算术。
+CREATE TABLE IF NOT EXISTS home_pie (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  category TEXT NOT NULL DEFAULT '',
+  value INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS home_line (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  day INTEGER NOT NULL DEFAULT 0,
+  value INTEGER NOT NULL DEFAULT 0
+);

package/templates/api/src/home/pie/api.ts

@@ -0,0 +1,40 @@
+// GET /api/home/pie —— 首页饼图（真实化 P4-1，AC-D9 apiPrefix=/home）。
+// 按 category 聚合 home_pie，返回 {code,value} 数组（对齐契约 pieData）。
+
+// 契约（oj v0.1.72「最新方式」）：入参挂 `.schema`，出参挂平级 `.response`；
+// union 用类型数组表达（见 by）。
+const pie = {
+	async get() {
+		try {
+			const rows = await db.query(
+				"SELECT category, SUM(value) AS v FROM home_pie GROUP BY category",
+				[],
+			);
+			json.ok(rows.map(r => ({ code: String(r.category), value: Number(r.v) })));
+		}
+		catch (e) {
+			json.fail(500, String(e));
+		}
+	},
+};
+
+pie.get.schema = {
+	query: {
+		type: "object",
+		properties: { by: { type: ["string", "number"] } },
+	},
+};
+
+pie.get.response = {
+	type: "array",
+	items: {
+		type: "object",
+		required: ["value", "code"],
+		properties: {
+			value: { type: "number" },
+			code: { type: "string" },
+		},
+	},
+};
+
+export default pie;

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

@@ -0,0 +1,14 @@
+# 声明式表结构（§4.2 / D1-C）：home 模块自有表 home_pie / home_line。
+tables:
+  home_pie:
+    pk: id
+    columns:
+      id: {type: integer, autoincrement: true}
+      category: {type: text, null: false}
+      value: {type: integer, null: false}
+  home_line:
+    pk: id
+    columns:
+      id: {type: integer, autoincrement: true}
+      day: {type: integer, null: false}
+      value: {type: integer, null: false}