# 体检项逐字定义（Mac 侧草案 v0，供两端冻结）

状态：**草案，未实施**。依 `patches/COORDINATION_CHECKLIST_20260916.md` §二「体检项定义须逐字冻结后再各自实现」而提。
对方标准原文（`RESEARCH_FREEZE_AND_DATA_STANDARD_20260916.md` L49）：**「新增行数、交易日连续性、复权因子非空、文件非半写状态；四项任一不过即停止当日执行并上报」** —— 原文只给名目，无阈值，故本节补齐**可判定的操作定义**。请对方逐条回「同意 / 改 X」后再各自实现。

统一前提（两端须一致）：
- 目标交易日记 `T`（= 增量拉数当日），池集合 = {hs300, zz500, zz1000, zz2000}，列集合 `COLS` = price-schema-v1 12 列。
- 体检**在增量写盘之后、扫描之前**执行；判定结果落 `patches/health_gate_<date>.md`（含四项指标原始值，不只结论）。
- 三态：`PASS` / `WARN`（记录并继续）/ `BLOCK`（停止当日执行并上报）。

## H1 新增行数

- **指标**：`upd_ratio = N(末行 trade_date == T 的文件数) / N(池内文件数)`，四池分别算并给全库值。
- **阈值**：`upd_ratio ≥ 0.95` → PASS；`0.90 ≤ upd_ratio < 0.95` → WARN；`< 0.90` → BLOCK。
- **附带硬指标**：增量**拒写计数 > 0** → BLOCK（拒写=显式失败，不是统计噪声）。
- 依据与例外：停牌股当日无行情属正常，故不要求 100%；实测正常日 5325/5400 = 98.6%（拒写 0）。

## H2 交易日连续性

- **H2a（文件内）**：每文件 `trade_date` 序列须**严格递增、无重复**；`trade_date ⊆ 交易日历`（日历取指数基准同日序列，或 tushare `trade_cal`）。
  - 违规 → BLOCK（重复/倒序/日历外日期均视为写坏）。
- **H2b（库级）**：每池**末行日期众数** == `T`；且 `T` 必须晚于上一交易日的末行日期众数（否则为「未推进」）→ 违反 BLOCK。
- **停牌缺口不判**：文件内两行之间缺交易日属停牌，**不违规**（故不做「逐日必须齐」的判定，避免把正常停牌判成错）。

## H3 复权因子非空

- **H3a**：新增行（trade_date == T）`adj_factor` 必须存在、非 NaN、`> 0`；任一违规 → BLOCK。
- **H3b**：新增行 12 列**无任一 NaN** → 违反 BLOCK（含 pre_close/change/pct_chg/vol/amount）。
- **H3c**：因子来源三级回退统计：`用当日全市场因子` / `用末行隐含因子` / `拒写`。第三项 > 0 → 已在 H1 记 BLOCK；第二项命中数 **> 当日除权股数**（除权股由因子表跳变识别）→ WARN（降级可见但不静默）。

## H4 文件非半写状态

- **H4a**：每池内文件**可完整解析**：`read_csv` 成功、列集合 == `COLS`（12 列，按名比对）、末行无 NaN、文件以换行结尾 → 任一不满足 BLOCK。
- **H4b**：**写入单调性**：体检前后文件字节数不得减少（增量只追加）；末行 `trade_date` 不得回退 → 违反 BLOCK。
- **H4c**：**写入窗口标记**：若文件 `mtime` 落在本次增量写盘窗口内且 H4a 未通过，判为「写入中被读」→ 重试一次再判，仍不过即 BLOCK（避免竞态误报）。

## 警告期与翻阻塞

- 依裁决：**先警告后阻塞**。警告期语义 = 触发 BLOCK 条件时**只落 WARN + 记录原始值 + 继续执行**，但在 `patches/health_gate_<date>.md` 标 `WOULD_BLOCK`。
- 翻阻塞条件（提请冻结）：**同一侧连续 3 个交易日无 `WOULD_BLOCK`** 即翻为阻塞；**两端须同日翻**（避免一侧严一侧宽）。翻日由 Owner 指定。
- 误报登记格式：`日期 | 项 | 文件/池 | 原始值 | 阈值 | 是否误报(是否需改阈值)`。

## 待对方确认

1. 上述四项定义与阈值逐条「同意/改」；
2. 交易日历取数源统一（建议：指数基准 000300.SH 同日序列，两端已有，避免引入新接口）；
3. 翻阻塞的 3 日观察窗与同日翻是否接受；
4. 体检产物文件命名 `patches/health_gate_<date>.md` 是否对齐（我方需按名取）。