Skip to content

docs: record data-layer D1 contracts progress #42

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
StackOverFlow11 merged 1 commit into from
Jun 19, 2026
Merged

docs: record data-layer D1 contracts progress #42

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ data → universe → factors(特征) → alpha(合成/预测) → portfolio(+ri

## 开发约定
- **交流中文**；代码/注释/commit message 用**英文**。
- **Git**：feature 分支 + PR。**PR #1（P0+P1）、#2（P2-1）、#3（P2-2）、#4（进度文档）、#5（P2-3）、#6（进度文档）、#7（P2-4）、#8（进度文档）、#9（P3-1）、#10（进度文档）、#11（P3-2）、#12（P3-3）、#13（进度文档）、#14（P3-4）、#15（进度文档）、#16（P3-5）、#17（进度文档）、#18（P3-6）、#19（P3-7）、#20（进度文档）、#21（P3-8）、#22（进度文档）、#23（P4-1）、#24（进度文档）、#25（P4-2）、#28（tushare 权限/限频探测 + capability registry）、#29（I1–I4 分钟级 intraday pipeline，4 commit 一 PR）、#30（进度文档）、#31（P4-3 因子支撑端点缓存 + 21:00 data updater，2 commit 一 PR）、#33（P-I5a 事件驱动回测架构重构 + opt-in 分钟尾盘 event model，4 commit 一 PR）、#35（P-I5b 分钟尾盘执行期 raw stk_limit 涨跌停可行性，4 commit 一 PR）、#37（P-I5c MMP 分钟因子端到端 opt-in alpha）、#39（P-I5d MMP 五分位分组回测 standalone，含 I5c plumbing）均已 merge 到 `main`**。commit 用 conventional 格式，**无 attribution**（不加 Co-Authored-By）。
- **Git**：feature 分支 + PR。**PR #1（P0+P1）、#2（P2-1）、#3（P2-2）、#4（进度文档）、#5（P2-3）、#6（进度文档）、#7（P2-4）、#8（进度文档）、#9（P3-1）、#10（进度文档）、#11（P3-2）、#12（P3-3）、#13（进度文档）、#14（P3-4）、#15（进度文档）、#16（P3-5）、#17（进度文档）、#18（P3-6）、#19（P3-7）、#20（进度文档）、#21（P3-8）、#22（进度文档）、#23（P4-1）、#24（进度文档）、#25（P4-2）、#28（tushare 权限/限频探测 + capability registry）、#29（I1–I4 分钟级 intraday pipeline，4 commit 一 PR）、#30（进度文档）、#31（P4-3 因子支撑端点缓存 + 21:00 data updater，2 commit 一 PR）、#33（P-I5a 事件驱动回测架构重构 + opt-in 分钟尾盘 event model，4 commit 一 PR）、#35（P-I5b 分钟尾盘执行期 raw stk_limit 涨跌停可行性，4 commit 一 PR）、#37（P-I5c MMP 分钟因子端到端 opt-in alpha）、#39（P-I5d MMP 五分位分组回测 standalone，含 I5c plumbing）、#41（数据层 D1 契约文档 + token 解析去重）均已 merge 到 `main`**。commit 用 conventional 格式，**无 attribution**（不加 Co-Authored-By）。
- **不过度设计**：按路线图 MVP 先打通一条端到端链路，再加层（architecture.html §11，Phase 0→3）。
- **secrets** 一律走外部 `.config.json`；repo `.gitignore` 已排除数据产物(`*.parquet`等)、缓存、`tmp/`（仅留架构文档）。
- 文件小而专（<800 行），immutable 优先。
Expand Down Expand Up @@ -213,6 +213,10 @@ data → universe → factors(特征) → alpha(合成/预测) → portfolio(+ri
- **真实 run（CSI500 `000905.SH`，2021-06-01→2026-05-31，59 月调仓，~95min）**：`covered=892/995`（**103 只分钟未覆盖成分被 drop 并披露，5 年窗口不缩短**）/ `stk_mins_live_calls=0`（cache-only）/ `fee_rate=0.001`；final NAV Q1→Q5 **0.9822 / 1.0423 / 1.0495 / 1.1275 / 1.1577**（**单调 Spearman 1.0000**，等额 rank 桶对 MMP 肥尾稳健）；合成 Q5−Q1 spread +0.29%/期、累计 **+17.15%**；限价覆盖 52,584/52,584（严格 `require_price_limit_coverage=true` 过）。
- ⚠️ **caveat（保留，不移除）**：单因子/单重叠 5 年窗口/单 universe,无调参/无 robustness/无 learned 权重;`covered=892/995`(103 drop);`stk_mins_live_calls=0`;**Q5−Q1 是合成 long-only 腿差,非单独执行的 dollar-neutral 组合**;执行模型仍缺 partial-fill / liquidity / volume-cap;**Q5>Q1 不作业绩声明**。这是项目首个正向 intraday 信号,下一步需独立泛化(CSI300/中证1000 或 disjoint 窗口,机器冻结)。
- **PR 处置**：#37（I5c）随 #39 落地后其 head 成 `main` 祖先,GitHub **自动 merged**(非本次手动 merge);#38（i5d stacked on i5c,base 非 main）已被 #39 **完全取代**(零 remaining commit/file diff vs main),保持 **OPEN 待清理**(未获显式授权关闭)。
- ✅ 质量门：`pytest` **577 passed**（P0=97 / P1=78 / P2-1=22 / P2-2=22 / P2-3=14 / P2-4=8 / P3-1=10 / P3-2=18 / P3-3=16 / P3-4=15 / P3-5=22 / P3-6=27 / P3-7=25+1 throttle / P3-8=8 / P4-1=28 / P4-2=17 / **intraday I1 schema=14 + feed=9 / I2 cache=10 / I3 aggregate=13 / I4 execution=10 / P4-3 cache=10 + updater=7 / P-I5a event-backtest=19 / P-I5b exec-feasibility=16 / P-I5c mmp-minute=18 / P-I5d mmp-quintile=19**）；`ruff` clean；`validate-config`（全部 17 配置含 data_update + phase_i5a + phase_i5b + phase_i5c + phase_i5d）+ `run-phase0`（demo）均 OK（**ic 0.9600 / annual 0.8408 不变**）。
- ✅ **数据层 D1 — cache/store 契约文档化 + token 解析去重**（**PR #41 已 merge 到 `main`**，行为保持型重构,非研究/非数据语义变更）：数据层第一步低风险清理,只做两件事——把 `cache` vs `store` 边界写成可提交契约,并把重复的 token 解析收敛到既有 `data/feed/secret.py::read_token`。
- **契约文档** `docs/data/data_layer_contracts.md`：`data/cache` = 可复用 raw endpoint 缓存 / SoT;`data/store/PanelStore` = per-run canonical 面板 artifact(非 raw lake,`artifacts/data/*.parquet` 不当缓存权威);缓存只存 raw;`front_adjust` / PIT 成分 / PIT SW 行业 / `ann_date` 财务对齐 / raw 涨跌停检查 / factor·alpha·portfolio·runtime 数学全在下游;`data-update` 只暖缓存不跑研究;data-quality + 并发是后续阶段(不声称已实现)。
- **token 去重**：`tushare_feed.py` 删掉重复的 module-level `_lookup_dotted` + 内联 json/Path 解析(`_read_token` 变 `read_token(...)` 一行 wrapper);`index_feed.py` 不再从 `tushare_feed` 导入私有 `_lookup_dotted`,`_client` 直接走 `read_token`。`_lookup_dotted` 全仓清零;6 个 tushare feed(feed/index/flags/fina/intraday/covariates)统一走 `secret.read_token`。构造签名 / `__repr__` token 安全 / fetch+cache 路径全不变;+2 窄测试锁定 index feed 真实 token 路径(fake config、不碰网络、不泄漏)。
- **行为保持**：phase0 `ic 0.9600 / annual 0.8408` 不变;无数据抓取/缓存语义/factor/alpha/portfolio/runtime/report 变更。**显式非目标(留给 D2+)**：`TushareCache` 内部拆分 / endpoint schema registry / data-quality validator / 并发 / `CoverageLedger` 存储变更 / `PanelStore` append·partition。**D2(`TushareCache` 模块化)是下一步工程阶段,本 PR 未实现。**
- ✅ 质量门：`pytest` **579 passed**（P0=97 / P1=78 / P2-1=22 / P2-2=22 / P2-3=14 / P2-4=8 / P3-1=10 / P3-2=18 / P3-3=16 / P3-4=15 / P3-5=22 / P3-6=27 / P3-7=25+1 throttle / P3-8=8 / P4-1=28 / P4-2=17 / **intraday I1 schema=14 + feed=9 / I2 cache=10 / I3 aggregate=13 / I4 execution=10 / P4-3 cache=10 + updater=7 / P-I5a event-backtest=19 / P-I5b exec-feasibility=16 / P-I5c mmp-minute=18 / P-I5d mmp-quintile=19 / D1 token-dedup index-feed +2**）；`ruff` clean；`validate-config`（全部 17 配置含 data_update + phase_i5a + phase_i5b + phase_i5c + phase_i5d）+ `run-phase0`（demo）均 OK（**ic 0.9600 / annual 0.8408 不变**）。
- ⚠️ 剩余（已显式披露）：日线 only、demo 路径非真数据、旧三因子无信号（P3-3/P3-4 实证;但其组合在 2024-2026 holdout 上 SSE50/CSI300/CSI500 全正、CSI500 高达 +17.8%——小样本/regime 翻转的持续例证）;value/低波信号获得**独立样本符号级确认**（P3-7 SSE50/CSI300 量级衰减;P3-8 CSI500 泛化成立且更强），组合级盈利能力仍未确立（排名跨 cell 翻转）;subset 报告文件名已可配置（P3-8 起不再互覆盖）。
- 路线图下一步：**I5d 独立泛化**（MMP 五分位单调性是项目首个正向 intraday 信号,但只一个重叠 5 年窗口/一个 universe → 在第二个 universe（CSI300/中证1000）和/或 disjoint 窗口上机器冻结复跑分组回测,使单调性可归因于因子而非该 regime,沿 P3-7/P3-8 独立确认先例）；**I5b/执行 follow-up**（执行期 feasibility 可再扩 partial-fill / liquidity / volume cap，size-aware 读数前补）；**P4-3 follow-up**（fina 按 ann_date 建披露日历 ledger 以去掉启发式 tail / updater 加 stk_mins 历史回填 / data-update summary 落 cache-stats artifact）；**数据层 D1+**（cache/store 契约已文档化,token 解析已收敛,后续 D2+ 再做 cache 内部拆分/schema registry/data-quality/并发）；研究侧：更长 holdout 滚动复检 / 成本模型细化。
- 路线图下一步：**I5d 独立泛化**（MMP 五分位单调性是项目首个正向 intraday 信号,但只一个重叠 5 年窗口/一个 universe → 在第二个 universe（CSI300/中证1000）和/或 disjoint 窗口上机器冻结复跑分组回测,使单调性可归因于因子而非该 regime,沿 P3-7/P3-8 独立确认先例）；**I5b/执行 follow-up**（执行期 feasibility 可再扩 partial-fill / liquidity / volume cap，size-aware 读数前补）；**P4-3 follow-up**（fina 按 ann_date 建披露日历 ledger 以去掉启发式 tail / updater 加 stk_mins 历史回填 / data-update summary 落 cache-stats artifact）；**数据层 D2**（D1 已 merge：cache/store 契约文档化 + token 解析收敛；下一步 `TushareCache` 内部模块化,之后再 schema registry / data-quality validator / 并发——均尚未实现）；研究侧：更长 holdout 滚动复检 / 成本模型细化。