candidate-pool 2.0.0

package/eod/lib/screen.js

@@ -0,0 +1,355 @@
+'use strict';
+/*
+ * eod/lib/screen.js —— 初筛过滤 → 分时校验 → 强度打分 → 分组排序
+ * ---------------------------------------------------------------------------
+ * 口径要点（尾盘口径 ≠ 现有 R01 隔夜口径，两套独立，不要互相套用）：
+ *
+ *   1. 初筛（FR-03）只依赖快照字段，因此可以先在全市场 6000+ 只上跑一遍，
+ *      把「不可买 / 明显不合格」的先剔掉，再对少数幸存者抓分时（否则请求量爆炸）。
+ *   2. 「不可买」判定必须覆盖三件事，实测缺一不可：
+ *        - 停牌/退市：成交量 0 或 行情时间戳停在 09:00:00
+ *          （已退市个股仍会返回陈旧价格，只看价格会把它们放进来）
+ *        - 一字板：开=高=低（全天一个价，实盘买不到）
+ *        - 已封涨停：现价达到该板块涨停价（主板 10% / 双创 20% / 北交所 30%）
+ *   3. 打分（FR-06）六项全部线性映射到 0..1 再加权，**每一项都能在报告里解释**，
+ *      不做「黑箱总分」。任何一项缺数据记 0 分而不是猜值。
+ *   4. 分组（FR-07）按行业聚合，组内按总分降序，标记组内最优。
+ * ---------------------------------------------------------------------------
+ */
+
+const { dayjs } = require('../../time');
+const { sectorOf, listedOf, computeSectorStats, UNKNOWN } = require('./sector');
+
+/** 筛除原因（中文，直接进报告与日志） */
+const REASON = {
+  ST: 'ST / 退市风险股',
+  SUSPENDED: '停牌或已退市（无成交）',
+  NO_DATA: '关键字段缺失或分时数据不可用',
+  CHG: '当日涨幅不在区间',
+  VOL_RATIO: '量比不足',
+  TURNOVER: '换手率不在区间',
+  CAP: '流通市值不在区间',
+  PRICE: '股价过低',
+  ONE_WORD: '一字板（实际上买不到）',
+  LIMIT_UP: '已封涨停（实际上买不到）',
+  NEW: '上市时间过短',
+  TAIL_SEG: '尾盘段涨幅不足',
+  BELOW_AVG: '现价低于当日均价',
+  FROM_HIGH: '距日内高点回落过多',
+};
+
+/** 板块判定：涨跌幅制度与成交量单位都与板块相关 */
+function boardOf(code) {
+  if (/^sh68[89]/.test(code)) return 'star';   // 科创板
+  if (/^sz30/.test(code)) return 'gem';        // 创业板
+  if (/^bj/.test(code)) return 'bj';           // 北交所
+  return 'main';                               // 沪深主板
+}
+
+/** 该板块的涨停幅度（%）。ST 已在上游剔除，故不必再处理 5% 档 */
+function limitUpPct(code) {
+  const b = boardOf(code);
+  if (b === 'star' || b === 'gem') return 20;
+  if (b === 'bj') return 30;
+  return 10;
+}
+
+const BOARD_LABEL = { main: '主板', star: '科创板', gem: '创业板', bj: '北交所' };
+
+/** 两个 YYYYMMDD / YYYY-MM-DD 之间相差的自然日；任一无法解析返回 null */
+function daysBetween(a, b) {
+  const da = dayjs.tz(String(a).replace(/^(\d{4})(\d{2})(\d{2})$/, '$1-$2-$3') + ' 00:00:00');
+  const db = dayjs.tz(String(b).slice(0, 10) + ' 00:00:00');
+  if (!da.isValid() || !db.isValid()) return null;
+  return Math.abs(db.diff(da, 'day'));
+}
+
+/**
+ * 单只票的快照初筛。返回 null = 通过；返回字符串 = 淘汰原因。
+ * 顺序有意从「便宜且决定性」到「贵」，便于统计各原因淘汰量。
+ */
+function preFilterOne(q, cfg, map, tradeDate) {
+  const ex = cfg.exclude;
+  const f = cfg.filter;
+
+  if (ex.st && /ST|退/i.test(q.name)) return REASON.ST;
+
+  if (ex.suspended) {
+    const hhmmss = String(q.stamp || '').slice(8, 14);
+    if (!(q.vol > 0) || hhmmss === '090000') return REASON.SUSPENDED;
+  }
+
+  if (q.chgPct == null || q.turnover == null || q.volRatio == null || q.floatCapYi == null || q.high == null) {
+    return REASON.NO_DATA;
+  }
+  if (q.chgPct < f.chgPctMin || q.chgPct > f.chgPctMax) return REASON.CHG;
+  if (q.volRatio < f.volRatioMin) return REASON.VOL_RATIO;
+  if (q.turnover < f.turnoverMin || q.turnover > f.turnoverMax) return REASON.TURNOVER;
+  if (q.floatCapYi < f.floatCapMinYi || q.floatCapYi > f.floatCapMaxYi) return REASON.CAP;
+  if (q.price < f.priceMin) return REASON.PRICE;
+
+  if (ex.oneWordBoard && q.open != null && q.high != null && q.low != null
+      && q.open === q.high && q.high === q.low) {
+    return REASON.ONE_WORD;
+  }
+
+  if (ex.limitUp && q.prevClose > 0) {
+    const limitPrice = Math.round(q.prevClose * (1 + limitUpPct(q.code) / 100) * 100) / 100;
+    if (q.price >= limitPrice - 0.005) return REASON.LIMIT_UP;
+  }
+
+  if (ex.newListing) {
+    // 交易所对新股简称为「N 开头（首日）/ C 开头（上市后 5 日内）」
+    if (/^[NC]/.test(q.name)) return REASON.NEW;
+    const listed = listedOf(map, q.code);
+    if (listed && tradeDate) {
+      const days = daysBetween(listed, tradeDate);
+      if (days != null && days < ex.newListingDays) return REASON.NEW;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 全市场初筛。
+ * @returns {{passed:Array, rejected:Array<{code,name,reason}>, byReason:object}}
+ */
+function preFilter(quotes, cfg, map, tradeDate) {
+  const passed = [];
+  const rejected = [];
+  const byReason = {};
+  for (const q of quotes) {
+    const reason = preFilterOne(q, cfg, map, tradeDate);
+    if (reason) {
+      byReason[reason] = (byReason[reason] || 0) + 1;
+      rejected.push({ code: q.code, name: q.name, reason });
+    } else {
+      passed.push(q);
+    }
+  }
+  return { passed, rejected, byReason };
+}
+
+/** 分时校验（FR-04）。返回原因数组，空数组 = 通过 */
+function postCheck(q, tm, cfg) {
+  const f = cfg.filter;
+  if (!tm) return [REASON.NO_DATA];
+  const out = [];
+  if (tm.segPct == null || tm.segPct < f.tailSegMinPct) out.push(REASON.TAIL_SEG);
+  if (f.aboveAvgMode === 'hard') {
+    if (tm.priceVsAvgPct == null) out.push(REASON.NO_DATA);
+    else if (tm.priceVsAvgPct < -Math.abs(f.aboveAvgTolerance || 0)) out.push(REASON.BELOW_AVG);
+  }
+  if (q.high > 0 && tm.p1 != null) {
+    const fromHigh = ((q.high - tm.p1) / q.high) * 100;
+    if (fromHigh > f.maxFromHighPct) out.push(REASON.FROM_HIGH);
+  }
+  return out;
+}
+
+function clamp01(v) { return Math.max(0, Math.min(1, v)); }
+
+/** 线性映射到 0..1；v 为空返回 0（缺数据不猜值） */
+function lin(v, lo, hi) {
+  if (v == null || !Number.isFinite(v)) return 0;
+  if (hi === lo) return v >= hi ? 1 : 0;
+  return clamp01((v - lo) / (hi - lo));
+}
+
+/**
+ * 换手适中度：落在 [sweetLow, sweetHigh] 拿满分，
+ * 低于 sweetLow 按 [filterMin, sweetLow] 递减，高于 sweetHigh 按 [sweetHigh, filterMax] 递减。
+ * 这样「过低无人气」与「过高警惕出货」两端都平滑扣分，而不是一刀切。
+ */
+function turnoverFit(t, s, f) {
+  if (t == null || !Number.isFinite(t)) return 0;
+  if (t >= s.turnoverSweetLow && t <= s.turnoverSweetHigh) return 1;
+  if (t < s.turnoverSweetLow) return clamp01((t - f.turnoverMin) / (s.turnoverSweetLow - f.turnoverMin));
+  return clamp01((f.turnoverMax - t) / (f.turnoverMax - s.turnoverSweetHigh));
+}
+
+/**
+ * 板块强度（实测后定的混合口径）。
+ *
+ * 只用「行业涨幅中位数的绝对阈值」会在普涨日整体饱和——实测 2026-09-18
+ * 全市场 68.7% 个股上涨，多数行业中位数都超过 2%，导致候选清一色拿满分、该项失去区分度。
+ * 只用「分位」则会在普跌日把「跌得最少的行业」也抬到满分，同样失真。
+ * 故取两者折中：
+ *   1. 行业中位数 ≤ sectorChgLoPct（默认 0%）→ 0 分：行业实际在跌，不给板块加分；
+ *   2. 行业中位数 ≥ sectorChgHiPct（默认 2%）→ 满分：绝对强度已足够；
+ *   3. 区间内 → 按该行业在全市场行业涨幅中的**分位**给分（相对强弱，自归一）。
+ */
+function sectorStrength(sec, s) {
+  if (!sec || sec.median == null) return 0;
+  if (sec.median <= s.sectorChgLoPct) return 0;
+  if (sec.median >= s.sectorChgHiPct) return 1;
+  if (!sec.total || sec.total <= 1) return 0;
+  const pct = (sec.total - sec.rank) / (sec.total - 1);   // rank=1 → 1，最末 → 0
+  return clamp01(pct);
+}
+
+/** 「距日内高点」百分比：越小越强 */
+function fromHighPct(q, tm) {
+  if (!(q.high > 0) || tm == null || tm.p1 == null) return null;
+  return ((q.high - tm.p1) / q.high) * 100;
+}
+
+/**
+ * 六项打分（FR-06）。总分 = Σ(权重 × 归一化值)。
+ * @returns {{total:number, items:object, ctx:object}} items 为各项得分（已乘权重）
+ */
+function scoreStock(q, tm, cfg, sectorStats, sector) {
+  const w = cfg.score.weights;
+  const s = cfg.score;
+  const f = cfg.filter;
+
+  const fh = fromHighPct(q, tm);
+  const sec = sectorStats.get(sector || UNKNOWN);
+
+  const items = {
+    // 尾盘动能：段涨幅 0 → 0 分，达到 tailMomentumFullPct → 满分
+    tailMomentum: w.tailMomentum * lin(tm.segPct, 0, s.tailMomentumFullPct),
+    // 量能：量比从门槛起到 volRatioFull 线性给分
+    volume: w.volume * lin(q.volRatio, f.volRatioMin, s.volRatioFull),
+    // 位置：距日内高点 0% → 满分，达到 maxFromHighPct → 0 分
+    position: w.position * (1 - lin(fh, 0, f.maxFromHighPct)),
+    // 均价线强度：高出均价 0% → 0 分，avgLineFullPct → 满分
+    avgLine: w.avgLine * lin(tm.priceVsAvgPct, 0, s.avgLineFullPct),
+    // 板块强度：见 sectorStrength() 的口径说明
+    sector: w.sector * sectorStrength(sec, s),
+    // 换手适中度
+    turnoverFit: w.turnoverFit * turnoverFit(q.turnover, s, f),
+  };
+
+  const total = Object.values(items).reduce((a, b) => a + b, 0);
+  return { items, total, context: { fromHighPct: fh, sectorMedian: sec ? sec.median : null } };
+}
+
+/**
+ * 分组 + 组内排序（FR-07）。
+ * 组间按「组内最高总分」降序，组内按总分降序，组内第一名标 bestInGroup。
+ */
+function groupAndRank(candidates, cfg) {
+  const bySector = new Map();
+  for (const c of candidates) {
+    const k = c.sector || UNKNOWN;
+    if (!bySector.has(k)) bySector.set(k, []);
+    bySector.get(k).push(c);
+  }
+
+  const groups = [];
+  for (const [sector, list] of bySector) {
+    list.sort((a, b) => (b.total - a.total) || ((b.tail?.segPct ?? -99) - (a.tail?.segPct ?? -99)));
+    list.forEach((c, i) => {
+      c.groupRank = i + 1;
+      c.bestInGroup = i === 0;
+      c.groupSize = list.length;
+    });
+    groups.push({
+      sector,
+      size: list.length,
+      // 展示用：同组内只留前 N 只，避免推一堆同质票（Q12）
+      shown: list.slice(0, Math.max(1, cfg.group.maxPerGroup)),
+      best: list[0],
+    });
+  }
+  groups.sort((a, b) => b.best.total - a.best.total);
+  return groups;
+}
+
+/**
+ * 主入口：快照 + 分时 -> 候选、分组、TOP。
+ *
+ * @param {Array} quotes        全市场快照
+ * @param {Map}   minutes       code -> { rows, date } | { error }
+ * @param {object} cfg          配置
+ * @param {object} map          行业映射
+ * @param {string} tradeDate    'YYYY-MM-DD'
+ * @param {string} cutHHMM      '1450'（或观察模式下的当前时点）
+ * @param {string} segFrom      '1430'
+ * @param {(code:string)=>object|null} makeTail 由 rows 计算 tailMetrics 的函数（注入以便复用/测试）
+ */
+function buildCandidates({ quotes, minutes, cfg, map, tradeDate, cutHHMM, segFrom, makeTail }) {
+  const pre = preFilter(quotes, cfg, map, tradeDate);
+  const sectorStats = computeSectorStats(pre.passed, map);
+
+  const candidates = [];
+  const dropped = [];
+  const tailReasons = {};
+
+  for (const q of pre.passed) {
+    const m = minutes.get(q.code);
+    if (!m || m.error) {
+      tailReasons[REASON.NO_DATA] = (tailReasons[REASON.NO_DATA] || 0) + 1;
+      dropped.push({ code: q.code, name: q.name, reason: REASON.NO_DATA });
+      continue;
+    }
+    const tm = makeTail(m.rows, q.code, cutHHMM, segFrom);
+    const reasons = postCheck(q, tm, cfg);
+    if (reasons.length) {
+      for (const r of reasons) tailReasons[r] = (tailReasons[r] || 0) + 1;
+      dropped.push({ code: q.code, name: q.name, reason: reasons.join('、') });
+      continue;
+    }
+
+    const sector = sectorOf(map, q.code) || UNKNOWN;
+    const sc = scoreStock(q, tm, cfg, sectorStats, sector);
+    const sec = sectorStats.get(sector);
+
+    candidates.push({
+      code: q.code,
+      name: q.name,
+      sector,
+      board: boardOf(q.code),
+      boardLabel: BOARD_LABEL[boardOf(q.code)],
+      price: q.price,
+      prevClose: q.prevClose,
+      open: q.open,
+      high: q.high,
+      low: q.low,
+      chgPct: q.chgPct,
+      turnover: q.turnover,
+      volRatio: q.volRatio,
+      // 收盘预估量比：即时量比按已交易分钟外推，量能非匀速，仅作参考
+      volRatioEst: null,
+      floatCapYi: q.floatCapYi,
+      totalCapYi: q.totalCapYi,
+      avgPrice: tm.avgAtCut,
+      stamp: q.stamp,
+      tail: tm,
+      score: sc.items,
+      total: sc.total,
+      scoreContext: sc.context,
+      sectorMedianChg: sec ? sec.median : null,
+      sectorRank: sec ? sec.rank : null,
+      sectorTotal: sec ? sec.total : null,
+      sectorMemberCount: sec ? sec.count : null,
+    });
+  }
+
+  candidates.sort((a, b) => b.total - a.total);
+  const groups = groupAndRank(candidates, cfg);
+
+  return {
+    candidates,
+    groups,
+    top: candidates.slice(0, Math.max(1, cfg.group.topN)),
+    stats: {
+      snapshotCount: quotes.length,
+      prePassCount: pre.passed.length,
+      preByReason: pre.byReason,
+      minuteDropped: dropped.length,
+      tailByReason: tailReasons,
+      candidateCount: candidates.length,
+      groupCount: groups.length,
+    },
+    dropped: [...pre.rejected, ...dropped],
+  };
+}
+
+module.exports = {
+  REASON, BOARD_LABEL, boardOf, limitUpPct, daysBetween,
+  preFilterOne, preFilter, postCheck, scoreStock, turnoverFit, fromHighPct, lin,
+  sectorStrength, groupAndRank, buildCandidates,
+};

package/eod/lib/sector.js

@@ -0,0 +1,96 @@
+'use strict';
+/*
+ * eod/lib/sector.js —— 行业归属（代码 -> 行业）缓存读取
+ * ---------------------------------------------------------------------------
+ * 为什么需要缓存：
+ *   全市场「代码 → 行业」的映射有两个来源，都很慢或不稳：
+ *     - 东财 clist 的 f100 字段：一次能拿全市场，但**东财对突发高频请求会封 IP**
+ *       （实测十余次请求后即 socket hang up），不能放进 14:50 的关键路径；
+ *     - 新浪行业分类：只给「行业 → 领涨股」，成员清单要按行业分页拉，请求数上百。
+ *   而行业归属**几乎不变**（一年也就调几次成分），所以做成低频刷新的本地缓存：
+ *   平时读文件（零网络、零延迟），偶尔用 build_industry_map.js 刷一次。
+ *
+ * 缓存结构（eod/data/industry-map.json）：
+ *   { generatedAt, source, count, stocks: { "sh600519": { name, sector, listed } } }
+ * ---------------------------------------------------------------------------
+ */
+
+const fs = require('fs');
+const path = require('path');
+const paths = require('../../paths');
+
+// 缓存位置跟随工作目录（见 paths.js）：默认 <仓库根>/eod/data/industry-map.json
+const UNKNOWN = '未分类';
+
+/** 读取单个映射文件；缺失 / 损坏一律返回空表（不抛错） */
+function readMap(file) {
+  try {
+    const j = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const stocks = j && j.stocks && typeof j.stocks === 'object' ? j.stocks : {};
+    return { generatedAt: j.generatedAt || null, source: j.source || null, count: Object.keys(stocks).length, stocks };
+  } catch (e) {
+    return { generatedAt: null, source: null, count: 0, stocks: {}, error: String((e && e.message) || e) };
+  }
+}
+
+/**
+ * 读取行业映射；文件缺失 / 损坏一律降级（不抛错，让主流程记为「未分类」）。
+ *
+ * 兜底顺序：工作目录 → **包内自带的那份**。
+ * 为什么需要第二级：行业映射虽是「数据」，却是由 refresh-industry-map 工作流生成的
+ * **派生缓存**（一年只变几次），不是用户资产；npm 包把它一起发出去当种子。
+ * 否则 `npx candidate-pool` 在一个空目录里跑，映射读不到 → 全市场塌成单一「未分类」，
+ * 板块内补涨（R07）、板块统计、板块分组会**静默失效**（不报错，只是结果变差）。
+ * 用户若要刷新，`node eod/build_industry_map.js` 会写到工作目录并从此优先。
+ */
+function loadIndustryMap(file = paths.industryMapFile()) {
+  const primary = readMap(file);
+  if (primary.count > 0) return primary;
+
+  const seed = paths.codeAsset('eod', 'data', 'industry-map.json');
+  if (path.resolve(file) === path.resolve(seed)) return primary;
+
+  const fromSeed = readMap(seed);
+  return fromSeed.count > 0 ? { ...fromSeed, seedFallback: true } : primary;
+}
+
+/** 取某只票的行业；查不到返回 null（由调用方决定记为「未分类」还是 data_gap） */
+function sectorOf(map, code) {
+  const s = map && map.stocks ? map.stocks[code] : null;
+  return (s && s.sector) || null;
+}
+
+/** 取某只票的上市日期（YYYYMMDD，可能为 null） */
+function listedOf(map, code) {
+  const s = map && map.stocks ? map.stocks[code] : null;
+  return (s && s.listed) || null;
+}
+
+/**
+ * 按行业统计当日涨幅中位数（板块强度，FR-05）。
+ * 只用快照里**已通过基础有效性**的票参与统计，避免退市/停牌票把中位数带偏。
+ * @returns {Map<string, {sector, median, count, rank, total}>}
+ */
+function computeSectorStats(stocks, map) {
+  const buckets = new Map();
+  for (const q of stocks) {
+    const sec = sectorOf(map, q.code);
+    if (!sec) continue;
+    if (q.chgPct == null) continue;
+    if (!buckets.has(sec)) buckets.set(sec, []);
+    buckets.get(sec).push(q.chgPct);
+  }
+  const rows = [];
+  for (const [sector, arr] of buckets) {
+    const sorted = arr.slice().sort((a, b) => a - b);
+    const mid = sorted.length % 2
+      ? sorted[(sorted.length - 1) / 2]
+      : (sorted[sorted.length / 2 - 1] + sorted[sorted.length / 2]) / 2;
+    rows.push({ sector, median: mid, count: sorted.length });
+  }
+  rows.sort((a, b) => b.median - a.median);
+  rows.forEach((r, i) => { r.rank = i + 1; r.total = rows.length; });
+  return new Map(rows.map((r) => [r.sector, r]));
+}
+
+module.exports = { loadIndustryMap, sectorOf, listedOf, computeSectorStats, mapPath: paths.industryMapFile, UNKNOWN };

package/eod/lib/store.js

@@ -0,0 +1,204 @@
+'use strict';
+/*
+ * eod/lib/store.js —— 幂等落库（FR-10 / FR-11 / Q3）
+ * ---------------------------------------------------------------------------
+ * 约定（与 tail.config.js store 段一致）：
+ *   1. 一个交易日一份正式文件 `eod-<交易日>.json`，**整文件覆盖**：
+ *      文件内 records 以 code 为键，天然不会出现重复记录；
+ *      同日多次运行的历史（几次、各跑出几只候选）记在 runs[] 里留痕，
+ *      最多保留 keepRunHistory 条。
+ *   2. 观察模式（14:30~14:50）另存 `eod-<交易日>-obs.json`，
+ *      不污染正式口径；同一天多次观察互相覆盖（同口径幂等），
+ *      「跑了几次 / 各自什么时点」看 runs[]（文件名带时点的 `-obs<HHMM>` 仅在 --stamp 时用）。
+ *   3. 收盘后回填（P5）写进每条 record 的 `fill` 字段（当日收盘价 / 次日表现），
+ *      重新跑筛选会覆盖 records 但**保留旧 fill**——只要 code 还在候选里。
+ *   4. 全部零依赖：Node 内置 fs/path + 项目 time.js。
+ * ---------------------------------------------------------------------------
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { now: nowBJ } = require('../../time');
+const paths = require('../../paths');
+
+/** 候选对象 -> 存档记录（压缩字段：分时明细不落盘，只留尾盘段汇总） */
+function toRecord(c) {
+  return {
+    code: c.code,
+    name: c.name,
+    sector: c.sector,
+    board: c.board,
+    boardLabel: c.boardLabel,
+    price: c.price,
+    prevClose: c.prevClose,
+    high: c.high,
+    chgPct: c.chgPct,
+    turnover: c.turnover,
+    volRatio: c.volRatio,
+    volRatioEst: c.volRatioEst ?? null,
+    floatCapYi: c.floatCapYi,
+    avgPrice: c.avgPrice,
+    groupRank: c.groupRank,
+    bestInGroup: c.bestInGroup,
+    groupSize: c.groupSize,
+    tail: c.tail ? {
+      segPct: c.tail.segPct,
+      upRatio: c.tail.upRatio,
+      maxDrawdownPct: c.tail.maxDrawdownPct,
+      priceVsAvgPct: c.tail.priceVsAvgPct,
+      avgAtCut: c.tail.avgAtCut,
+      p0: c.tail.p0,
+      p1: c.tail.p1,
+      bars: c.tail.bars,
+      // 实际取数窗口（盘中模式的滚动窗口靠它才可回溯；正式口径固定 1430→1450）
+      segFrom: c.tail.segFromUsed ?? c.tail.segFrom ?? null,
+      cut: c.tail.cut ?? null,
+    } : null,
+    score: c.score,
+    total: c.total,
+    sectorMedianChg: c.sectorMedianChg,
+    sectorRank: c.sectorRank,
+    sectorTotal: c.sectorTotal,
+    // P5 回填位：{ close, next1, next2, next3, filledAt }（收盘后由回填脚本写入）
+    fill: {},
+  };
+}
+
+/**
+ * 文件名后缀（不含扩展名）。
+ *   正式  (cut)      → ''
+ *   观察  (observe)  → '-obs'                       ← **一天一个文件**，多次观察靠 runs[] 留痕
+ *                      '-obs<HHMM>'（stamp=true）
+ *   盘中  (intraday) → '-intraday'                  ← **一天一个文件**，多次运行靠 runs[] 留痕
+ *                      '-intraday<HHMM>-w<分钟>'（stamp=true）
+ *
+ * 观察 / 盘中都默认**一天一个文件、不按时点命名**，理由相同：
+ *   两者的「尾盘段」都是**相对窗口**（观察 = 14:30→当前时点，盘中 = 滚动 segMinutes 分钟），
+ *   不同时刻的结果**本来就不可横向比较**，逐个留档没有复盘价值；而盘中一天可能跑十几次，
+ *   按时点命名会让目录失控（十几个 JSON + 十几个 HTML）。
+ *   真正需要留痕的是「跑了几次、每次什么口径、多少候选」—— 那正是 runs[] 的职责；
+ *   时点也没丢，存档里有 doc.cutAt，D1 侧有 tail_run.cut_at。
+ *   还有一条：D1 对 (trade_date, mode) 是 UPSERT，一个交易日只有一行观察，
+ *   文件名若不跟着「一天一个」，就会出现「磁盘 N 份 vs 库里 1 行」这种两源粒度不一致
+ *   （曾按 `-obs<HHMM>` 命名，副作用是文件名取决于启动分钟，文档 / --replay 无法写死）。
+ * 需要完整保留某一次时显式加 --stamp；stamp 模式下连窗口长度一起写进文件名，
+ * 因为「对比 20 分钟 vs 30 分钟窗口」正是 stamp 的主要用途（同名会互相覆盖）。
+ */
+function daySuffix(mode, cutHHMM, { stamp = false, segMinutes = null } = {}) {
+  if (mode === 'observe') return stamp ? `-obs${cutHHMM}` : '-obs';
+  if (mode === 'intraday') {
+    if (!stamp) return '-intraday';
+    return `-intraday${cutHHMM}${segMinutes ? `-w${segMinutes}` : ''}`;
+  }
+  return '';
+}
+
+/**
+ * 存档文件名（数据 JSON）。
+ *   正式  (cut)      → eod-<日>.json            ← 唯一被 D1 同步 / 复盘引用的口径
+ *   观察  (observe)  → eod-<日>-obs.json        （--stamp 时带时点）
+ *   盘中  (intraday) → eod-<日>-intraday.json   （--stamp 时带时点与窗口）
+ * 观察 / 盘中必须另存：它们的尾盘段不是 14:30→14:50 的固定口径
+ * （观察是 14:30→当前时点，盘中是滚动窗口），若写进正式文件会把当天的正式结果
+ * 覆盖成假的 14:50 口径。
+ */
+function dayFile(cfg, tradeDate, mode, cutHHMM, opts) {
+  return path.join(paths.eodDir(), cfg.store.dataDir, `eod-${tradeDate}${daySuffix(mode, cutHHMM, opts)}.json`);
+}
+
+/** 读取某交易日的正式存档（无则 null） */
+function loadDay(cfg, tradeDate) {
+  const f = dayFile(cfg, tradeDate, 'cut');
+  if (!fs.existsSync(f)) return null;
+  try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch (e) { return null; }
+}
+
+/**
+ * 保存一次运行结果（幂等）。
+ * @param {object} p
+ *   - segFrom    尾盘段起点 'HHMM'（盘中模式会随之滚动，存进 runs[] 才能回溯口径）
+ *   - segMinutes 盘中窗口长度（分钟）；正式/观察为 null
+ *   - stamp      盘中模式下是否在文件名里带上时点（默认 false = 一天一个文件）
+ * @returns {{file:string, recordCount:number, runCount:number, replacedFill:number}}
+ */
+function saveRun({ cfg, tradeDate, mode, cutHHMM, result, runner, segFrom = null, segMinutes = null, stamp = false }) {
+  const dir = path.join(paths.eodDir(), cfg.store.dataDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const file = dayFile(cfg, tradeDate, mode, cutHHMM, { stamp, segMinutes });
+
+  const old = fs.existsSync(file) ? (() => {
+    try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { return null; }
+  })() : null;
+
+  const run = {
+    at: nowBJ(),
+    mode,
+    cutAt: cutHHMM,
+    // 尾盘段起点与窗口长度：正式/观察恒为 1430；盘中是滚动窗口，必须记下来，
+    // 否则事后看 runs[] 只知道「11:20 跑过一次」，不知道那次用的是哪一段。
+    segFrom,
+    segMinutes,
+    candidateCount: result.candidates.length,
+    groupCount: result.groups.length,
+    prePassCount: result.stats.prePassCount,
+    snapshotCount: result.stats.snapshotCount,
+    runner: runner || 'local',
+  };
+
+  // 合并旧 fill：同 code 重选时保留收盘后回填的表现数据
+  const records = {};
+  let replacedFill = 0;
+  const oldRecs = (old && old.records) || {};
+  for (const c of result.candidates) {
+    const rec = toRecord(c);
+    const prev = oldRecs[c.code];
+    if (prev && prev.fill && Object.keys(prev.fill).length) {
+      rec.fill = prev.fill;
+      replacedFill++;
+    }
+    records[c.code] = rec;
+  }
+
+  const runs = [...((old && old.runs) || []), run].slice(-cfg.store.keepRunHistory);
+
+  const doc = {
+    version: cfg.version,
+    tradeDate,
+    mode,
+    cutAt: cutHHMM,
+    updatedAt: nowBJ(),
+    runs,
+    stats: result.stats,
+    records,
+  };
+  fs.writeFileSync(file, JSON.stringify(doc, null, 1), 'utf8');
+  return { file, doc, recordCount: Object.keys(records).length, runCount: runs.length, replacedFill };
+}
+
+/**
+ * 回填（P5）：给指定交易日的正式文件写 fill 字段。
+ * @param {object} patch code -> fill 对象（整体替换该 code 的 fill）
+ * @returns {{updated:number, missing:string[]}} missing = 文件里没有的 code
+ */
+function applyFill(cfg, tradeDate, patch) {
+  const file = dayFile(cfg, tradeDate, 'cut');
+  if (!fs.existsSync(file)) return { updated: 0, missing: Object.keys(patch) };
+  const doc = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const missing = [];
+  let updated = 0;
+  for (const [code, fill] of Object.entries(patch)) {
+    if (doc.records[code]) {
+      doc.records[code].fill = { ...fill, filledAt: nowBJ() };
+      updated++;
+    } else {
+      missing.push(code);
+    }
+  }
+  if (updated) {
+    doc.updatedAt = nowBJ();
+    fs.writeFileSync(file, JSON.stringify(doc, null, 1), 'utf8');
+  }
+  return { updated, missing };
+}
+
+module.exports = { saveRun, loadDay, applyFill, toRecord, dayFile, daySuffix };