candidate-pool 2.0.0

package/db/d1client.js

@@ -0,0 +1,69 @@
+'use strict';
+// Cloudflare D1 HTTP API 客户端（供本机脚本 / CI 写入，非 Workers 内调用）
+// 凭据来源（优先级从高到低）：
+//   1) 真实环境变量 CF_ACCOUNT_ID / CF_D1_DATABASE_ID / CF_API_TOKEN（CI Secrets / 系统环境变量）
+//   2) db/.env —— 由 dotenv 加载，默认**不覆盖**上面已存在的值
+// 仅在真正写入时才校验凭据；dry-run 不调用本模块。
+const path = require('path');
+const paths = require('../paths');
+// 凭据文件跟随工作目录（见 paths.js）：默认 <仓库根>/db/.env
+require('dotenv').config({ path: paths.dbEnvFile(), quiet: true });
+
+function cfg() {
+  const ACCOUNT_ID = process.env.CF_ACCOUNT_ID;
+  const DB_ID = process.env.CF_D1_DATABASE_ID;
+  const TOKEN = process.env.CF_API_TOKEN;
+  if (!ACCOUNT_ID || !DB_ID || !TOKEN) return null;
+  return { ACCOUNT_ID, DB_ID, TOKEN };
+}
+exports.cfg = cfg;
+
+function endpoint() {
+  const c = cfg();
+  if (!c) throw new Error('缺少 Cloudflare 凭据：请设置 CF_ACCOUNT_ID / CF_D1_DATABASE_ID / CF_API_TOKEN');
+  return c;
+}
+
+async function post(path, body) {
+  const c = endpoint();
+  const res = await fetch(`https://api.cloudflare.com/client/v4/accounts/${c.ACCOUNT_ID}/d1/database/${c.DB_ID}${path}`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${c.TOKEN}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  const j = await res.json();
+  if (!j.success) throw new Error('CF D1 API 错误: ' + JSON.stringify(j.errors || j.messages || j));
+  return j.result;
+}
+
+// 单条语句（DDL / 查询 / 单插）
+async function exec(sql) {
+  const r = await post('/query', { sql });
+  return (r && r[0]) ? r[0] : r;
+}
+// 单条查询，返回结果数组
+async function query(sql, params = []) {
+  const r = await post('/query', { sql, params });
+  return (r && r[0] && r[0].results) || [];
+}
+// 批量语句（每条语句形如 { sql, params }）
+// 说明：Cloudflare D1 的 /execute 路由在本账号/数据库稳定返回 404 "Route not found"，
+// 而 /query 的批量 { statements:[...] } 入参也被拒绝（要求单个 sql）。
+// 因此改为走 /query 逐条提交 { sql, params }（与 query() 同一可用路径），
+// 以有界并发（CONC）提交，避免串行过慢、又不过度压测 API 限流。
+const BATCH_CONC = 10;
+async function batch(statements) {
+  const out = [];
+  for (let i = 0; i < statements.length; i += BATCH_CONC) {
+    const slice = statements.slice(i, i + BATCH_CONC);
+    const results = await Promise.all(slice.map(s =>
+      post('/query', { sql: s.sql, params: s.params || [] })
+    ));
+    results.forEach(r => { if (Array.isArray(r)) out.push(...r); });
+  }
+  return out;
+}
+
+exports.exec = exec;
+exports.query = query;
+exports.batch = batch;

package/db/ddl.js

@@ -0,0 +1,82 @@
+'use strict';
+/*
+ * db/ddl.js —— DDL 的唯一读取入口（schema.sql 是唯一真相源）
+ * ---------------------------------------------------------------------------
+ * 背景（2026-09-21 事故）：
+ *   同一份建表语句曾被复制到 3 个地方 —— db/schema.sql、
+ *   eod/lib/store_d1.js::ensureTables、db/persist.js::ensureColumns，彼此没有约束关系。
+ *   而两条「自动应用」路径都是坏的：
+ *     · 本地：db/sqlite_client.js 只在【缺 run_batch 表】时才应用 schema。
+ *       库一旦早已存在，后来新增的 tail_run / tail_pick 就永远不会被创建。
+ *     · 远程：压根没有自动应用路径，只靠人工 `wrangler d1 execute`。
+ *   结果：local.db 与线上 D1 都没有尾盘两张表 → /api/tail/* 全部
+ *   `no such table` → 被 onError 兜成 HTTP 500（四个页面全挂）。
+ *
+ * 现在的约定：
+ *   1. schema.sql 只写「最终想要的形状」，全部 IF NOT EXISTS，**可重复执行**；
+ *   2. 任何需要建表/建索引的地方都从这里取语句，不再各写一份；
+ *   3. 需要「改已存在的表」（SQLite 的 CREATE TABLE IF NOT EXISTS 不会补列）时，
+ *      写成 db/migrations/NNN-描述.sql，由 db/migrate.js 按文件名顺序执行一次并记录。
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA_FILE = path.join(__dirname, 'schema.sql');
+const MIGRATIONS_DIR = path.join(__dirname, 'migrations');
+
+/**
+ * 把 SQL 文本切成单条语句。
+ * - 去掉 `--` 注释（本项目 schema.sql 大量使用行尾内联注释，需一并清掉）；
+ * - 按 `;` 切分；本项目 DDL 不含「字符串字面量里带分号」的情况，故简单切分足够。
+ *
+ * 必须切分的原因：Cloudflare D1 的 /query 路由只接受**单条**语句。
+ *
+ * @param {string} sql
+ * @returns {string[]}
+ */
+function splitStatements(sql) {
+  return String(sql)
+    .split(/\r?\n/)
+    .map((line) => line.replace(/--.*$/, ''))
+    .join('\n')
+    .split(';')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/** schema.sql 的原始文本（用于计算 hash / 判断是否变化）。 */
+function readSchema() {
+  return fs.readFileSync(SCHEMA_FILE, 'utf8');
+}
+
+/** schema.sql 切分后的语句数组（建表 + 建索引，全部幂等）。 */
+function loadStatements() {
+  return splitStatements(readSchema());
+}
+
+/**
+ * 增量迁移文件（db/migrations/NNN-*.sql），按文件名升序。
+ * 目录不存在时返回空数组（本项目当前没有需要 ALTER 的变更）。
+ * @returns {Array<{name: string, statements: string[]}>}
+ */
+function loadMigrations() {
+  if (!fs.existsSync(MIGRATIONS_DIR)) return [];
+  return fs
+    .readdirSync(MIGRATIONS_DIR)
+    .filter((f) => f.endsWith('.sql'))
+    .sort()
+    .map((name) => ({
+      name,
+      statements: splitStatements(fs.readFileSync(path.join(MIGRATIONS_DIR, name), 'utf8')),
+    }));
+}
+
+module.exports = {
+  SCHEMA_FILE,
+  MIGRATIONS_DIR,
+  splitStatements,
+  readSchema,
+  loadStatements,
+  loadMigrations,
+};

package/db/diff.js

@@ -0,0 +1,223 @@
+'use strict';
+/*
+ * db/diff.js —— 结构差异识别（声明式：期望结构 vs 库中实际结构）
+ * ---------------------------------------------------------------------------
+ * 为什么需要它：
+ *   db/migrate.js 若只是把 schema.sql 整份重放，`CREATE TABLE IF NOT EXISTS`
+ *   对【已存在的表】是空操作 —— 也就是**新增字段永远不会生效**，只有「新建整表」才生效。
+ *   而「给老表加字段」恰恰是最常见的结构变更（本项目已手工加过 run_at / vol_ratio）。
+ *
+ * 于是把「识别」与「执行」分开：
+ *   本文件只做**纯函数**解析与比对（不碰数据库，可单测）；
+ *   由 db/migrate.js 决定怎么执行、以及哪些差异必须人工写迁移文件。
+ *
+ * 能自动处理的（安全、可逆性无要求）：
+ *   - 期望里有、库里没有的【表】      → CREATE TABLE
+ *   - 期望里有、库里没有的【列】      → ALTER TABLE ... ADD COLUMN（受 SQLite 限制，见 unsafeReason）
+ *   - 期望里有、库里没有的【索引】    → CREATE INDEX
+ *
+ * 只识别、不擅自执行的（必须人工写 db/migrations/NNN-*.sql）：
+ *   - 列定义变了（改类型 / 改约束）    → SQLite 不支持直接改，需重建表
+ *   - 列被删 / 表被删                  → 涉及数据丢弃，必须人工确认
+ *   - 不满足 ALTER 限制的新列          → 见 unsafeReason 的返回原因
+ */
+
+const { splitStatements } = require('./ddl');
+
+/** D1 内部表（如 _cf_KV）与 sqlite 内部表不参与比对，避免每次运行都刷警告。 */
+const INTERNAL_TABLE = /^(sqlite_|_cf_)/i;
+
+/** 取「从 openIdx 处的左括号」到匹配右括号之间的内容。 */
+function extractParenBody(sql, openIdx) {
+  let depth = 0;
+  for (let i = openIdx; i < sql.length; i++) {
+    const ch = sql[i];
+    if (ch === '(') depth++;
+    else if (ch === ')') {
+      depth--;
+      if (depth === 0) return sql.slice(openIdx + 1, i);
+    }
+  }
+  return sql.slice(openIdx + 1);
+}
+
+/** 按「顶层逗号」切分（跳过括号内的逗号，如 PRIMARY KEY (a, b)）。 */
+function splitTopLevel(body) {
+  const out = [];
+  let depth = 0;
+  let cur = '';
+  for (const ch of body) {
+    if (ch === '(') depth++;
+    else if (ch === ')') depth--;
+    if (ch === ',' && depth === 0) {
+      out.push(cur);
+      cur = '';
+      continue;
+    }
+    cur += ch;
+  }
+  if (cur.trim()) out.push(cur);
+  return out;
+}
+
+/** 归一化用于比对（忽略空白与大小写的差异）。 */
+function normalize(s) {
+  return String(s).replace(/\s+/g, ' ').trim().toUpperCase();
+}
+
+/**
+ * 标识符：`foo` / "foo" / [foo] / foo 四种写法都要认。
+ * 为什么必须处理：`sqlite_master.sql` 存的是**建表原文**，若某侧建表时带了引号
+ * （wrangler / D1 控制台 / 手工执行的 DDL 常有），而解析规则只认裸标识符，
+ * 结果会是「列被静默丢弃」→ 误判为缺列 → ALTER 报 duplicate column name。
+ * 带上引号消除这个隐患，两侧写法不同也能正确比对。
+ */
+const IDENT = `(?:["\`\\[]([^"\`\\]]+)["\`\\]]|([A-Za-z_]\\w*))`;
+
+/** 从 IDENT 的匹配结果里取名字（去掉引号）。 */
+function identName(m, offset) {
+  return m[offset + 1] != null ? m[offset + 1] : m[offset + 2];
+}
+
+/** 该列定义能否用 `ALTER TABLE ADD COLUMN` 安全追加；不能则给出原因。 */
+function unsafeReason(def) {
+  const d = normalize(def);
+  if (/PRIMARY\s+KEY/.test(d)) return '主键列无法用 ALTER TABLE 追加';
+  if (/\bUNIQUE\b/.test(d)) return 'UNIQUE 列无法用 ALTER TABLE 追加';
+  if (/AUTOINCREMENT/.test(d)) return 'AUTOINCREMENT 无法用 ALTER TABLE 追加';
+  if (/\bNOT\s+NULL\b/.test(d) && !/\bDEFAULT\b/.test(d)) return 'NOT NULL 却没有 DEFAULT，既有行无法补值';
+  return null;
+}
+
+function parseTableBody(body) {
+  const columns = new Map();
+  const constraints = [];
+  for (const raw of splitTopLevel(body)) {
+    const part = raw.trim();
+    if (!part) continue;
+    // 表级约束（PRIMARY KEY / UNIQUE / FOREIGN KEY / CHECK / CONSTRAINT ...）不是列
+    if (/^(PRIMARY\s+KEY|UNIQUE|FOREIGN\s+KEY|CHECK|CONSTRAINT)\b/i.test(part)) {
+      constraints.push(normalize(part));
+      continue;
+    }
+    const m = new RegExp(`^${IDENT}\\s+([\\s\\S]+)$`).exec(part);
+    if (m) columns.set(identName(m, 0), m[3].trim());
+  }
+  return { columns, constraints };
+}
+
+/**
+ * 解析 DDL 文本 → { tables, indexes }。
+ * 只识别 CREATE TABLE / CREATE INDEX（本项目 DDL 仅用这两类）。
+ * @param {string} sqlText schema.sql 全文，或 sqlite_master.sql 拼接而成的文本
+ */
+function parseObjects(sqlText) {
+  const tables = new Map();
+  const indexes = new Map();
+  for (const stmt of splitStatements(sqlText)) {
+    const t = new RegExp(
+      `^\\s*CREATE\\s+TABLE\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?${IDENT}\\s*\\(`,
+      'i',
+    ).exec(stmt);
+    if (t) {
+      const name = identName(t, 0);
+      const body = extractParenBody(stmt, t.index + t[0].length - 1);
+      tables.set(name, { name, ddl: stmt, ...parseTableBody(body) });
+      continue;
+    }
+    const i = new RegExp(
+      `^\\s*CREATE\\s+(?:UNIQUE\\s+)?INDEX\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?${IDENT}\\s+ON\\s+${IDENT}`,
+      'i',
+    ).exec(stmt);
+    if (i) {
+      const iname = identName(i, 0);
+      indexes.set(iname, { name: iname, table: identName(i, 2), ddl: stmt });
+    }
+  }
+  return { tables, indexes };
+}
+
+/**
+ * 比对期望结构与实际结构。
+ * @returns {{addTables: Array, addColumns: Array, unsafeColumns: Array,
+ *            changedColumns: Array, addIndexes: Array,
+ *            droppedTables: string[], droppedColumns: Array}}
+ */
+function diffSchema(desired, actual) {
+  const addTables = [];
+  const addColumns = [];
+  const unsafeColumns = [];
+  const changedColumns = [];
+  const addIndexes = [];
+  const droppedTables = [];
+  const droppedColumns = [];
+
+  for (const [tname, dt] of desired.tables) {
+    const at = actual.tables.get(tname);
+    if (!at) {
+      addTables.push({ table: tname, ddl: dt.ddl });
+      continue;
+    }
+    for (const [cname, cdef] of dt.columns) {
+      const acdef = at.columns.get(cname);
+      if (acdef === undefined) {
+        const reason = unsafeReason(cdef);
+        (reason ? unsafeColumns : addColumns).push({ table: tname, column: cname, def: cdef, reason });
+      } else if (normalize(cdef) !== normalize(acdef)) {
+        changedColumns.push({ table: tname, column: cname, desired: cdef, actual: acdef });
+      }
+    }
+    for (const cname of at.columns.keys()) {
+      if (!dt.columns.has(cname)) droppedColumns.push({ table: tname, column: cname });
+    }
+  }
+
+  for (const tname of actual.tables.keys()) {
+    if (!desired.tables.has(tname) && !INTERNAL_TABLE.test(tname)) droppedTables.push(tname);
+  }
+  for (const [iname, di] of desired.indexes) {
+    if (!actual.indexes.has(iname)) addIndexes.push(di);
+  }
+
+  return { addTables, addColumns, unsafeColumns, changedColumns, addIndexes, droppedTables, droppedColumns };
+}
+
+/** 差异是否为空（用于判断「结构已经是最新」）。 */
+function isEmptyDiff(d) {
+  return (
+    d.addTables.length === 0 &&
+    d.addColumns.length === 0 &&
+    d.addIndexes.length === 0 &&
+    d.unsafeColumns.length === 0 &&
+    d.changedColumns.length === 0 &&
+    d.droppedTables.length === 0 &&
+    d.droppedColumns.length === 0
+  );
+}
+
+/**
+ * 差异 → 可执行 DDL（纯函数，不碰数据库）。
+ * migrate.js 与 db/diff_selftest.js 共用这一份，保证「测的」就是「跑的」。
+ * 只输出安全项；unsafeColumns / changedColumns / dropped* 一律不在此处执行。
+ * @returns {string[]}
+ */
+function applyStatements(d) {
+  const stmts = [];
+  for (const t of d.addTables) stmts.push(t.ddl);
+  for (const c of d.addColumns) {
+    stmts.push(`ALTER TABLE ${c.table} ADD COLUMN ${c.column} ${c.def}`);
+  }
+  for (const i of d.addIndexes) stmts.push(i.ddl);
+  return stmts;
+}
+
+module.exports = {
+  parseObjects,
+  diffSchema,
+  isEmptyDiff,
+  applyStatements,
+  unsafeReason,
+  normalize,
+  splitTopLevel,
+  INTERNAL_TABLE,
+};

package/db/diff_selftest.js

@@ -0,0 +1,124 @@
+'use strict';
+/*
+ * db/diff_selftest.js —— 结构同步的自测（零依赖，node db/diff_selftest.js）
+ * ---------------------------------------------------------------------------
+ * 为什么必须有：2026-09-21 的事故本质是「结构同步**静默失效**」——本地永不建新表、
+ * 远程靠人工执行，两边都不报错，直到接口 500 才被发现。所以「新增字段能否被识别」
+ * 这类能力不能只靠一次人工试验，得有可重跑的回归保护。
+ *
+ * 覆盖：新增列（可自动 / 不可自动）、新增索引、新增表、删列只报告不执行、
+ *       引号标识符、幂等性（跑第二遍必须零差异）。
+ * 退出码非 0 表示失败。
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const diffLib = require('./diff');
+const { createClient } = require('./sqlite_client');
+
+let failed = 0;
+function check(name, cond, detail) {
+  console.log(`${cond ? '  OK  ' : '  FAIL'} ${name}${cond || detail === undefined ? '' : `  → ${detail}`}`);
+  if (!cond) failed++;
+}
+const names = (arr) => arr.map((x) => x.table + '.' + x.column).sort();
+
+// 期望结构：demo 表比库中现状多出 4 列，其中 2 列可自动追加、2 列不允许
+const DESIRED = `
+CREATE TABLE IF NOT EXISTS demo (
+  id TEXT NOT NULL PRIMARY KEY,
+  a  TEXT,
+  b  REAL,
+  c  TEXT NOT NULL,
+  d  TEXT UNIQUE,
+  e  TEXT NOT NULL DEFAULT 'z'
+);
+CREATE INDEX IF NOT EXISTS idx_demo_a ON demo (a);
+`;
+
+// 库里现状：旧版 demo（无 b/c/d/e）+ 一个 schema 里已删除的列 legacy_col
+const LEGACY = `
+CREATE TABLE legacy_tbl (x TEXT);
+CREATE TABLE demo (id TEXT NOT NULL PRIMARY KEY, a TEXT, legacy_col TEXT);
+INSERT INTO demo (id, a, legacy_col) VALUES ('1', 'hello', 'old');
+`;
+
+(async () => {
+  const file = path.join(os.tmpdir(), `cp-diff-selftest-${process.pid}.db`);
+  const client = createClient(file);
+  const readActual = async () => {
+    // 与 db/migrate.js::readActual 等价的读结构逻辑
+    const t = await client.query("SELECT name, sql FROM sqlite_master WHERE type='table' AND sql IS NOT NULL");
+    const i = await client.query("SELECT name, sql FROM sqlite_master WHERE type='index' AND sql IS NOT NULL");
+    return diffLib.parseObjects([...t, ...i].map((r) => `${r.sql};`).join('\n'));
+  };
+
+  try {
+    await client.exec(LEGACY);
+
+    console.log('\n[1] 差异识别：新增列 / 不可自动列 / 新增索引 / 删列');
+    const desired = diffLib.parseObjects(DESIRED);
+    const d1 = diffLib.diffSchema(desired, await readActual());
+    check('可自动新增列 = demo.b, demo.e', JSON.stringify(names(d1.addColumns)) === JSON.stringify(['demo.b', 'demo.e']), JSON.stringify(names(d1.addColumns)));
+    check('不可自动新增列 = demo.c, demo.d', JSON.stringify(names(d1.unsafeColumns)) === JSON.stringify(['demo.c', 'demo.d']), JSON.stringify(names(d1.unsafeColumns)));
+    check('新增索引 = idx_demo_a', d1.addIndexes.length === 1 && d1.addIndexes[0].name === 'idx_demo_a', JSON.stringify(d1.addIndexes.map((x) => x.name)));
+    check('删列只报告不执行 = demo.legacy_col', d1.droppedColumns.length === 1 && d1.droppedColumns[0].column === 'legacy_col', JSON.stringify(names(d1.droppedColumns)));
+    check('不给「不允许的列」生成 DDL', !diffLib.applyStatements(d1).some((s) => /ADD COLUMN (c|d)\b/.test(s)));
+    check('不给删列生成 DDL', !diffLib.applyStatements(d1).some((s) => /DROP/i.test(s)));
+
+    console.log('\n[2] 执行差异：DDL 真的能跑通，且存量行不被破坏');
+    const stmts = diffLib.applyStatements(d1);
+    await client.batch(stmts.map((sql) => ({ sql })));
+    const cols = (await client.query('PRAGMA table_info(demo)')).map((r) => r.name);
+    check('demo 现含 b/e', cols.includes('b') && cols.includes('e'), cols.join(','));
+    const row = (await client.query("SELECT * FROM demo WHERE id='1'"))[0];
+    check('存量行 a 保留', row && row.a === 'hello', JSON.stringify(row));
+    check('存量行 b 补空值', row && row.b === null, JSON.stringify(row && row.b));
+    check("新列 e 取默认值 'z'", row && row.e === 'z', JSON.stringify(row && row.e));
+    const idx = (await client.query("SELECT name FROM sqlite_master WHERE type='index' AND name='idx_demo_a'")).length;
+    check('索引已建', idx === 1, String(idx));
+
+    console.log('\n[3] 幂等性：再比一次必须只剩「不可自动」与「删列」');
+    const d2 = diffLib.diffSchema(desired, await readActual());
+    check('无新增表/列/索引', d2.addTables.length === 0 && d2.addColumns.length === 0 && d2.addIndexes.length === 0, JSON.stringify({ t: d2.addTables.length, c: d2.addColumns.length, i: d2.addIndexes.length }));
+    check('DDL 为空（可安全重复跑）', diffLib.applyStatements(d2).length === 0, JSON.stringify(diffLib.applyStatements(d2)));
+
+    console.log('\n[4] 健壮性：引号/反引号/方括号标识符 & 大小写/空白差异不误报');
+    const quoted = diffLib.parseObjects(`
+      create table if not exists "demo" (
+        "id" text not null primary key,
+        \`a\`  TEXT,
+        [b]    REAL,
+        c      TEXT NOT NULL,
+        d      TEXT UNIQUE,
+        e      TEXT NOT NULL DEFAULT 'z'
+      );
+      CREATE INDEX IF NOT EXISTS "idx_demo_a" ON "demo" ("a");
+    `);
+    const d3 = diffLib.diffSchema(quoted, await readActual());
+    check('引号写法解析出 6 列', quoted.tables.get('demo') && quoted.tables.get('demo').columns.size === 6, quoted.tables.get('demo') && quoted.tables.get('demo').columns.size);
+    check('引号/大小写差异不误报为缺列', d3.addColumns.length === 0 && d3.changedColumns.length === 0, JSON.stringify({ add: names(d3.addColumns), chg: names(d3.changedColumns) }));
+
+    console.log('\n[5] 新增整表');
+    const withNew = diffLib.parseObjects(DESIRED + '\nCREATE TABLE IF NOT EXISTS brand_new (k TEXT PRIMARY KEY, v TEXT);');
+    const d4 = diffLib.diffSchema(withNew, await readActual());
+    check('识别出 brand_new', d4.addTables.length === 1 && d4.addTables[0].table === 'brand_new', JSON.stringify(d4.addTables.map((x) => x.table)));
+    await client.batch(diffLib.applyStatements(d4).map((sql) => ({ sql })));
+    check('brand_new 已建', (await client.query("SELECT name FROM sqlite_master WHERE type='table' AND name='brand_new'")).length === 1);
+    // 注意：demo.legacy_col 是「只报告不执行」的删列项，故第二遍不会 isEmptyDiff 全空；
+    // 这里断言的是「可执行项已归零」——即重复运行不会产生任何 DDL。
+    const d5 = diffLib.diffSchema(withNew, await readActual());
+    check('第二遍无可执行项（DDL 为空）', diffLib.applyStatements(d5).length === 0, JSON.stringify(diffLib.applyStatements(d5)));
+    check('第二遍仅剩已声明的人工项（删列）', d5.droppedColumns.length === 1 && d5.unsafeColumns.length === 2, JSON.stringify({ drop: names(d5.droppedColumns), unsafe: names(d5.unsafeColumns) }));
+  } finally {
+    client.close();
+    try { fs.unlinkSync(file); } catch (_) {}
+  }
+
+  console.log(failed ? `\n自我检查失败：${failed} 项` : '\n全部通过');
+  process.exit(failed ? 1 : 0);
+})().catch((e) => {
+  console.error('[致命]', (e && e.stack) || e);
+  process.exit(1);
+});

package/db/enrich_stock_base.js

@@ -0,0 +1,138 @@
+'use strict';
+// 股票档案补全：从东方财富 F10 公开接口低频抓取
+//   题材概念 / 地域 / 主营业务 / 最赚钱业务，写入 stock_base（仅填缺失字段）。
+// 用法：
+//   node db/enrich_stock_base.js                 # 补全所有 concepts/region/main_business 为空的票
+//   node db/enrich_stock_base.js --test sh600519 # 打印单只原始响应，便于校准字段路径
+//   node db/enrich_stock_base.js --all           # 强制覆盖已存在的字段
+// 注意：东方财富 F10 端点可能随版本调整，若字段取不到，用 --test 看原始 JSON 后微调下方解析。
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const d1 = require('./d1client');
+const localSqlite = require('./sqlite_client');
+const { now: fmtNow } = require('../time');
+
+const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36';
+const REF = 'https://emweb.securities.eastmoney.com/';
+
+function emCode(code) {
+  const m = String(code).toLowerCase().match(/^(sh|sz|bj)(\d{6})$/);
+  if (!m) return null;
+  return m[1].toUpperCase() + m[2];
+}
+
+function getJSON(url, tries = 3) {
+  return new Promise(async (resolve, reject) => {
+    let last;
+    for (let i = 0; i < tries; i++) {
+      if (i) await new Promise(r => setTimeout(r, 800 * i));
+      try {
+        const buf = await new Promise((res, rej) => {
+          https.get(url, { headers: { 'User-Agent': UA, 'Referer': REF } }, r => {
+            const cs = []; r.on('data', c => cs.push(c)); r.on('end', () => res(Buffer.concat(cs)));
+          }).on('error', rej).on('timeout', () => rej(new Error('timeout')));
+        });
+        return resolve(JSON.parse(buf.toString('utf8')));
+      } catch (e) { last = e; }
+    }
+    reject(last);
+  });
+}
+
+// 取公司概况：主营业务 + 地域（省份）
+async function companySurvey(em) {
+  const url = `https://emweb.securities.eastmoney.com/PC_HSF10/CompanySurvey/PageAjax?code=${em}`;
+  const j = await getJSON(url);
+  const R = j && (j.Result || (Array.isArray(j) && j[0] && j[0].Result));
+  if (!R) return {};
+  const r = Array.isArray(R) ? R[0] : R;
+  return { mainBusiness: r.MainBusiness || r.mainBusiness || '', region: r.Province || r.province || '' };
+}
+
+// 取主营构成：按毛利率挑「最赚钱业务」
+async function operationsRequired(em) {
+  const url = `https://emweb.securities.eastmoney.com/PC_HSF10/OperationsRequired/PageAjax?code=${em}`;
+  const j = await getJSON(url);
+  const R = j && (j.Result || (Array.isArray(j) && j[0] && j[0].Result));
+  if (!R) return {};
+  const main = (R.MainOp || R.mainOp || []);
+  if (!main.length) return {};
+  let best = null;
+  for (const it of main) {
+    const gm = parseFloat(it.GROSS_MARGIN != null ? it.GROSS_MARGIN : it.grossMargin);
+    if (!isNaN(gm) && (!best || gm > best.gm)) best = { gm, name: it.ITEM_NAME || it.itemName, prop: it.PROPORTION != null ? it.PROPORTION : it.proportion };
+  }
+  if (!best) return {};
+  return { topBusiness: `${best.name}（毛利率 ${Number(best.gm).toFixed(1)}%${best.prop != null ? `，营收占比 ${Number(best.prop).toFixed(1)}%` : ''}）` };
+}
+
+// 取题材概念
+async function concepts(em) {
+  const url = `https://emweb.securities.eastmoney.com/PC_HSF10/BusinessAnalysis/PageAjax?code=${em}`;
+  const j = await getJSON(url);
+  const R = j && (j.Result || (Array.isArray(j) && j[0] && j[0].Result));
+  if (!R) return {};
+  const arr = R.Concept || R.concept || R.THSConcept || [];
+  const list = (Array.isArray(arr) ? arr : []).map(x => x.TITLE || x.title || x.ZTMC || x.conceptName).filter(Boolean);
+  if (list.length) return { concepts: list.join('、') };
+  // 兜底：一些版本把概念放在 HYSYL（行业）或核心题材字段
+  const core = R.CoreConcept || R.coreConcept;
+  if (Array.isArray(core)) return { concepts: core.map(x => x.TITLE || x.title).filter(Boolean).join('、') };
+  return {};
+}
+
+async function enrichOne(code) {
+  const em = emCode(code);
+  if (!em) return {};
+  const [cs, op, cp] = await Promise.allSettled([companySurvey(em), operationsRequired(em), concepts(em)]);
+  return {
+    mainBusiness: (cs.status === 'fulfilled' ? cs.value.mainBusiness : '') || '',
+    region: (cs.status === 'fulfilled' ? cs.value.region : '') || '',
+    topBusiness: (op.status === 'fulfilled' ? op.value.topBusiness : '') || '',
+    concepts: (cp.status === 'fulfilled' ? cp.value.concepts : '') || '',
+  };
+}
+
+(async () => {
+  const test = process.argv.includes('--test');
+  const all = process.argv.includes('--all');
+  const isLocal = process.argv.includes('--local');
+  const codeArg = (process.argv.find(a => a.startsWith('--code=')) || '').split('=')[1];
+  const client = isLocal ? localSqlite.createClient() : d1;
+  if (isLocal) console.log(`[enrich] 本地 SQLite 模式 -> ${client.file}`);
+
+  if (test && codeArg) {
+    const r = await enrichOne(codeArg);
+    console.log(JSON.stringify(r, null, 2));
+    if (client.close) client.close();
+    return;
+  }
+
+  const rows = codeArg
+    ? [{ code: codeArg }]
+    : await client.query(`SELECT code FROM stock_base WHERE ${all ? '1=1' : "concepts IS NULL OR region IS NULL OR main_business IS NULL"}`);
+  const codes = rows.map(r => r.code);
+  console.log(`待补全 ${codes.length} 只${all ? '（强制覆盖）' : ''}`);
+
+  let ok = 0, skip = 0;
+  for (const code of codes) {
+    try {
+      const r = await enrichOne(code);
+      const has = r.concepts || r.region || r.mainBusiness || r.topBusiness;
+      if (!has) { skip++; console.log(`  · ${code}: 接口无数据，跳过`); continue; }
+      if (test) { console.log(code, JSON.stringify(r)); continue; }
+      await client.query(
+        'UPDATE stock_base SET concepts=COALESCE(NULLIF(?,""),concepts), region=COALESCE(NULLIF(?,""),region), main_business=COALESCE(NULLIF(?,""),main_business), top_business=COALESCE(NULLIF(?,""),top_business), updated_at=? WHERE code=?',
+        [r.concepts, r.region, r.mainBusiness, r.topBusiness, fmtNow(), code]
+      );
+      ok++;
+      console.log(`  ✓ ${code} 概念=${r.concepts || '-'} 地域=${r.region || '-'} 主营=${r.mainBusiness || '-'} 最赚=${r.topBusiness || '-'}`);
+    } catch (e) {
+      console.log(`  ✗ ${code}: ${e.message}`);
+    }
+    if (!test) await new Promise(r => setTimeout(r, 250)); // 低频，避免触发东财限流
+  }
+  if (client.close) client.close();
+  console.log(`[enrich] 完成：更新 ${ok} 跳过 ${skip}`);
+})().catch(e => { console.error('[enrich] 中止:', e.message); process.exit(1); });