simon/ggx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

修复：量价单位 / 未来函数守卫 / 实时画像闸门；行情回补到 2005；手册补全流程

Browse Source 
本轮会话的三项正确性改造（均为「不报错、只让结果静默错」的类型）：

1) 修复 stock_daily 量价单位前后不一致
   - 现象：2015-2019 存 Tushare 原始单位（手/千元），2020 起存（股/元），2019 同日混合；
     而流动性阈值按「元」配置 → 早年门槛实际是「日均成交额 ≥ 200 亿元」，
     把 2015-2019 的股票池整体清空（实测 2016/2017/2018 各选出 0 只）。
   - 修复：写入端 sync/price.py 统一换算；读取端 units.normalize_ohlcv_units
     按行判定并幂等换算（price_history / avg_amount 都走它）；
     审计新增 UNIT-OHLCV 防回归。
   - 效果：2016/2017/2018 的股票池变为 7/11/13 只。

2) 未来函数守卫（单次回测）
   - 股票池自带 asof：若晚于回测起点即**拒绝执行**（原先静默冻结套用），
     与 walk-forward 已有的拒绝理由一致；确需复现加 --allow-lookahead-universe，
     偏差写入 unimplemented_json。

3) 新增实时（PIT）个股画像闸门
   - profile/pit.py：每个决策日按当时可见数据重算过去 5 年画像，
     惰性（仅买入条件已触发的标的）、面板按 asof 缓存、
     规则不含财务指标时不查财报表；被剔除时产出 REJECT + 逐规则留痕。
   - 指标定义复用 ProfileBuilder._profile_one（与批量画像逐值等价的回归测试）。
   - profile/coverage.py：窗口覆盖率（按交易日历的真实开市天数），
     策略新增 entry.profile_gate.min_window_coverage（默认 0，不改变既有行为）。
   - core/metrics.py：闸门可用指标的唯一定义（配置期即校验，避免写错指标名静默失效）。

4) 行情回补到 2005（使 5/8/10 年窗口真正完整）
   - stock_daily / adjust_factor / daily_basic 补到 2005-01-04；
     hd_suspend / hd_limit 补到 2010-01-04。
   - 5 年窗口覆盖率：2018-05-18 由 67.0% → 99.1%，2016-12-30 由 39.8% → 99.0%；
     残差经逐日与 hd_suspend 交叉核实为真实停牌（16/16 命中）。
   - 审计 G2/G3 与断点续传原先用固定阈值（2000 / 1500 只），
     会把 2005-2009 的正常数据误判为异常 —— 改为按「当年应有上市股票数」成比例判定。
   - 节流修正：daily/adj_factor/daily_basic 限频 480 → 170（实测该 token 约 196/min 即被拒）。

5) 自我声明如实化
   - 原先「约束未生效」由「过滤后集合为空」判定，会把「这批股票恰好没停牌」
     误报成「hd_suspend 无数据」；改为按表级判定。
   - 补齐此前静默的「配置承诺但未实现」项：suspended_rule/limit_up_down_rule 的 defer、
     cash_mode=reinvest/reinvest_rule、handle_rights_issue、signal_to_execution、
     max_volume_pct、liquidity_limit_pct_adv —— 全部写入 unimplemented_json。

6) 手册：新增 §0「全流程操作（选股 → 画像 → 回测）」置于最前
   - 逐步说明「命令做了什么、数据从哪来、落了哪些库、有哪些坑」；
     含实时画像闸门 9 问 9 答、未来函数守卫表、成交与成本口径、验证 SQL。
   - 修正旧 §2.4 漏传 --universe-run（选了池子却没用于回测）；
     修正两处声称「停牌顺延」「分红再投资」已实现的相反表述。

测试：403 项全部通过（含新增 test_units.py、test_profile_pit.py、
未实现声明诚实性测试、行序无关性回归测试）。

