Skip to content

docs: record all-A historical backfill (PR #61) #62

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
Jul 16, 2026
Merged

docs: record all-A historical backfill (PR #61) #62

Show file tree
Hide file tree
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
11 changes: 8 additions & 3 deletions AGENTS.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）、#41（数据层 D1 契约文档 + token 解析去重）、#43（数据层 D2 TushareCache specs/parsers 拆分）、#45（数据层 D3 report-only 数据质量层）、#47（数据层 D3b default-off `data-update` 质量报告钩子）、#49（数据层 D4 coverage ledger 批量写 + 进程内查找缓存）、#51（数据层 D5 opt-in 有界并发 + 全局限频器）、#53（P-I5e MMP 五分位 CSI300 独立泛化检验，负结果）、#55（P-I5f 分钟尾盘执行流动性/容量诊断，report-only）、#57（数据层 schema 注册表 + default-off drift 守卫）、#59（数据层 全A 增量 auto-warm + systemd 定时，default-off）均已 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 解析去重）、#43（数据层 D2 TushareCache specs/parsers 拆分）、#45（数据层 D3 report-only 数据质量层）、#47（数据层 D3b default-off `data-update` 质量报告钩子）、#49（数据层 D4 coverage ledger 批量写 + 进程内查找缓存）、#51（数据层 D5 opt-in 有界并发 + 全局限频器）、#53（P-I5e MMP 五分位 CSI300 独立泛化检验，负结果）、#55（P-I5f 分钟尾盘执行流动性/容量诊断，report-only）、#57（数据层 schema 注册表 + default-off drift 守卫）、#59（数据层 全A 增量 auto-warm + systemd 定时，default-off）、#61（数据层 全A 历史回填 `data-backfill`，分块/续跑/失败隔离）均已 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 @@ -262,6 +262,11 @@ data → universe → factors(特征) → alpha(合成/预测) → portfolio(+ri
- **config** `config/data_update_all_a.yaml`:全A 夜间暖;`index_weight` 只为项目回测 universe(SSE50/CSI300/CSI500)预暖,**非 universe-agnostic**(他指数回测自走 lazy read-through)。**systemd** `deploy/systemd/quant-data-update.{service,timer}`:**user** timer @ **21:00 Asia/Shanghai**(`OnCalendar` 钉时区,host 在 LA 也按上海触发,需 systemd≥239;`systemd-analyze` 验证下次 13:00 UTC=上海 21:00);**artifact-only,不装不 enable**。`docs/ops/data_update_schedule.md`:安装/enable 步骤 + LOUD preflight(先手动观察跑一次再 enable)+ **诚实稳态成本**(全A ~3 万调用/晚 ~1h,**非"≈0"**)+ 失败隔离 caveat(单票持续失败中止当晚后续端点,per-symbol 隔离归 PR-2)。
- **不变量**:`universe_scope=config` 默认 → all-A 分支永不进入(poison-pill 测试锁);`update_endpoints`/`_build_feeds`/`run_data_update` body 字节级不变;既有 data_update 测试全过;factor/alpha/portfolio/runtime 不动;phase0 `0.9600/0.8408` 不变;无 token 入 code/config/unit/doc/log/test。
- **review 两轮**(cc 接替外部 reviewer 验收):security CLEAN;code-review 无 CRIT/HIGH,修 2 MEDIUM(`index_weight` 从孤 000300 → 3 项目指数 + 明确注释;"增量≈0"表述 → 如实 ~3 万调用/晚)+ 失败隔离文档化归 PR-2。**独立重跑 771 passed / ruff clean / 20 配置 / phase0 0.9600·0.8408 / systemd-analyze TZ 验证**。**首次 live 全A warm = 用户 Stage-1 手动观察跑**,timer 确认后才 enable。
- ✅ 质量门：`pytest` **771 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 / P-I5e 仅 config（无新测试,`test_cache_config` 的 config glob 自动 +1）/ P-I5f intraday-liquidity=17（+ `test_cache_config` config glob 自动 +1）/ D1 token-dedup index-feed +2 / D2 cache-modularization +5 / D3 data-quality market=15 + intraday=12 + report=14 / D3b data-update-quality=18 / D4 coverage-ledger-scaling=13 / D5 scheduler=9 + concurrency=12 / schema-registry-guard=62 / all-A-incremental=12**）；`ruff` clean；`validate-config`（全部 20 配置含 data_update + phase_i5a + phase_i5b + phase_i5c + phase_i5d + phase_i5e + phase_i5f）+ `run-phase0`（demo）均 OK（**ic 0.9600 / annual 0.8408 不变**）。
- ✅ **数据层 盘后全A 自动拉取 —— PR-2 全A 历史回填**（**PR #61 已 merge 到 `main`**，行为保持型;新 `data-backfill` CLI 补深度历史,与 PR-1 夜间增量分离）：`qt/data_backfill.py::run_data_backfill` 把 universe 分 `chunk_size` 批,每批在**宽窗口** `[backfill.start, today]` 暖(非夜间 `today−lookback`);`include_minute` 时分钟按**全窗口**暖(非 7 天 tail,复用 I2 ≤23 天分页,不重造)。跑完全无 factor/alpha/portfolio/backtest/PanelStore。
- **per-batch 失败隔离**:批持续失败(过重试)→ secret-free 记录(批号+异常**类型**,`except Exception` 故 Ctrl-C 正常传播)并跳过——该批 gap 留缺(可续跑重取),run 继续并计 failed 批/票。**断点续跑免费**:靠 coverage ledger,重跑只补未覆盖 gap(真 cache 端到端证)。
- **`start > today` 守卫**:逆序窗口本会被 `subtract_intervals` 当"零缺口=已覆盖"→ 未来 start typo 静默 no-op;故加 loud `ValueError`(仿 `DataCfg._check_date_order`)。config `data_update.backfill: {start, chunk_size, include_minute}`(全默认 → 现存配置照常 validate);`config/data_update_all_a.yaml` 加 `backfill:` 块 + 诚实成本注(冷全A 分钟回填数小时~多日,可续跑)。ops doc 加"历史回填"节(先回填再 enable 夜间 timer)。
- **不变量**:增量 `run_data_update` 路径**字节级不变**——唯一共享改动是 `_build_scheduler`/`_build_caches` verbatim 抽取(same kwargs/顺序);49 个既有 data_update 测试原样过(main-vs-branch pytest 对照 **771→793 恰好 +22、0 既有测试被动**)。phase0 `0.9600/0.8408` 不变;缓存仍 raw-only;无 token。
- **review 两轮**(cc 接替外部 reviewer 验收):security CLEAN(失败/进度日志只 counts+异常类型);code-review 无 CRIT/HIGH(共享重构 verbatim 验证),修 2 MEDIUM(`start>today` 静默 no-op 守卫 + 失败×续跑联合测)+ LOW(summary 显并发模式)。独立重跑 **793 passed / ruff / 20 配置 / phase0 0.9600·0.8408**。**建设侧完成;live rollout(先 `data-backfill` 补史 → 手动增量 warm → enable timer)= 用户 Stage-1 driver**。
- ✅ 质量门：`pytest` **793 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 / P-I5e 仅 config（无新测试,`test_cache_config` 的 config glob 自动 +1）/ P-I5f intraday-liquidity=17（+ `test_cache_config` config glob 自动 +1）/ D1 token-dedup index-feed +2 / D2 cache-modularization +5 / D3 data-quality market=15 + intraday=12 + report=14 / D3b data-update-quality=18 / D4 coverage-ledger-scaling=13 / D5 scheduler=9 + concurrency=12 / schema-registry-guard=62 / all-A-incremental=12 / all-A-backfill=22**）；`ruff` clean；`validate-config`（全部 20 配置含 data_update + phase_i5a + phase_i5b + phase_i5c + phase_i5d + phase_i5e + phase_i5f）+ `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 起不再互覆盖）。
- 路线图下一步：**MMP 暂缓推进（I5e 负结果）**（I5e 已在独立 universe CSI300 同窗口机器冻结复跑 → 单调性 **FAILS/反转**（Spearman −0.5,Q5 高 MMP 最差,合成 Q5−Q1 累计 −26.77%）;I5d 的 CSI500 单调性疑 universe/regime 特异、**非稳健** → **在出现 disjoint 窗口 / 第三 universe 的正向证据前,不把 MMP 当稳健或可交易信号推进**;新 intraday 因子候选只作显式 EXPLORATORY 工作）；**I5f 已落地 → I5g（可选,须单独显式 goal）**（I5f 已加 report-only 执行流动性/容量诊断,实测 10M RMB/5% 参与率下约半数 SSE50 单分钟 desired trade 容量不足;**强制 partial-fill / volume-cap（真正约束成交）= 可能的 I5g,仅在单独显式 goal 后启动**,本阶段未做,不声称已实现）；**盘后全A auto-fetch**（数据正确性审计 PASS——D3 质量层实测 80GB 真实缓存结构干净、ann_date PIT 轴 100%、跨 shard schema 无漂移;PR #59 = PR-1 全A 增量 auto-warm + systemd @21:00 default-off 已落地;**PR-2 = 全A 历史回填**——分块/断点续跑/分钟全窗口 + per-symbol 失败隔离,进行中）；**P4-3 follow-up**（fina 按 ann_date 建披露日历 ledger 以去掉启发式 tail / data-update summary 落 cache-stats artifact）；**数据层 D6**（D1+D2+D3+D3b+D4+D5 已 merge：契约文档化 + token 解析收敛 + `TushareCache` specs/parsers 拆分 + report-only `data/quality/` 质量层 + default-off `data-update` 质量报告钩子 + coverage ledger `record_many` 批量写 + 进程内查找缓存 + opt-in 有界并发 + 全局限频器 + **schema 注册表/default-off drift 守卫(PR #57)**；剩余数据层 follow-up：schema 守卫接 live `data-update` 暖跑路径(当前仅接 pipeline/回测) + 分钟 schema 守卫;**D6**=`PanelStore` append/partition / 可选物化派生面板存储,**仅当因子研究需要可复用派生面板时才启动**——均尚未实现）；研究侧：更长 holdout 滚动复检 / 成本模型细化。
- 路线图下一步：**MMP 暂缓推进（I5e 负结果）**（I5e 已在独立 universe CSI300 同窗口机器冻结复跑 → 单调性 **FAILS/反转**（Spearman −0.5,Q5 高 MMP 最差,合成 Q5−Q1 累计 −26.77%）;I5d 的 CSI500 单调性疑 universe/regime 特异、**非稳健** → **在出现 disjoint 窗口 / 第三 universe 的正向证据前,不把 MMP 当稳健或可交易信号推进**;新 intraday 因子候选只作显式 EXPLORATORY 工作）；**I5f 已落地 → I5g（可选,须单独显式 goal）**（I5f 已加 report-only 执行流动性/容量诊断,实测 10M RMB/5% 参与率下约半数 SSE50 单分钟 desired trade 容量不足;**强制 partial-fill / volume-cap（真正约束成交）= 可能的 I5g,仅在单独显式 goal 后启动**,本阶段未做,不声称已实现）；**盘后全A auto-fetch**（数据正确性审计 PASS——D3 质量层实测 80GB 真实缓存结构干净、ann_date PIT 轴 100%、跨 shard schema 无漂移;PR #59 = PR-1 全A 增量 auto-warm + systemd @21:00 default-off 已落地;**PR #61 = PR-2 全A 历史回填**——分块/断点续跑/分钟全窗口 + per-symbol 失败隔离 + `start>today` 守卫,已落地。**建设侧完成,剩 live rollout = 用户 Stage-1**:先 `data-backfill` 补全A 历史(可续跑)→ 手动跑增量 warm 观察 → enable systemd timer）；**P4-3 follow-up**（fina 按 ann_date 建披露日历 ledger 以去掉启发式 tail / data-update summary 落 cache-stats artifact）；**数据层 D6**（D1+D2+D3+D3b+D4+D5 已 merge：契约文档化 + token 解析收敛 + `TushareCache` specs/parsers 拆分 + report-only `data/quality/` 质量层 + default-off `data-update` 质量报告钩子 + coverage ledger `record_many` 批量写 + 进程内查找缓存 + opt-in 有界并发 + 全局限频器 + **schema 注册表/default-off drift 守卫(PR #57)**；剩余数据层 follow-up：schema 守卫接 live `data-update` 暖跑路径(当前仅接 pipeline/回测) + 分钟 schema 守卫;**D6**=`PanelStore` append/partition / 可选物化派生面板存储,**仅当因子研究需要可复用派生面板时才启动**——均尚未实现）；研究侧：更长 holdout 滚动复检 / 成本模型细化。
Loading