simon
fdfdd152d8
说明：本提交是工作区中此前的未提交工作（在 cf6d4d2 之后产生），**非本次会话所写**，
按用户要求**不跑测试、直接记录变更并推送**。
已完成推送前的基础安全检查：无明文凭据、无大文件、`.env`/`logs/`/`output/` 仍被忽略。
测试状态：**本次未执行测试套件**。
## 一、TTM 股息率的两处残余缺陷 + 卖出复核
起因：用户报告 `600690.SH` 在 2026-07-30 触发清仓、07-31 开盘卖出，实际不该卖。
### 缺陷一：同一除权日的多条「实施」记录被逐行累加
- 成因：`hd_dividend` 写入侧刻意保留全量公告记录，去重键含 `ann_date`，
同一笔分红会有多条「实施」记录落在**同一除权日**；查询侧逐行累加即重复计入。
- 规模：5724 只有现金分红的股票中 **953 只**存在同除权日重复（多出 1313 行）。
- 效果：`600690.SH` 的 `ttm_dps` 长期虚高约一倍（2.46848 vs 真实 1.23424），
窗口到期时又必然回落，把假象放大成一次 −78% 的塌陷。
- 修法：新增 `factor.dividend_yield.dedupe_dividend_events()`，按 `(symbol, ex_date)`
聚合成**一笔经济事件**（金额/股数逐字段取最大 → 收敛「分项 + 合计」；
日期取最晚 → PIT 保守）。三处入口统一调用：`ttm_dps_series`、
`Repo.dividend_events`、`universe/filters/dividend.py`。
### 缺陷二：只看相邻间隔，漏掉「年度 → 中期 → 下一年度」的跳法
- 成因：7.6 的「按后继接管」只看相邻两次除权的间隔。实测 `600690.SH`：
FY2024 年度 2025-07-25、FY2025 中期 2025-11-07、FY2025 年度 2026-08-21。
105 天的间隔使前两笔被判为「年内多次分红」而互不取代，392 天又超过 `365+45`
→ **2026-07-25~08-21 出现 28 天空窗**，可见现金只剩 0.26920。
- 修法：`ttm_dps_series` 的覆盖窗口由「按相邻间隔」升级为「**按财年 `end_date`**」：
① 后继接管（保留 7.6 行为，阈值 `ttm_days - grace_days` = 320 天）；
② **跨财年补位**：每个财年最后一笔 → 下一财年最后一笔入场，上限 `365 + grace`；
③ **末笔宽限兜底**：无后继时覆盖 `365 + grace`（真停发仍如实归零）。
- 验收（作者实测）：600690 在 2026-07-27 的 `ttm_dps` 由 0.53840 变为 **1.23424**，
股息率 5.30%、历史分位 92.98%，**不再触发 P25 清仓**。
### 缺陷三（设计缺口）：卖出只认「已除权的现金」，不认「已公告的分红」
- 成因：FY2025 年度分红 0.89151 的**实施公告日是 2026-06-25**，除权日 2026-08-21。
TTM 现金口径看不到它 → 「股息率处于历史低位」在字面上为真，
实际描述的是**现金流时点**而非分红能力恶化。
- 修法：新增 `entry/exit.confirm`（`enabled` / `min_ratio` / `announce_lookback_days`）：
若「已公告未除权」的分红说明股息率本应更高，且
`TTM ÷ (TTM + 已公告未除权) < min_ratio`，则判定**未确认**：
保持仓位并记录 `EXIT_UNCONFIRMED`（不进成交流水）。真降息不会命中。
## 二、公司行为的三处静默错误（分红/送转/配股口径）
### 问题一：纯送转被整行丢弃（凭空亏损）
- `_apply_dividends` 在算送股**之前**就按 `cash_div_tax <= 0` 整行 `continue`，
于是「10 送 10」这类**无现金分红**的送转完全不调股数 ——
而价格是不复权价、除权日照常腰斩 → 记出一笔不存在的亏损。
- 规模：全库「实施且 `stk_div > 0`」13,038 行，其中**纯送转 3,268 行**；
高股息池成员在 2015-2026 区间内 **824 笔**（如 `000793.SZ` 每 10 股转增 12 股，
单笔约 −54% 的该持仓市值）。
- 修法：现金与送转**各自独立判断**，只有「既无现金也无送转」才跳过；
并把 `stk_bo_rate`/`stk_co_rate` 写入分红台账留痕。
### 问题二：同一除权日的重复记录被重复入账
- 全库 **1401 组**同 `(symbol, ex_date)` 的多条实施记录（1240 组字段相同；
96 组报告期不同、122 组金额不同）。实测 `002352.SZ 2024-11-07` 同时有
0.4 / 1.0 / 1.4 三条，而 1.4 = 0.4 + 1.0 是合计口径 → 逐行累加会放大两三倍。
- 修法：复用 `dedupe_dividend_events`（与缺陷一同一个函数）。
### 问题三：分红再投资的声明与行为不一致
- 引擎实际行为一直是「分红现金回到与初始资金同一个 `cash` 变量，
下次调仓按目标权重再配置」= `reinvest` + `portfolio_rebalance`；
但 `backtest.yml` 写的是 `same_stock_next_open`，于是每次 run 都声明
「未实现分红再投资规则，分红留存为现金」，让人误以为分红不可再投资。
- 修法：配置改为已实现组合 `cash_mode: reinvest` + `reinvest_rule: portfolio_rebalance`；
声明逻辑抽成 `dividend_handling_notes()`，**逐档取值都有单测**对应
（`hold`/`cash_out`/`same_stock_next_open`/`handle_stock_dividend=false`/配股
才声明未实现）。顺带接线一直是**死字段**的 `dividend.apply_dividend_tax`。
## 三、新增：回测层面的排除行业清单（黑名单）
- 位置与语义：`config/backtest.yml: universe_exclusions.industries` ——
「**这次回测**特意不要哪些行业」（研究口径），
与 `config/universe.yml`（策略选股定义）**叠加取并集**，只做减法。
三种回测模式（single / walkforward / daily）一律生效。
- 最大的坑：数据库 `stock.industry` 里**没有「房地产业」**，它被拆成四个名字，
写「房地产」或「房地产业」**一只都排除不掉**：
`全国地产` 26 只 + `区域地产` 43 只 + `房产服务` 13 只 + `园区开发` 14 只 = **96 只**（1.6%）。
因此 `MarketFilter` 首次求值时拿名单与表内实际取值核对，
**写错名字直接抛 `ConfigError`**（并按字符重合度提示最接近的真实取值）。
- 接线：三个入口都走生效后的配置；并修掉一处缓存陷阱（配置变更后缓存未失效）。
- 新增测试锁定它。
## 四、其它
- `src/hdiv/core/config.py`：新增配置模型（排除行业、卖出复核等，+102 行）
- `src/hdiv/data/repo.py`（+45）、`src/hdiv/backtest/engine.py`（+121）、
`backtest/daily.py`、`backtest/walk_forward.py`、`web/service.py`、
`report/universe_report.py` 相应接线
- 测试：新增 `tests/test_dividend_fiscal_year.py`；扩充
`test_backtest.py` / `test_config.py` / `test_daily.py` /
`test_dividend_smoothing.py` / `test_universe.py`
- `tools/diag_dividend_artifact.py`：诊断脚本与上述修复对齐
- 文档：`docs/implementation-status.md` 新增 §7.6b / §7.7 / §11；
`docs/user-guide.md` 新增排除行业清单说明
## 待验证
本次按要求**未执行测试**。上述「实测/验收」数字均引自文档中作者自己的记录，
非本次会话验证结果。建议合入后跑一次全量测试（注意：daily 的 DB 标记测试
因 `hd_cashflow` 无界扫描仍然很慢）。
高股息回测系统
A 股 高股息 + 安全边际 + 估值均值回归 策略的研究与回测系统。
从 Point-in-Time 股票筛选 → 个股特性画像 → 策略定义 → 历史回测 → Walk-forward 样本外验证 → 每日动态股票池推演 → 绩效与敏感性分析 → 统一 Web 前端，全链路打通。
采用前后端分离：前端为 output/ 下的单页应用（hash 路由，nginx 直接托管），
后端为 hdiv web 提供的 REST API（nginx 反代 /api）。
快速开始
cd ~/project/高股息回测
cp .env.example .env # 填入数据库密码与 Tushare token
export PYTHONPATH=src
# 建表
.venv/bin/python -m hdiv ddl apply
# 同步数据（首次约 3~4 小时，可后台跑）
.venv/bin/python -m hdiv sync dividend --only-missing
.venv/bin/python -m hdiv sync financial --interleaved --only-missing
.venv/bin/python -m hdiv sync index
.venv/bin/python -m hdiv sync trading --start 2019-01-01
# 日常增量：只抓「库里还没有的那几天」，不重拉历史
.venv/bin/python -m hdiv sync daily --dry-run # 先看待抓清单
.venv/bin/python -m hdiv sync daily # 真抓
# 注册为每天 17:00 的 launchd 定时任务
./deploy/install-sync-schedule.sh install
# 审计 → 打开 output/index.html
.venv/bin/python -m hdiv audit
完整用法见 使用手册。
文档
| 文档 | 内容 |
|---|---|
| 使用手册 | 安装、配置、命令、报告解读、故障排查 |
| 实施状态 | 交付清单、验收映射、已修复问题、实测结论与限制 |
| 开发计划 | 架构设计、数据库设计、分阶段计划 |
| 需求原文 | 项目的原始方案与验收标准 |
目录
config/ ★ 所有可调参数（YAML，代码零硬编码）
src/hdiv/ 代码：数据层、筛选、画像、策略、回测、分析、报告
templates/ HTML 模板（Jinja2，离线）
assets/ 图表库（ECharts，本地化，不依赖 CDN）
output/ ★ 报告输出（部署这个目录）
sql/ 建表 SQL 副本（供人工审查）
tests/ 439 项自动化测试（含每日动态股票池的取数等价性、预剪枝等价性、PIT 纪律与端到端）
docs/ 文档
三条设计原则
| 原则 | 落实方式 |
|---|---|
| 配置零硬编码 | 任何业务阈值只出现在 config/*.yml；字段名写错直接报错 |
| 只增不删 | SQL 钩子拦截 DELETE/DROP/TRUNCATE；源码扫描测试守护 |
| 无未来函数 | 所有取数必经 data/repo.py，PIT 纪律有负例测试 |
重要提示
本系统的实测结论是：策略没有稳定的样本外超额收益。
全期回测（2015–2026）显示 +92.73% / CAGR 5.75%， 但 7 窗口 Walk-forward 的样本外收益均值仅 +1.16%（基准 +2.29%，超额 −1.12pp）。
它真正的价值在于回撤控制（样本外最差 −22.97%，基准同期 −46%~−52%）—— 更像降低波动的配置工具，而非超额收益来源。
四条必须说的结论（详见实施状态 §4.6c/§4.6d/§9）：
修数据让结果变差、但变真实了。 行情原先只到 2015-01-05， 使「过去 5 年」窗口在 2019 年前被静默截短（覆盖率仅 20%~67%）。 2026-10-04 已把行情回补到 2005-01-04、涨跌停/停牌到 2010， 5 年窗口覆盖率提升到 98.7%~100%。代价是全期收益从 +117.36% 降到 +92.73% —— 因为 2015 年（牛市顶 + 股灾）从「被数据缺口 挡住」变成被真实交易（−3.18%）。靠数据缺口躲过股灾不是策略能力。
实时画像闸门在两个口径下结论相反： 单条路径 −8.47pp（有害），样本外 +1.16pp（有益）。
口径 闸门开 闸门关 全期单路径总收益 +92.73% +101.20% Walk-forward 样本外均值 +1.16% −0.00% 样本外最差回撤 −22.97% −24.22% 按本项目一贯立场以样本外为准：闸门是改善。是否启用由你决定 （
entry.profile_gate.enabled）；全期剔除 1027 次买入信号。同一项数据修正，在两个口径下的「效果」相差 32.9pp （回补对样本外贡献 0 —— 7 个窗口逐窗口未变；对单路径贡献 −32.9pp）。 这是「不要采信单条路径」最有力的例证。
stock_daily的量价单位曾前后不一致（2015-2019 存「手/千元」， 2020 起存「股/元」），使流动性门槛在早年低估 1000 倍、把 2015-2019 的股票池整体清空。已修复（读取层幂等归一化 + 审计UNIT-OHLCV防回归）。
请始终以 Walk-forward 的样本外结果为主要依据，不要采信单条路径的全期数字。 详见实施状态 §4.6。
三种回测模式（不要混用）
| 模式 | 命令 | 回答的问题 |
|---|---|---|
| 单条路径 | hdiv backtest [--universe-run <id>] |
某个固定池/周期重筛下的全期表现 |
| 样本外 | hdiv backtest --mode walkforward |
参数在未知未来能否复现（过拟合检验） |
| 每日动态池 | hdiv backtest --mode daily --start 2020-01-05 |
从某天起每个交易日重新选股连续推演会怎样 |
--mode daily 的特点是股票池每天都在变：每个交易日按当时可见数据重建池子
（PIT），每个交易日判断买卖点；持仓掉出当日池子默认只减不加（不清仓），
买卖决策都会留下个股画像证据，每日入选成员落库到 hd_daily_universe。
成本要说清楚：逐日全市场筛选是重活 —— 6.7 年（约 1600 个交易日）约需 1.5 小时；1 年约 20 分钟，3 个月约 5 分钟。命令启动时会打印预计时长。 要缩短时间，可缩短区间，或把
config/backtest.yml的daily.universe_refresh_days调大（例如 5 = 每周选股、每日判断买卖 —— 这是真实的语义取舍）。详见使用手册 §5.7b。
Web 部署（前后端分离）
# 1) 归一化站点目录（归档历史 + 同步前端）
.venv/bin/python -m hdiv site normalize
# 2) 本地预览
./deploy/serve.sh start-dev # http://127.0.0.1:8099/
# 3) 生产：同步前端 + 启动后端（仅 API）
rsync -av --delete output/ user@host:/srv/hddiv/site/
./deploy/serve.sh start # 监听 127.0.0.1:8099 --api-only
nginx 需做两件事：托管 output/、把 /api 反代到后端。
配置模板见 deploy/nginx.conf.example（含子路径与站点根两种布局）。
验证：
curl http://<host>:8080/ggx/api/health # 应返回 {"ok": true, ...}
浏览器打开首页后，右上角应显示 「API 正常」；若显示「API 不可用」，
说明 nginx 的 /api 反代未生效。
静态报告（
output/reports/）通过相对路径引用assets/echarts.min.js， 因此部署时必须整体同步output/目录，不能只拷 HTML。静态报告是导出件，默认不生成（SPA 已提供同样内容）。需要离线单文件快照时 加
--html导出，文件名带 run_id，同一天多次运行不会互相覆盖。
测试
.venv/bin/python -m pytest tests/ -q
覆盖：配置校验（含 18 类非法配置必须被拒）、SQL 安全约束、表结构幂等性、 单位换算与量级检测、PIT 纪律、分红口径、回测资金对账、参数阶梯、CLI 接口契约。