注意：本提交中 docs/*、README.md、src/hdiv/web/service.py 除本轮修改外，
也含此前遗留的未提交改动（无法按文件切分）。
This commit is contained in:
simon
2026-10-04 12:47:17 +08:00
parent fb6608193b
commit 14ec0c6c86
25 changed files with 4543 additions and 209 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user-guide.md
+673 -41
View File
@@ -7,6 +7,7 @@
# 目录
0. [全流程操作](#0-全流程操作) ★ **先读这一节（选股 → 画像 → 回测）**
1. [系统是什么](#1-系统是什么)
2. [快速开始](#2-快速开始)
3. [目录与架构](#3-目录与架构)
@@ -22,6 +23,288 @@
---
# 0. 全流程操作
> **选股 → 画像 → 回测**，三步主路径。
本节是**主操作路径**：从「选出一批股票」到「跑出一份可信的回测」，
每一步都说明**命令做了什么、数据从哪来、落了哪些库、有哪些坑**。
## 0.0 五分钟全流程（可直接复制）
```bash
cd ~/project/高股息回测
export PYTHONPATH=src
# ① 选股：按 2025-01-01 当时可见的数据筛选（实际落到交易日 2024-12-31）
.venv/bin/python -m hdiv universe --asof 2025-01-01
# → 记下打印的 run_id，例如 02485801b2805cbae0e02db66c7bc946
# ② 画像：对这 46 只看它们在**该时点**的 5/8/10 年画像
.venv/bin/python -m hdiv profile --universe-run 02485801b2805cbae0e02db66c7bc946
# ③ 登记策略（首次需要；之后改 YAML 再 register 即可）
.venv/bin/python -m hdiv strategy register
# ④ 回测：用这个池子，**起点不得早于股票池 asof**
.venv/bin/python -m hdiv backtest \
--universe-run 02485801b2805cbae0e02db66c7bc946 \
--start 2025-01-01
# ⑤ Walk-forward 样本外验证（★ 判断策略好坏的唯一依据）
.venv/bin/python -m hdiv backtest --mode walkforward
# ⑥ 打开前端看结果
.venv/bin/python -m hdiv web # → http://127.0.0.1:8099/
```
> **③④ 的顺序无所谓，②和④互不依赖**（见 §0.3 的「关键认知」）。
> **④ 与 ⑤ 的区别是本质性的**：④ 是「一条路径」，⑤ 是「逐年样本外」。
> 本项目只认 ⑤ —— 详见 §7.5。
---
## 0.1 步骤①：选股 `hdiv universe`
```bash
.venv/bin/python -m hdiv universe --asof 2025-01-01 [--no-persist] [--html]
```
### 发生了什么
```
① asof 归一化 → 2025-01-01 是元旦休市，落到「≤ asof 的最近交易日」= 2024-12-31
② 取候选集 → stock 表中 list_date <= asof 且 (delist_date 为空或 > asof)
即「当时已上市、当时未退市」——**包含此后才退市的股票**（消除生存者偏差）
③ 挂 PIT 面板 → daily_basic（当日或最近 5 个交易日内）、20 日均成交额、
最新已公告财报（ann_date <= asof）、已实施且已除权的分红
④ 依次过 4 个滤网 → market → risk → dividend → quality（先便宜的、淘汰率高的）
每只股票记录：每个滤网的通过位 + **首个未通过的滤网 + 原因 + 取值快照**
⑤ 截断 → 按股息率降序取前 output.max_members（默认 200）只
⑥ 落库 → hd_universe_run（头）+ hd_universe_member（逐股留痕）
```
各滤网的判据（全部来自 `config/universe.yml`，改 YAML 即改行为）：
| 顺序 | 滤网 | 主要判据 |
|---|---|---|
| 1 | `market` | 交易所 ∈ [SSE, SZSE]、板块 ∈ [主板/创业板/科创板]、上市 ≥ 10 年、总市值 ≥ 500 亿、20 日均成交额 ≥ 2,000 万元、当日有行情 |
| 2 | `risk` | 非 ST（按 `stock_name_history` 还原**当时**的名字）、未退市、未停牌、净资产为正、资产负债率 ≤ 80%（银行/保险/证券/信托豁免） |
| 3 | `dividend` | 股息率 ≥ 3%（**自算 PIT-TTM**，非 `dv_ttm`）、连续分红 ≥ 5 年、6 年窗口内至少 5 个分红年、支付率 ≤ 100%、自由现金流为正、FCF 覆盖分红 ≥ 1 倍 |
| 4 | `quality` | 5 年平均 ROE ≥ 8%、经营现金流/净利润 ≥ 0.6（用**年报**而非季报，否则累计值会误杀） |
### 关键性质
1. **无未来函数**：每一条判据都带 `<= asof` 约束（行情 `trade_date`、财报 `ann_date`、
分红 `imp_ann_date` 与 `ex_date` 双重）。ST 状态按历史名称还原，不看今天的名字。
2. **run_id 是确定性的**：由「配置哈希 + asof」决定，**不含时间戳**。
所以同配置同时点重跑会**原地覆盖同一条记录**，不会积累重复。
3. **`asof` 会被归一化到交易日**。`--asof 2025-01-01` 与 `--asof 2024-12-31`
得到**同一个 run_id**。看到打印的 `asof=2024-12-31` 不是 bug。
4. **`--no-persist` 的后果**：结果不落库 → 前端看不到，**也无法被回测引用**。
CLI 会显式提醒。
### 落库与追溯
| 表 | 内容 |
|---|---|
| `hd_universe_run` | run_id / asof_date / 候选数 / 入选数 / 配置指纹 / 数据版本 |
| `hd_universe_member` | 逐股：每个滤网通过位、`fail_stage`（首个未通过滤网）、`fail_reason`（中文原因）、取值快照 |
> **「为什么没选上」是这个模块最重要的产出。** 前端「股票池」页可逐股下钻。
---
## 0.2 步骤②：画像 `hdiv profile`
```bash
# 对某个股票池的全部成员，按**该股票池的 asof** 画像
.venv/bin/python -m hdiv profile --universe-run <run_id>
# 指定股票 + 指定时点（任意历史时点，PIT）
.venv/bin/python -m hdiv profile --symbols 600036.SH 000651.SZ --asof 2018-05-18
```
### 发生了什么
```
① 确定对象与时点 → --universe-run 时 asof 取该池的 asof_date；--asof 可显式覆盖
② 取数 → 起点 = asof.year − max(windows_years) − 1 的 1 月 1 日，终点 = asof
价格（不复权）、daily_basic（PE/PB/PS）、分红、年报财务、指数
③ 逐股逐指标统计 → 每个指标 × 每个窗口 [全历史, 5, 8, 10] 年：
n_obs、min/max/mean/median/std、P10/P25/P50/P75/P90、
当前值、**当前值在该窗口分布中的分位**
④ 分红质量 → 连续分红年数、DPS 增速与波动、支付率、FCF 覆盖
（与「股票池筛选」共用同一套口径函数）
⑤ 安全边际评分 → 5 个分项（股息率/估值/财务质量/资产负债表/分红质量）
+ 全项齐备时才给 composite 综合分
⑥ 覆盖率自检 → 窗口实际观测数 ÷ 该窗口应有交易日数；不足则打印警告
⑦ 落库 → hd_profile_run / hd_profile_stat / hd_profile_series / hd_profile_score
```
### 输出解读
| 字段 | 含义 |
|---|---|
| `n_obs` | 该窗口内的实际观测数（**注意分位就是在这 n 个观测上算的**） |
| `current_value` | asof 当天的值（取窗口内**最后一个观测**） |
| `current_percentile` | 当前值在窗口分布中的分位（`≤ 当前值的观测占比`） |
| `status` | `OK` / `INSUFFICIENT`（样本不足，**不猜、不用 0 填充**） |
| 窗口覆盖率 | 1.0 = 名义 5 年真有 5 年数据；< 1 说明被数据起点截短 |
CLI 会打印覆盖率，例如：
```
画像 <run_id>：46 只
窗口覆盖率：最差 10 年窗口 94.6%（1.0 = 名义窗口被完整覆盖）
```
### 关键认知（最容易误解的一点）
> **画像是一次「快照」，回测并不读它。**
>
> 回测里每次买入前用的画像，是引擎**在该决策日实时重算**的
> （见 §0.3 第④步），与这里落库的快照是**两条独立路径**。
> 两者由「逐值等价测试」约束，不会给出两个不同的数。
>
> 所以：**画像页是给你看的，不是给回测用的。** 回测每天自己算。
---
## 0.3 步骤③：回测 `hdiv backtest`
```bash
# 冻结股票池（推荐用于「我看好这批票」的场景）—— 起点不得早于股票池 asof
.venv/bin/python -m hdiv backtest --universe-run <run_id> --start 2025-01-01
# 不冻结：引擎在每个调仓日按当时可见数据重新筛选（判断策略本身用这个）
.venv/bin/python -m hdiv backtest --start 2015-01-01
```
### 发生了什么（逐日事件循环）
```
① 确定区间 → 交易日历取 [start, end]，默认取 config/backtest.yml 的 period
② 重建股票池 → --universe-run：守卫校验 asof ≤ 回测首个交易日，然后**冻结**该清单，
所有调仓日复用（每 12 个月不再重筛）
否则：每 universe_refresh_months=12 个月的调仓日，调 selector.run(asof=当日)
—— 用的是**当时可见**的数据（PIT）
③ 预载面板 → 价格（不复权）、分红事件、停牌、涨跌停、指数
若闸门启用：另按最长窗口预载画像面板
④ 逐日循环 ↓
④a 开盘 → 执行**昨日**收盘产生的信号，成交价 = 次日开盘价 ± 滑点
④b 盘中 → 除权除息：现金分红入账（按持股期限扣红利税）、送转股增加股数
④c 收盘 → 每月一次评估信号（signal_frequency_months=1）：
· 算当日股息率 = TTM 每股分红 ÷ 不复权收盘价
· 算历史分位 = 当前值在「(当日−5年, 当日]」分布中的占比
· 分位 ≥ entry.yield_percentile(75) → 买入候选（阶梯定目标仓位）
· 分位 ≤ exit.yield_percentile(25) → 卖出候选
· **买入候选再过「实时画像闸门」**（见下）
④d 收盘 → 盯市：总市值 = 现金 + 持仓 × 不复权收盘价 → 净值曲线
⑤ 绩效与对账 → 收益/CAGR/回撤/Sharpe/Sortino/Calmar、逐年收益、
**资金恒等式残差**（应为 0）
⑥ 落库 → hd_backtest_run / _equity / _position / _trade / _signal / _metric
```
### ④c 的「实时画像闸门」（★ 你关心的那件事）
| 问题 | 答案 |
|---|---|
| 会实时算画像吗？ | **会**。每个决策日、对**已触发买入条件**的标的，按当时可见数据重算过去 5 年画像 |
| 用哪一天的画像？ | **该决策日自己的**。2025-03-31 用 (2020-03-31, 2025-03-31]，不是「2025-01-01 那天」的 |
| 每只股票每天都算吗？ | **不是**。惰性：只有股息率分位 ≥ P75 已触发的才去算 |
| 算全量指标吗？ | 算 `_profile_one` 的全部指标，但**只加载规则声明用到的面板**（纯估值规则不查财报表） |
| 管卖出吗？ | **不管**。卖出/减仓只看股息率分位 |
| 决定仓位大小吗？ | **不决定**。`weight_scheme: score` 未实现，仓位由分位阶梯决定 |
| 不通过会怎样？ | 产出信号类型 `REJECT` + `skip_reason=PROFILE_GATE`，**不成交**；前端「未成交信号」可逐条看每条规则的实际值/阈值/是否通过 |
| 数据缺失/样本不足？ | 按 `on_unverifiable`（默认 `reject`）保守处理 —— **不猜** |
| 关掉它？ | `entry.profile_gate.enabled: false`，整条链路不参与，行为回到改造前 |
配置与规则详见 §4.3「实时画像闸门」。
### 未来函数守卫（会拒绝执行的情况）
| 情形 | 行为 |
|---|---|
| `--universe-run` 且**股票池 asof > 回测首个交易日** | **拒绝执行**，退出码 1，错误信息给出三种正确做法 |
| `--universe-run` 用在 `--mode walkforward` | **拒绝执行**（训练窗口比股票池时点更早） |
| `--universe-run` 且 asof ≤ 起点 | 正常执行（股票池属于**事前信息**） |
| 确需复现带未来信息的旧结果 | 显式加 `--allow-lookahead-universe`；偏差会写入 `unimplemented_json` |
> **例**：`--universe-run b8dd742f…`（asof=2025-01-21）+ 默认起点 2015-01-01
> → **直接报错，不会跑出任何结果**。
> 想用这个池子，必须 `--start 2025-01-21`（或更晚）。
### 回测里的成交与成本口径
| 项 | 口径 |
|---|---|
| 成交价 | 信号**次日开盘价** ± 滑点（固定此行为，`same_close` 等分支未实现） |
| 佣金 / 印花税 / 过户费 | 佣金双边取 `max(额×费率, 最低佣金)`；印花税**仅卖出**；过户费双边 |
| 红利税 | 按持股期限：≤1 月 20%、≤1 年 10%、>1 年免征 |
| 整手 | 买入按 100 股取整 |
| 涨跌停 | 开盘即封板 → 该信号**跳过**（记 `skip_reason`） |
| 停牌 | 该信号**跳过**（`backtest.yml` 写的 `defer` **未实现**，不会顺延） |
| 分红 | 除权日入账，**留存为现金**（`cash_mode: reinvest` 未实现），下次调仓按目标权重再配置 |
| 送转股 | 已实现：股数按 `stk_div` 增加、成本不变 |
| 配股 | **未实现**（`handle_rights_issue` 不生效） |
| 部分成交 / 成交量占比 | **未实现**（按信号全额成交，受资金与权重上限约束） |
> 以上「未实现」的项都会**逐条写入 `hd_backtest_run.unimplemented_json`**，
> 你可以直接从库里读到该 run 到底哪些约束没生效 —— 不会静默。
### 验证这次回测「干净」的两个动作
```sql
-- ① 有没有被声明为「含未来信息」（应为 0）
SELECT run_id, start_date, end_date,
(unimplemented_json LIKE '%含未来信息%') AS bias_flag
FROM hd_backtest_run
WHERE universe_run_id = '<你的 run_id>'
ORDER BY created_at DESC;
-- ② 资金对账残差必须为 0（不为 0 时不要采信任何绩效指标）
SELECT run_id, status, unimplemented_json FROM hd_backtest_run
ORDER BY created_at DESC LIMIT 1;
```
CLI 也会直接打印对账残差与 `✓`。
---
## 0.4 步骤④：看结果与「能不能信」
| 入口 | 看什么 |
|---|---|
| `hdiv web` → 首页 | 数据审计、股票池、画像、回测、Walk-forward 的汇总入口 |
| 回测详情 | 净值曲线、逐笔成交（含 `reason_json`：为什么买）、未成交信号（含 `REJECT` 原因）、持仓 |
| **Walk-forward 详情** | **逐窗口样本内/样本外对比** —— 判断策略好坏的唯一依据 |
| `output/reports/` | 静态 HTML 快照（需 `--html` 显式导出） |
**读结论的三条纪律**：
1. **只认 Walk-forward 的样本外结果**，不要采信单路径全期数字。
本项目的实测就是反例：同一份数据，回补前后单路径从 +117% 掉到 +93%，
而样本外 7 个窗口**一个数字都没变**。
2. **对账残差不为 0 就不要看绩效**。
3. **样本太短不要下结论**。用 2025 起的池子跑不到 2 年（约 21 个调仓月），
统计上说明不了任何问题，更**不能拿来调参**。
---
## 0.5 一页速查：每步的命令、产出、坑
| 步骤 | 命令 | 落库 | 最容易踩的坑 |
|---|---|---|---|
| ① 选股 | `hdiv universe --asof <日期>` | `hd_universe_run` / `hd_universe_member` | `asof` 会归一化到交易日；`--no-persist` 后无法被回测引用 |
| ② 画像 | `hdiv profile --universe-run <id>` | `hd_profile_run` / `_stat` / `_series` / `_score` | 画像**不参与回测**；窗口可能被数据起点截短（看覆盖率警告） |
| ③ 回测 | `hdiv backtest [--universe-run <id>] [--start]` | `hd_backtest_run` / `_equity` / `_position` / `_trade` / `_signal` / `_metric` | **股票池 asof 晚于起点会被拒绝**；`defer`/`reinvest` 等未实现项在 `unimplemented_json` 里 |
| ④ 验证 | `hdiv backtest --mode walkforward` | `hd_walkforward_run` / `_window` | 必须与 `--universe-run` 分开用；约 25~80 分钟 |
| ⑤ 调参 | `hdiv sensitivity --sweep "..."` | `hd_sensitivity_run` / `_point` | 样本不足时噪声会被误读为过拟合 |
---
# 1. 系统是什么
一套 **A 股高股息策略的研究与回测系统**。它把下面这条链路串成一条可复现的流水线：
@@ -120,26 +403,34 @@ export PYTHONPATH=src
## 2.4 完整跑一遍策略研究
> **完整的分步讲解见 §0（先读那一节）。** 这里只给最短的命令序列。
```bash
export PYTHONPATH=src
# 股票池（时点：2024-06-28）
# ① 股票池（时点：2024-06-28）
.venv/bin/python -m hdiv universe --asof 2024-06-28
# → 记下输出的 run_id
# 个股画像（对股票池内全部股票）
.venv/bin/python -m hdiv profile --universe-run <上一步的 run_id>
# ② 个股画像（对股票池内全部股票，按该池的时点）
.venv/bin/python -m hdiv profile --universe-run <①的 run_id>
# 登记策略
# ③ 登记策略
.venv/bin/python -m hdiv strategy register
# 回测（默认区间取 config/backtest.yml 的 period）
.venv/bin/python -m hdiv backtest
# ④ 回测
# - 若要用①这个池子：必须带 --universe-run，且 --start 不得早于该池 asof
# （2024-06-28 的池子 → 起点最早 2024-06-28；否则会被未来函数守卫拒绝）
# - 若要看**策略本身**的历史表现：去掉 --universe-run，让引擎逐调仓日重筛
.venv/bin/python -m hdiv backtest --universe-run <①的 run_id> --start 2024-06-28
.venv/bin/python -m hdiv backtest --start 2015-01-01 # 策略本身
# 注意：不传 --start 时取 config/backtest.yml 的 period.start（2015-01-01），
# 这与 --universe-run 组合会被**拒绝**，详见 §0.3 的守卫表。
# Walk-forward 样本外验证（约 25 分钟）
# ⑤ Walk-forward 样本外验证（★ 判断策略的唯一依据，约 25~80 分钟）
.venv/bin/python -m hdiv backtest --mode walkforward
# 参数敏感性
# ⑥ 参数敏感性
.venv/bin/python -m hdiv sensitivity
```
@@ -310,17 +601,26 @@ industry_exemptions:
| `series_max_points` | `1500` | 落库序列点数上限（等间隔降采样，仅影响画图） |
| `series_metrics` | `[dv_yield, pe_ttm, pb, close, drawdown]` | 哪些指标需要落时间序列 |
| `ttm_dividend.window_days` | `365` | TTM 每股分红回看天数 |
| `ttm_dividend.grace_days` | `45` | 宽限期（见下方说明） |
| `ttm_dividend.grace_days` | `45` | 宽限期/容差（见下方说明） |
| `ttm_dividend.smooth_spikes` | `true` | 消除除权间隔不规整造成的毛刺 |
| `percentiles` | `[10,25,50,75,90]` | 需计算的分位数 |
| `dividend_yield_volatility.*` | 250/60/20/10 | 日/月/季/年频波动窗口 |
| `safety_margin.mode` | `separate` | `separate`=分项展示 / `composite`=加权综合 |
| `safety_margin.weights` | 见文件 | 综合分权重（`composite` 模式下必须和为 1.0） |
| `safety_margin.score_anchors` | 见文件 | 各分项的满分/零分锚点 |
> **`grace_days` 为什么必需**：A 股年度分红的除权间隔中位数约 **366 天**
> （实测招商银行 5 次间隔 > 365 天，最长 393 天）。严格 365 天窗口会制造
> 1~3 天的「空窗期」，把股息率算成 0 —— 这是统计假象，会污染历史分位。
> 仅当严格窗口结果为零时，才回退到 `365 + grace_days`。
> **`grace_days` 的作用**：A 股相邻两次除权间隔经常 ≠ 365 天，
> 硬窗口会在每年除权日附近制造两种日历假象 ——
> **重叠虚高**（间隔 < 365，新旧同时在窗口内，实测招商银行 +108%）
> 与**断档虚低**（间隔 > 365，旧的已到期新的未入场，实测中国神华 −57%）。
>
> `smooth_spikes: true` 时按「同一档年度分红由后继接管」处理：
> 间隔落在 `365 ± grace_days` 内即视为同一次分红的正常漂移，
> 新旧衔接处不再双算也不再断档；间隔 < `365 − grace_days` 视为年内多次分红
> （中期+年度），彼此都保留；超过 `365 + grace_days` 仍无后继则如实归零。
>
> 实测效果：招商银行 >20% 跳变 21 → 5 次，中国银行虚低归零 77 天 → 0 天。
> 若个别股票仍有断档，把 `grace_days` 调大（如 90）。
---
@@ -339,11 +639,101 @@ strategy:
|---|---:|---|
| `entry.yield_percentile` | `75` | 买入阈值：股息率 ≥ 历史 P75 |
| `entry.scale_in[]` | 75→25%, 80→50%, 85→75%, 90→100% | 分批建仓阶梯 |
| `entry.profile_gate` | 启用，4 条规则 | **实时画像闸门**（见下节） |
| `exit.yield_percentile` | `25` | 卖出阈值：股息率 ≤ 历史 P25 |
| `exit.scale_out[]` | 50→50%, 25→0% | 分批减仓阶梯 |
| `position.max_position` | `0.10` | 单股仓位上限 |
| `position.sector_max_position` | `0.25` | 单行业仓位上限 |
| `position.max_holdings` | `20` | 最多持仓只数 |
| `position.sector_max_position` | `0.25` | 单行业仓位上限（**尚未实现**，见 §11） |
| `position.max_holdings` | `20` | 最多持仓只数（**尚未实现**，见 §11） |
### 实时画像闸门 `entry.profile_gate`（新增）
**它解决的问题**：股票池每 12 个月才重建一次，期间持有的候选可能早已「不值得买」。
闸门的语义是 —— **股息率分位触发买入之后，再用「当日可见的数据」重算一次个股画像，
不通过的票直接剔除。**
```yaml
entry:
profile_gate:
enabled: true # false 时整条链路不参与，回测行为与启用前完全一致
window_years: 5 # 画像统计窗口；0 = 全历史；其余必须是 profile.yml 的 windows_years 之一
on_unverifiable: reject # 数据缺失/样本不足时：reject = 保守不买（默认）/ pass = 放行
rules:
- { metric: dividend_continuity_years, op: ">=", value: 5 }
- { metric: payout_ratio, op: "<=", value: 1.0 }
- { metric: fcf_dividend_cover, op: ">=", value: 1.0 }
- { metric: roe_avg, op: ">=", value: 0.08 }
```
| 字段 | 含义 |
|---|---|
| `metric` | 画像指标代码，只能是 `src/hdiv/core/metrics.py` 里声明的那批（写错在**配置期**就报错） |
| `stat` | `current_value`（当日值）/ `current_percentile`（当日值在窗口分布中的分位，仅序列型指标可用） |
| `op` | `>=` / `<=` / `>` / `<` |
| `value` | 阈值 |
三条关键性质：
1. **无未来函数**：每个决策日只用「当时可见」的价格、每日指标、分红（`imp_ann_date`
与 `ex_date` 双重约束）与财报（`ann_date <= asof`）。有负例测试守护
（公告日前一天不得看到该年报；除权日前一天不得包含该笔分红）。
2. **与批量画像同一定义**：闸门用的指标与 `hdiv profile` 页面上的指标**逐值一致**
（有等价性测试），不会出现「页面一个数、回测另一个数」。
3. **惰性与复用**：只在买入条件已触发时才计算；跨股票共享的面板按时点缓存，
长周期指标从同一份已载入面板里切窗口。因此成本与**触发次数**成正比，
而不是与「区间长度 × 股票数」成正比；规则里不含财务指标时完全不查财报。
**被剔除的信号怎么看**：信号类型为 `REJECT`，`skip_reason = PROFILE_GATE`，
会出现在「回测 → 未成交信号」列表里，标签为
**「实时画像未通过，主动放弃买入」**；`reason_json.profile_gate.checks`
逐条记录每个指标的**实际值、阈值、状态、是否通过**，可直接回答「为什么没买」。
**`on_unverifiable` 怎么选**：这是本项目的一贯取舍（同 `universe.dividend.on_missing_data`）。
| 取值 | 行为 | 适用 |
|---|---|---|
| `reject`（默认） | 数据缺失或样本不足 → 不买 | 忠于「安全边际」：宁可错过，不可踩雷 |
| `pass` | 无法验证 → 放行 | 与股票池筛选口径一致；结果更依赖数据完整度 |
> 实测差异很大：2016 年初，中石化的**最新可见分红属于 FY2015，而 FY2015 年报尚未公告**
> （约 3 月才披露），因此「支付率」在当时**根本无法验证**。
> `reject` 会放弃买入，`pass` 会照买 —— 这不是 bug，而是策略取舍得由你决定。
### 窗口覆盖率 `min_window_coverage`（新增，重要）
**「名义 5 年」不等于「真有 5 年数据」。** `window_slice(asof, 5)` 的语义是
「把已有数据切成最近 5 年」，数据起点晚于窗口左端时窗口会被**静默截短**。
本项目行情/每日指标自 **2015-01-05** 才有，所以实测（600036.SH，股息率，5 年窗口）：
| asof | 窗口内实际观测 | 应有交易日 | 覆盖率 |
|---|---:|---:|---:|
| 2015-12-31 | 239 | 1214 | **19.7%** |
| 2016-12-30 | 483 | 1214 | **39.8%** |
| 2018-05-18 | 817 | 1219 | **67.0%** |
| 2019-12-31 | 1214 | 1219 | 99.6% |
| 2020-12-31 起 | ≈1218 | ≈1218 | **100%** |
也就是说：**2019 年及之前的「过去 5 年画像」实际只有 0.2~4 年数据**，
而画像的 `status` 仍报 `OK`（它的门槛低到 20 个观测）。
```yaml
entry:
profile_gate:
window_years: 5
min_window_coverage: 0.0 # 0 = 不因覆盖率淘汰（默认）；1.0 = 必须完整覆盖
```
| 取值 | 行为 |
|---|---|
| `0.0`（默认） | 覆盖率只**记录**在信号的 `reason_json.profile_gate.checks[].window_coverage`，不影响判定 —— 保持改造前行为 |
| `1.0` | 名义 5 年必须真有 5 年数据；不足时按 `on_unverifiable` 处理（默认 → 不买） |
| 中间值 | 例如 `0.8` = 允许最多缺 20% |
**建议**：先把数据回补到位（见 §6.6），再考虑启用 `min_window_coverage: 1.0`；
否则 2019 年之前会几乎没有买入信号（那是**数据不足**，不是策略判断）。
> `hdiv profile` 命令也会打印覆盖率，例如：
> `⚠ 5 年窗口数据不足：最低覆盖率仅 67.0%（窗口会被数据起点截短）`
### 目标仓位阶梯（重要）
@@ -436,9 +826,9 @@ period: { start: 2015-01-01, end: latest }
| `benchmark[]` | 沪深300 / 中证红利 / 上证指数 | 基准列表 |
| `risk_free_rate` | `0.02` | 无风险利率（用于 Sharpe/Sortino） |
| `fill.price` | `next_open` | 信号次日开盘成交 |
| `fill.limit_up_down_rule` | `skip` | 涨跌停时跳过 |
| `fill.suspended_rule` | `defer` | 停牌时顺延 |
| `dividend.cash_mode` | `reinvest` | 分红处理：`reinvest`/`hold`/`cash_out` |
| `fill.limit_up_down_rule` | `skip` | 涨跌停时跳过（`defer` 分支**未实现**） |
| `fill.suspended_rule` | `defer` | ⚠️ **未实现**：实际行为是**跳过**，不会顺延（见 §0.3） |
| `dividend.cash_mode` | `reinvest` | ⚠️ **未实现**：实际行为是**留存为现金**（等价 `hold`），见 §0.3 |
---
@@ -452,6 +842,9 @@ period: { start: 2015-01-01, end: latest }
| `charts.*` | 全部 `true` | 各图表开关 |
| `naming.*` | 见文件 | 输出文件命名模板 |
| `layout.max_width` | `1440` | 页面最大宽度（px） |
| `layout.decimals.ratio` | `4` | **比率的小数位**。百分比小数位 = ratio − 2（ratio=4 → 股息率 6.17%；ratio=6 → 6.1715%）。同时作用于静态报告与 Web 前端 |
| `layout.decimals.money` | `2` | 金额小数位 |
| `layout.decimals.price` | `2` | 价格小数位 |
> **`asset_mode` 怎么选**：见 [§7.8 报告部署](#78-报告部署)。
@@ -504,7 +897,8 @@ hdiv sync financial [--interleaved] [--only-missing] [--apis ...] [--limit N]
hdiv sync index [--no-weight] [--start YYYYMMDD]
hdiv sync price --which daily|adj_factor|daily_basic --start --end [--no-resume]
hdiv sync trading [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--no-resume]
hdiv sync backfill [--start 2015-01-01] [--end 2018-12-31] [--basic-end 2019-12-31] [--no-resume]
hdiv sync backfill [--start 2015-01-01] [--end 2018-12-31] \
[--basic-start <同 --start>] [--basic-end 2019-12-31] [--no-resume]
```
| 目标 | 说明 | 首次耗时 |
@@ -514,11 +908,15 @@ hdiv sync backfill [--start 2015-01-01] [--end 2018-12-31] [--basic-end 2019-1
| `index` | 基准指数行情 + 成分股权重 | ~2 分钟 |
| `price` | 日线/复权因子/每日指标（逐交易日） | 视区间 |
| `trading` | 停牌与涨跌停 | ~20 分钟 |
| `backfill` | 2015–2018 历史回补（写入 qlib 原有表，`INSERT IGNORE` 不覆盖既有行） | ~15 分钟 |
| `backfill` | 历史回补（写入 qlib 原有表，`INSERT IGNORE` **不覆盖既有行**） | 视区间 |
> **`--only-missing`**：跳过已同步的标的，支持断点续传
> **`--interleaved`**：按股票一次性拉齐四张报表，使策略相关的大市值股票优先就绪
> **回补需要显式授权**：`HDIV_ALLOW_BACKFILL=1` 或改 `datasource.yml`
> **`--basic-start` 必须显式给出**：`run_backfill` 的默认 `basic_start=2015-01-01`，
> 早期 CLI 没有这个参数，于是「回补 2010–2014」实际只补了行情与复权因子，
> **`daily_basic` 仍停在 2015** —— 画像里的 PE/PB/股息率照样拿不到早年数据。
> 现在 `--basic-start` 缺省时跟随 `--start`。
## 5.3 `audit` — 数据审计
@@ -526,10 +924,16 @@ hdiv sync backfill [--start 2015-01-01] [--end 2018-12-31] [--basic-end 2019-1
hdiv audit [--no-persist] [--html]
```
执行 18 项检查（缺口 G1–G6、PIT 纪律、唯一性、单位自检、代码有效性），
执行 15 项检查（缺口 G1–G6、PIT 纪律、唯一性、单位自检、量价单位一致性、代码有效性），
结果写入 `hd_data_audit` 并生成 `output/data_audit_<date>.html`。
退出码：总体 FAIL 时为 1。
> 与单位有关的两项：`UNIT`（`daily_basic` 的市值恒等式 + 量级）与
> `UNIT-OHLCV`（`stock_daily` 逐年抽样的量价单位一致性）。
> 后者当前会报 **WARN**：2015-2019 的存量行仍是 Tushare 原始单位，
> 读取层已兜底换算（结果正确），但存量数据本身仍应择机重刷。
> 详见 §9.1。
## 5.4 `universe` — 股票池筛选
```bash
@@ -554,11 +958,21 @@ hdiv universe [-c config/universe.yml] [--asof 2024-06-28 | latest] [--no-persis
## 5.5 `profile` — 个股画像
```bash
hdiv profile --universe-run <run_id> # 对股票池全部股票
hdiv profile --symbols 600519.SH 000333.SZ --asof 2024-06-28 # 指定股票
hdiv profile --universe-run <run_id> # 对股票池全部股票（asof 取该股票池的时点）
hdiv profile --symbols 600519.SH 000333.SZ --asof 2024-06-28 # 指定股票与**时点**
hdiv profile --symbols 600519.SH --asof 2018-05-18 # 任意历史时点的 PIT 画像
hdiv profile --universe-run <run_id> --html --html-limit 20 # 导出前 20 只的静态报告
```
> `--asof` 决定画像用**哪些数据**：只使用 `<= asof` 的行情、每日指标、分红与财报。
> 例如 `--asof 2018-05-18` 得到的就是「2018-05-18 当天能算出的画像」，
> 5 年窗口覆盖 (2013-05-18, 2018-05-18]。
> 不带 `--asof` 且带 `--universe-run` 时，asof 取该股票池的筛选时点。
>
> **注意**：画像是一次**快照**（每个 asof 一份）。回测并不读取它 ——
> 回测的交易依据是引擎在每个决策日**实时重算**的画像，见
> §4.3「实时画像闸门」与 §9.2。
## 5.6 `strategy` — 策略管理
```bash
@@ -572,19 +986,41 @@ hdiv strategy diff -f A.yml --other B.yml # 比较两版差异
```bash
hdiv backtest [--start 2015-01-01] [--end 2026-09-30] [--no-persist] [--html]
hdiv backtest --mode walkforward # 7 个滚动窗口，约 25 分钟
hdiv backtest --mode walkforward # 7 个滚动窗口
hdiv backtest --universe-run <run_id> # 用指定股票池（冻结）并建立关联
# 注意 1：--universe-run 与 --mode walkforward 不能同时使用（会报错说明原因）。
# 注意 2：单次回测里，若股票池的 asof 晚于回测起点，同样会被**拒绝**
# （同一条未来函数纪律）。错误信息会给出三种正确做法：
# a) 去掉 --universe-run，让引擎逐调仓日按当时可见数据重新筛选（推荐）
# b) 把 --start 改到股票池 asof 之后
# c) 确需复现带未来信息的历史结果：显式加 --allow-lookahead-universe
# —— 该偏差会写入 hd_backtest_run.unimplemented_json，可被检索出来
```
输出示例：
> **为什么单次回测也要拒绝**：股票池带 asof 时点。用 2025-01-21 选出的名单去跑
> 2015 年起的区间，名单里含有 2015 年不可能知道的信息（哪些公司此后仍满足
> 连续分红、5 年 ROE、自由现金流覆盖等条件）。实测：这样跑出的回测
> **在 2015-01-06 就有 8 笔成交**，而按当时可见数据筛选，那段时间的股票池
> 只有个位数只股票。
输出示例（当前配置：实时画像闸门启用）：
```
期初 1,000,000 → 期末 2,148,010 | 总收益 114.80% | CAGR 6.73% | 最大回撤 -21.05% | Sharpe 0.31 | 成交 180 笔
累计现金分红 558,797（已扣红利税 13,676） | 对账残差 -0.0000 ✓
回测 HD_MR_V1 v1.0：2015-01-05 ~ 2026-09-30（2846 个交易日）
实时画像闸门已启用：窗口 5 年，4 条规则，面板自 2004-01-01 起载入（86 只）
实时画像：计算 2428 次（缓存命中 0），涉及 141 个决策时点，
财报面板载入 141 次，流动性查询 0 次 | 画像剔除 1027 次
期初 1,000,000 → 期末 1,927,312
总收益 92.73% CAGR 5.75% 最大回撤 -25.38% Sharpe 0.22 Calmar 0.23 成交 197 笔
累计现金分红 …（已扣红利税 …） | 对账残差 -0.0000 ✓
```
> **「对账残差」是资金恒等式的校验值**（期初 = 期末现金 + 买入 − 卖出 + 费用 − 分红）。
> 应为 0；若不为 0 说明成本或分红入账有遗漏，**此时不要采信绩效指标**。
>
> 「画像剔除 1027 次」= 有多少个买入信号被实时画像拦下。它们全部以
> `REJECT` 记录在库，可在前端「未成交信号」里逐条查看每条规则的实际值。
## 5.8 `sensitivity` — 参数敏感性
@@ -692,6 +1128,87 @@ cp config/strategy/high_dividend_v1.yml config/strategy/my_strategy.yml
> ⚠ **务必先做 ① 和 ②**。单条路径的全期回测会系统性高估策略（见 §7.5）。
## 6.6 把「过去 5 年」补齐（数据回补）
> **✅ 本仓库当前的数据状态：已回补完成（2026-10-04）** ——
> `stock_daily`/`adjust_factor`/`daily_basic` 均覆盖到 **2005-01-04**，
> `hd_suspend`/`hd_limit` 覆盖到 **2010-01-04**。
> 5 年窗口覆盖率自 2015-01-05 起为 **98.7%~100%**，残差已逐日与
> `hd_suspend` 交叉核实为**真实停牌**（16/16 命中）。
> 所以下面这节现在是**方法说明与重做指引**，而不是待办事项。
> 完整记录见 [implementation-status §9.3c](implementation-status.md)。
### 先看缺口：哪些数据支持 5 年回看
| 数据 | 回补前起点 | 当前 |
|---|---|---|
| `stock_daily` 行情 | 2015-01-05 | **2005-01-04** ✅ |
| `daily_basic` PE/PB/股息率 | 2015-01-05 | **2005-01-04** ✅ |
| `adjust_factor` 复权因子 | 2015-01-05 | **2005-01-04** ✅ |
| `hd_suspend` / `hd_limit` | 2019-01-02 | **2010-01-04** ✅ |
| `hd_dividend` 分红 | 1991 | 不变 ✅ |
| `hd_fina_indicator` / `hd_income` / `hd_cashflow` | 1990 / 1990 / 2001 | 不变 ✅ |
| `hd_index_daily` 基准 | 1990 | 不变 ✅ |
| `stock_name_history` ST 历史 | 1990 | 不变 ✅ |
| `trading_calendar` 交易日历 | 2000 | 不变 ✅ |
**结论：卡住「5 年画像」的只有行情与每日指标，缺口就在 2015-01-05 之前。**
### 回补到哪一年，取决于你要覆盖多早的决策日
「asof 的 5 年窗口完整」要求数据起点 ≤ `asof − 5 年`：
| 想覆盖的决策日 | 必须回补区间 | 新增交易日（约） |
|---|---|---:|
| 2015-01-05 起 | **2010-01-01 ~ 2014-12-31** | 1,212 |
| 2018-01-01 起 | 2013-01-01 ~ 2014-12-31 | 486 |
| 同时补齐 8/10 年窗口（`profile.yml: windows_years`） | **2005-01-01 ~ 2014-12-31** | 2,430 |
### 执行
```bash
cd ~/project/高股息回测
export PYTHONPATH=src
export HDIV_ALLOW_BACKFILL=1 # 回补写入 qlib 原有表需显式授权
# ① 行情 + 复权因子 + 每日指标（三者一起补，缺一个画像就残）
.venv/bin/python -m hdiv sync backfill \
--start 2010-01-01 --end 2014-12-31 \
--basic-start 2010-01-01 --basic-end 2014-12-31
# ② 若还要成交约束（涨跌停/停牌）覆盖到早年
.venv/bin/python -m hdiv sync trading --start 2010-01-01 --end 2014-12-31
# ③ 核对：只增不减，且量价单位一致
.venv/bin/python -m hdiv audit
```
**必须知道的四件事**：
1. **只追加、不改既有行**（`INSERT IGNORE`）。因此 2015-2019 已存在的行不会被
修成正确单位 —— 那由读取层兜底（见 §9.1）。回补的新行走的是**正确单位**写入路径。
2. **耗时与点数**：`daily`/`adj_factor`/`daily_basic` 的限频是 480 次/分钟，
但瓶颈是 HTTP 往返（每日 3 次调用）。1,212 个交易日 ≈ 3,600 次调用，
实测量级 **1~3 小时**；补到 2005 年约翻倍。先用 `--limit` 或在测试库试跑。
3. **Tushare 权限**：早年数据需要相应积分。若某日返回空，`sync_days` 会记录在
`hd_sync_log`，不会中断整体任务。
4. **回补后必须重跑**：股票池、画像、回测、Walk-forward 的结论都会变
（2015-2019 从「几乎无候选」变成有完整 5 年画像的候选）。
### 回补后怎么确认「5 年真的齐了」
```bash
# 画像命令会打印覆盖率（不足时给警告）
.venv/bin/python -m hdiv profile --symbols 600036.SH --asof 2015-06-30
# ⚠ 5 年窗口数据不足：最低覆盖率仅 xx%（窗口会被数据起点截短）
# 或者在 SQL 里直接量：某股在 (asof-5y, asof] 内的行情观测数
```
也可以把策略的 `entry.profile_gate.min_window_coverage` 设为 `1.0`，
让回测**只**在 5 年窗口完整时才允许买入 —— 不完整的决策日会产出
`REJECT`（`skip_reason=PROFILE_GATE`），理由写明 `window_coverage=67%`。
---
# 7. 报告解读
@@ -754,6 +1271,11 @@ cp config/strategy/high_dividend_v1.yml config/strategy/my_strategy.yml
## 7.5 Walk-forward 报告 ★ 最重要
> **前端入口**：`#/walkforwards`（导航栏「样本外」）。
> 每个 wf_id 是一条独立记录，点进去可看逐窗口的样本内/样本外对比与冻结阈值。
> 该页面同时给出**样本外均值、胜率、稳定性**三个核心判据。
**这是判断策略是否真的有效的核心依据。**
**看什么**：
@@ -770,16 +1292,33 @@ cp config/strategy/high_dividend_v1.yml config/strategy/my_strategy.yml
|---|---|
| 样本外超额 > 0 且稳定性 > 1 | 策略可能真的有效 |
| 样本外超额 ≈ 0 | 与基准相当，无超额收益能力 |
| 样本外超额 < 0 | **策略未通过样本外检验** |
| 样本外超额 < 0 | 看是否集中在牛市（见下） |
| 全期回测远好于样本外均值 | **单路径回测高估了策略** |
> **本系统的实测结论**：全期回测 +114.80%，而 7 窗口样本外收益均值 **−0.95%**
> （基准 +2.29%，超额 **−3.24pp**）。即**当前策略没有稳定的样本外超额收益**。
> 它的价值在于**回撤控制**（样本外最差 −24.62%，基准同期 −46%~−52%），
> **务必用年化口径比较样本内/外**：训练段 5 年、测试段 1 年，
> 直接比累计收益会得出「样本内远高于样本外」的错误印象（本项目实测踩过这个坑，
> 详见 implementation-status.md §7.3）。页面上统一使用年化。
> **务必按牛熊分开看超额**。高股息/低估值策略的典型形态是
> **牛市跑输、熊市跑赢**（用上涨弹性换取下跌保护）。
> 此时只看「超额均值」会被样本里牛熊比例误导 ——
> 本项目实测：4 个熊市窗口全部跑赢，3 个牛市窗口全部跑输。
> 判断这类策略要问的是「我用上涨弹性换下跌保护，值不值」，
> 而不是「它有没有 alpha」。
> **本系统的实测结论**：全期回测 +92.73%，而 7 窗口样本外收益均值 **+1.16%**
> （基准 +2.29%，超额 **−1.13pp**）。即**当前策略没有稳定的样本外超额收益**。
> 它的价值在于**回撤控制**（样本外最差 −22.97%，基准同期 −46%~−52%），
> 更像降低波动的配置工具，而非超额收益来源。
>
> 这个反差不是 bug，正是 Walk-forward 存在的意义 —— 详见
> [implementation-status.md §4.6](implementation-status.md)。
>
> 另外注意：实时画像闸门在两个口径下结论相反 ——
> **全期单路径**收益从 +101.20% 降到 +92.73%（更差），
> 但 **walk-forward 样本外**均值从 −0.00% 升到 +1.16%、最差回撤从 −24.22%
> 改善到 −22.97%（更好）。按本项目一贯立场以样本外为准，闸门是改善。
> 详见 §4.6c。
## 7.6 参数敏感性报告
@@ -977,15 +1516,32 @@ Tushare 各接口单位不统一，且从列名看不出来。系统在 `data/un
| `roe` / `roic` / `debt_to_assets` | 百分数 | **小数** |
| 财务报表金额 | 元 | 元（不变） |
| `dividend.base_share` | 万股 | **股** |
| `stock_daily.vol` | 手 | **股**（×100） |
| `stock_daily.amount` | 千元 | **元**（×1000） |
**自检手段**（审计中的 `UNIT` 检查）：
**自检手段**（审计中的 `UNIT` 与 `UNIT-OHLCV` 检查）：
1. **恒等式** `总市值 ≈ 收盘价 × 总股本` —— 能发现「只换算了一个字段」
2. **绝对量级** 总市值中位数须落在 A 股合理区间 —— 这是唯一能识别整体单位错误的手段
3. **量价一致性**（`UNIT-OHLCV`）：`成交额 / (成交量 × 收盘价)` 应 ≈ 1。
≈ 0.1 说明该行还是 Tushare 原始口径（手 / 千元）。审计会逐年抽样并列出
> 为什么必须两项都做：`元/股 × 万股 = 万元`，所以恒等式在**原始单位下也成立**，
> 为什么必须前两项都做：`元/股 × 万股 = 万元`，所以恒等式在**原始单位下也成立**，
> 单靠它无法发现「万元当元用」。实测该错误曾导致市值过滤选中 **0 只**股票。
> **`stock_daily` 的量价单位曾经不一致（已修复）**：该表是「追加进既有 qlib 库」的，
> 2015-01~2019 的行由本项目从 Tushare 回补，写的是**原始单位**（手 / 千元）；
> 2020 起沿用 qlib 存量（股 / 元）；2019 年**同日混着两种**。
> 而 `min_avg_amount_20d: 20000000` 是按「元」写的 ——
> 于是 2015-2019 的 20 日均额被低估 1000 倍，流动性门槛实际变成
> 「日均成交额 ≥ 200 亿元」，**把 2015-2019 的股票池整体清空**
> （实测 2016/2017/2018 各筛选出 0 只）。
>
> 修复方式有两层：写入端（`sync.price.daily_frame`）统一换算；
> 读取端（`units.normalize_ohlcv_units`，按行判定、**幂等**）兜住存量数据。
> 修好后 2016-02 的股票池是 7 只、2017 是 11 只、2018 是 13 只。
> 审计新增 `UNIT-OHLCV` 防止回归。
## 9.2 Point-in-Time（无未来函数）
| 数据 | 可见性规则 |
@@ -995,11 +1551,25 @@ Tushare 各接口单位不统一，且从列名看不出来。系统在 `data/un
| 行情/指标 | `trade_date <= 评估日` |
| ST 状态 | 按 `stock_name_history` 的名称生效区间还原，**不看今天的名字** |
| 股票池 | 包含**此后才退市**的股票（消除生存者偏差） |
| **实时画像** | 每个决策日按上述规则重算；窗口只覆盖 `(评估日 − N 年, 评估日]` |
| **窗口覆盖率** | `n_obs / 该窗口应有交易日数`；< 1 说明窗口被数据起点截短（见 §4.3、§6.6） |
| **股票池 vs 回测区间** | 股票池的 `asof` 晚于回测起点即**拒绝执行**（可显式放行并留痕） |
另外：
- **成交在信号次日开盘**，信号日只产生信号
- 滚动分位窗口的**右端必须是评估日本身**
- 画像的窗口切片是 `(起点, asof]`（左开右闭），与分位参照窗口一致
- Walk-forward 测试段使用**训练段冻结**的分布
（但实时画像闸门**不需要冻结** —— 它只用当时可见数据做过滤，
不带任何用测试期数据拟合出来的参数）
**三类未来函数，系统的处理方式不同**：
| 类型 | 处理 |
|---|---|
| 用未来数据算**当日因子** | 代码层杜绝（`Repo` 是唯一取数出口，有负例测试） |
| 用未来时点选出的**股票池**跑更早区间 | **拒绝执行**（`--universe-run` 的 asof 校验） |
| 用未来数据给人看的**研究快照**（画像/筛选页） | 允许，但**不进入回测**；回测每天自己重算 |
## 9.3 分红口径
@@ -1043,11 +1613,18 @@ Tushare 各接口单位不统一，且从列名看不出来。系统在 `data/un
| 过户费 | 双边 |
| 红利税 | 按持股期限：≤1月 20%、≤1年 10%、>1年 免征 |
| 整手 | 买入按 100 股取整 |
| 涨跌停 | 开盘即封板则该信号不成交，记录 `skip_reason` |
| 停牌 | 信号顺延到下一可成交日 |
| 涨跌停 | 开盘即封板则该信号**当日跳过**，记录 `skip_reason`（`defer` 未实现） |
| 停牌 | **当日跳过**（⚠️ `fill.suspended_rule: defer` **未实现**，不会顺延；见 §0.3） |
| 送转股 | 已实现：股数按 `stk_div` 增加、成本不变 |
| 配股 | **未实现**（`handle_rights_issue` 不生效） |
| 部分成交 / 成交量占比 | **未实现**（按信号全额成交，受资金与权重上限约束） |
**分红处理**：持仓市值用**不复权价**，现金分红在除权日**单独入账**。
这样从根上避免了「复权收益 + 分红」的重复计算。
**分红处理**：持仓市值用**不复权价**，现金分红在除权日**单独入账**（按持股期限扣红利税），
**留存为现金**，在下次调仓时按目标权重重新配置
（⚠️ `cash_mode: reinvest` / `reinvest_rule` **未实现**）。
用不复权价 + 独立现金流，从根上避免了「复权收益 + 分红」的重复计算。
> 以上每一项未实现都会逐条写入 `hd_backtest_run.unimplemented_json` —— 可直接查库核对。
**资金对账**（每次回测都会校验）：
@@ -1233,11 +1810,17 @@ curl -I http://192.168.1.166:8080/ggx/index.html
| 股票清单 | `#/universes/<run_id>` | 入选与淘汰股票、逐股关键指标、**点击个股打开画像** |
| 个股画像 | `#/stocks/<symbol>` | K线+股息率+PE 四联图、历史分布、安全边际雷达 |
| 回测记录 | `#/backtests` | 每条记录显示**回测条件与总体结果** |
| 回测详情 | `#/backtests/<run_id>` | 净值曲线、绩效指标、**逐笔成交与理由** |
| 回测详情 | `#/backtests/<run_id>` | 净值曲线、**任意日持仓明细**、逐笔成交与理由 |
| 个股买卖点 | `#/backtests/<run_id>/stocks/<symbol>` | 股价/股息率/PE/ROE 趋势图 + 买卖点标注 |
| **样本外** | `#/walkforwards` | Walk-forward 记录；**样本内 vs 样本外**逐窗口对比 |
| 归档 | `#/archive` | 已归档与已删除的记录，可恢复 |
### 记录管理
- **重跑覆盖**：同一份配置 + 同一个 `asof` 时点 → 同一个 `run_id`，重跑会**原地覆盖**
旧记录（含成员清单与因子快照），不会累积重复条目。
你在界面上的**命名与备注会被保留**，不会被重跑清掉。
改了配置（阈值等）或换了时点则视为不同筛选，各留一条记录。
- **命名**：点「命名」按钮，可设置名称与备注。名称会显示在列表与详情页标题上
- **归档**：归档后默认列表不再显示，可在「归档」页找到并取消归档
- **删除**：**软删除** —— 记录被隐藏，但数据完整保留在数据库中，可随时恢复。
@@ -1363,6 +1946,45 @@ bash scripts/mac_nginx_ggx.sh status # system 项目
./deploy/install-service.sh status # 本项目（后端侧）
```
### 11.2.1 `/api/health` 通，但页面报「配置校验失败」
现象：状态徽章正常、`api/health` 通，可页面整体报错，形如：
```text
加载失败：配置校验失败：/…/config/datasource.yml
1 validation error for DataSourceConfig
sync
Extra inputs are not permitted [type=extra_forbidden, input_value={'min_symbols_floor': 200…}]
```
**这不是配置写错了，是后端进程太旧**。`hdiv` 在进程启动时把
`src/hdiv/core/config.py` 的模型和 `config/*.yml` 一起读进内存（配置还经
`lru_cache` 缓存），所以：
- 你新加了配置字段 + 对应的模型字段，
- launchd 里那个进程却还在用**加字段之前**的模型校验文件，
- 于是「新文件里的 `sync` 段」成了模型眼里的多余键 → `extra_forbidden`。
注意 `KeepAlive` 只负责**崩溃后**拉起，正常运行的进程不会因为你改文件而重启。
症状最迷惑的地方是：报错看起来像 YAML 写错了，实际 YAML 完全合法。
**验证与修复**（一条命令即可）：
```bash
# 绕过服务，用当前源码直接校验该文件：能通过就说明文件没问题
PYTHONPATH=src .venv/bin/python -c \
"from hdiv.core.config import load_config; print(load_config('datasource'))"
# 改完 src/ 或 config/ 之后必须重启后端，让它重新 import 模块、重新读配置
./deploy/install-service.sh restart
```
`restart` 用的是 `launchctl kickstart -k`（先杀后拉，PID 会变）；
手工 nohup 启动的（`deploy/serve.sh start`）对应执行 `./deploy/serve.sh restart`。
**记住这条规则：改 `src/` 或 `config/` 之后，一律 `restart` 一次。**
只改 `web/`、`templates/` 这类静态产物不需要——它们由 nginx 每次请求重新读盘。
## 11.3 股票池为空或很少
**按顺序排查**：
@@ -1396,6 +2018,10 @@ bash scripts/mac_nginx_ggx.sh status # system 项目
**最可能原因：预热期**。滚动分位窗口需要历史分布；数据起点之前的时段无法产生信号。
若回测区间前 3~5 年完全空仓、之后才开始建仓，这是**预期行为**（不做未来函数的代价）。
注意：**用 `--universe-run` 冻结股票池时没有预热期** —— 引擎不再自筛选，
历史约束不作用于早期，2015 年起即可能满仓。这也是为什么冻结模式的回撤
显著大于重新筛选模式。若你看到早期就满仓，那是冻结模式的正常表现，不是 bug。
**确认方法**：
```sql
@@ -1448,8 +2074,14 @@ market.min_market_capp
| 4 | 未实现部分成交 | 按信号全额成交，受资金与权重上限约束 |
| 5 | 大股东质押、重大诉讼过滤**无数据源** | 配置项存在但恒不生效 |
| 6 | AI Agent 层（P8）未实现 | 属 `plan.md` 第四版扩展 |
| 7 | 回测 2015–2018 为预热期 | 100% 现金，无信号（见 §10.4） |
| 8 | 参数敏感性结论依赖扫描区间与池规模 | 样本不足时噪声可能被误读为过拟合 |
| 7 | 策略/回测配置里下列字段**尚未实现** | 改了它们**回测结果不会变**：<br>`position.max_holdings`、`position.sector_max_position`、`position.weight_scheme`、`risk.max_portfolio_drawdown`、`risk.max_single_drawdown`、`risk.liquidity_limit_pct_adv`、`exit.stop_loss_pct`、`exit.max_holding_days`、`fill.max_volume_pct`、`fill.partial_fill`、<br>**`fill.suspended_rule` / `fill.limit_up_down_rule` 的 `defer`**（未成交信号当日即被丢弃，不会顺延）、**`dividend.cash_mode=reinvest` / `dividend.reinvest_rule`**（分红留存为现金，在下次调仓再配置）、**`dividend.handle_rights_issue`**（配股不入账）、**`execution.signal_to_execution`**（固定次日开盘成交）。<br>**这些都会逐条写入 `hd_backtest_run.unimplemented_json`**，可直接从库里查 |
| 8 | `stock_daily` 2015–2019 的存量行仍是 Tushare 原始单位 | 读取层已兜底换算（结果正确），审计 `UNIT-OHLCV` 报 WARN；重刷数据可消除 |
| 9 | ~~行情/每日指标只到 2015-01-05~~ → **已修复（2026-10-04 回补到 2005-01-04）** | 曾使「过去 5 年画像」在 2019 年前只有 0.2~4 年数据（覆盖率 20%~67%）；回补后 5 年窗口覆盖率为 **98.7%~100%**，残差经逐日核实为真实停牌。另：**修好数据后全期收益从 +117.36% 降到 +92.73%**，因为 2015 年（牛市顶 + 股灾）从「被数据缺口挡住」变成被真实交易。见 §6.6 与 implementation-status §9.3c |
| 10 | `config/profile.yml: sufficiency` 三个阈值**尚未被任何代码使用** | `min_history_years_dividend` / `min_history_years_price` / `min_dividend_records` 目前是死配置。真正的充分性判定由 `profile_gate.min_window_coverage` + `on_unverifiable` 承担 |
| 11 | 实时画像闸门默认 `on_unverifiable: reject` | 数据不全时会放弃部分本可买入的标的（刻意保守，可改为 `pass`）。回补后早年数据已基本完整，影响大幅缩小 |
| 12 | 参数敏感性结论依赖扫描区间与池规模 | 样本不足时噪声可能被误读为过拟合 |
| 13 | 幸存者偏差尚有 **3 只**缺口 | `000022.SZ`/`000043.SZ`/`300114.SZ`（均因吸收合并退市）有行情但不在 `stock` 表，永远不会进入候选集；占 5,903 只的 0.05%。根因是 `stock` 只收录在市股票 |
| 14 | `hd_suspend`/`hd_limit` 含 356 个 `stock` 表未收录代码 | 其中 356 中 250+106 为北交所（按交易所白名单设计排除）；SZ 部分与第 13 条同源。不影响可交易标的 |
## 12.1 使用前请务必知道
@@ -1504,6 +2136,6 @@ export PYTHONPATH=src
| 个股画像口径（窗口/分位/权重） | `config/profile.yml` |
| 买卖阈值与仓位 | `config/strategy/high_dividend_v1.yml` |
| 手续费/滑点/红利税 | `config/cost.yml` |
| 回测区间/Walk-forward/基准 | `config/backtest.yml` |
| 回测区间/Walk-forward/基准/分位最小样本量 | `config/backtest.yml` |
| 报告外观与部署方式 | `config/report.yml` |
| 后端监听地址/端口 | `hdiv web` 命令行参数（或 `deploy/serve.sh` / launchd plist） |