docs(plans): add Spec-3 question-gen-v2 implementation plan

9 tasks: type extension → postprocess → families → sampler_v2 → generator_v2 → gates → run_store → pipeline_v2 → CLI integration. Includes structured-logging schemas/metrics and Codex review revisions.
2026-07-11 22:57:47 -04:00
parent 8c9adfd3fa
commit 043d4aa46f
10 changed files with 964 additions and 3 deletions
@@ -0,0 +1,58 @@
+---
+type: schema
+node_id: schema:question-gen-runs
+title: "表结构: question_gen_runs（出题批次）"
+date: 2026-07-12
+---
+
+# 表结构: question_gen_runs（出题批次）
+
+出题管线 v2 的批次级运行记录。每次 `tools/generate_questions.py generate` 执行产生一行。
+
+## 列定义
+
+| 列名 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `run_id` | TEXT | PK | 生成批次唯一 ID（UUID） |
+| `git_sha` | TEXT | NOT NULL | 代码版本（HEAD commit） |
+| `config_snapshot` | TEXT | | 科研配置 YAML 快照（JSON 序列化） |
+| `started_at` | TEXT | NOT NULL | ISO8601 开始时间 |
+| `finished_at` | TEXT | | ISO8601 结束时间（运行中为 NULL） |
+| `status` | TEXT | NOT NULL | running / completed / failed |
+| `total_slots` | INTEGER | | 目标题数（默认 240） |
+| `accepted` | INTEGER | | 过门题数 |
+| `rejected` | INTEGER | | 最终拒绝题数 |
+| `heavy_sampled` | INTEGER | | 重量抽检题数 |
+
+## DDL
+
+```sql
+CREATE TABLE IF NOT EXISTS question_gen_runs (
+    run_id        TEXT PRIMARY KEY,
+    git_sha       TEXT NOT NULL,
+    config_snapshot TEXT,
+    started_at    TEXT NOT NULL,
+    finished_at   TEXT,
+    status        TEXT NOT NULL DEFAULT 'running',
+    total_slots   INTEGER,
+    accepted      INTEGER,
+    rejected      INTEGER,
+    heavy_sampled INTEGER
+);
+```
+
+## 埋点位置
+
+| 代码位置 | 动作 | 时机 |
+|---------|------|------|
+| `tools/generate_questions.py::generate` 入口 | INSERT（status=running） | 批次开始 |
+| `tools/generate_questions.py::generate` 结尾 | UPDATE（finished_at/status/统计汇总） | 批次结束 |
+
+## 查询模式
+
+```sql
+-- 最近一次成功运行
+SELECT * FROM question_gen_runs WHERE status='completed' ORDER BY started_at DESC LIMIT 1;
+-- 产能统计
+SELECT accepted, rejected, heavy_sampled, total_slots FROM question_gen_runs WHERE run_id=?;
+```