simon
fce725e13c
从 Point-in-Time 股票筛选到统一 Web 前端的完整链路： 筛选 → 画像 → 策略 → 回测 → Walk-forward → 绩效分析 → 报告/前端。 架构 - 数据层与策略层分离；策略代码不写 SQL，只经 data/repo.py 取数 - 所有业务阈值集中在 config/*.yml，代码零硬编码（字段写错直接报错） - 报告只做「run_id → SQL → 渲染」，不做任何计算，数字可追溯 - 前后端分离：output/ 静态站点 + hdiv web 提供的 REST API 数据安全 - 只增不删：SQL 钩子拦截 DELETE/DROP/TRUNCATE，并有源码扫描测试守护 - qlib 原有表只读，本项目数据写入 hd_ 前缀表 - 回补使用 INSERT IGNORE，保证既有行零改动 - .env 存密钥且已 gitignore；output/、logs/、.venv/ 不入库 交付物 - 30 张 hd_* 表、7 个 YAML 配置、283 项自动化测试 - 统一 Web 前端（hash 路由 SPA）+ nginx 部署配置与 launchd 托管脚本 如实声明的限制 - 策略缺少稳定的样本外超额收益（Walk-forward 7 窗口均值 -0.95%， 基准 +2.29%）；其价值体现在回撤控制，而非超额收益 - 涨跌停/停牌约束仅覆盖 2019 年起；index_weight 尚未填充 - AI Agent 层（plan.md 第四版 P8）未实现 详见 docs/user-guide.md 与 docs/implementation-status.md。
130 lines
4.4 KiB
Markdown
130 lines
4.4 KiB
Markdown
# 高股息回测系统
|
||
|
||
A 股 **高股息 + 安全边际 + 估值均值回归** 策略的研究与回测系统。
|
||
|
||
从 Point-in-Time 股票筛选 → 个股特性画像 → 策略定义 → 历史回测 →
|
||
Walk-forward 样本外验证 → 绩效与敏感性分析 → **统一 Web 前端**，全链路打通。
|
||
|
||
采用**前后端分离**：前端为 `output/` 下的单页应用（hash 路由，nginx 直接托管），
|
||
后端为 `hdiv web` 提供的 REST API（nginx 反代 `/api`）。
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
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
|
||
|
||
# 审计 → 打开 output/index.html
|
||
.venv/bin/python -m hdiv audit
|
||
```
|
||
|
||
完整用法见 **[使用手册](docs/user-guide.md)**。
|
||
|
||
---
|
||
|
||
## 文档
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| **[使用手册](docs/user-guide.md)** | 安装、配置、命令、报告解读、故障排查 |
|
||
| [实施状态](docs/implementation-status.md) | 交付清单、验收映射、已修复问题、**实测结论与限制** |
|
||
| [开发计划](docs/development-plan.md) | 架构设计、数据库设计、分阶段计划 |
|
||
| [需求原文](docs/plan.md) | 项目的原始方案与验收标准 |
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
```text
|
||
config/ ★ 所有可调参数（YAML，代码零硬编码）
|
||
src/hdiv/ 代码：数据层、筛选、画像、策略、回测、分析、报告
|
||
templates/ HTML 模板（Jinja2，离线）
|
||
assets/ 图表库（ECharts，本地化，不依赖 CDN）
|
||
output/ ★ 报告输出（部署这个目录）
|
||
sql/ 建表 SQL 副本（供人工审查）
|
||
tests/ 262 项自动化测试
|
||
docs/ 文档
|
||
```
|
||
|
||
---
|
||
|
||
## 三条设计原则
|
||
|
||
| 原则 | 落实方式 |
|
||
|---|---|
|
||
| **配置零硬编码** | 任何业务阈值只出现在 `config/*.yml`；字段名写错直接报错 |
|
||
| **只增不删** | SQL 钩子拦截 `DELETE`/`DROP`/`TRUNCATE`；源码扫描测试守护 |
|
||
| **无未来函数** | 所有取数必经 `data/repo.py`，PIT 纪律有负例测试 |
|
||
|
||
---
|
||
|
||
## 重要提示
|
||
|
||
**本系统的实测结论是：策略没有稳定的样本外超额收益。**
|
||
|
||
全期回测（2015–2026）显示 +114.80% / CAGR 6.73%，
|
||
但 7 窗口 Walk-forward 的样本外收益均值仅 **−0.95%**（基准 +2.29%，超额 **−3.24pp**）。
|
||
|
||
它真正的价值在于**回撤控制**（样本外最差 −24.62%，基准同期 −46%~−52%）——
|
||
更像降低波动的配置工具，而非超额收益来源。
|
||
|
||
**请始终以 Walk-forward 的样本外结果为主要依据，不要采信单条路径的全期数字。**
|
||
详见[实施状态 §4.6](docs/implementation-status.md)。
|
||
|
||
---
|
||
|
||
## Web 部署（前后端分离）
|
||
|
||
```bash
|
||
# 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](deploy/nginx.conf.example)**（含子路径与站点根两种布局）。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
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，同一天多次运行不会互相覆盖。
|
||
|
||
---
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
.venv/bin/python -m pytest tests/ -q
|
||
```
|
||
|
||
覆盖：配置校验（含 18 类非法配置必须被拒）、SQL 安全约束、表结构幂等性、
|
||
单位换算与量级检测、PIT 纪律、分红口径、回测资金对账、参数阶梯、CLI 接口契约。
|