docs(phase1): 数据层完成报告 + 端到端冒烟脚本

2026-07-05 23:47:07 +08:00
parent 88295011f9
commit 6da8a55b5e
2 changed files with 118 additions and 0 deletions
@@ -0,0 +1,77 @@
+# Phase 1 数据层 — 完成报告
+
+**日期**：2026-07-05
+**状态**：✅ DONE（本地 16 passed + 端到端冒烟通过）
+**分支**：已 merge to master（`20e2437`）
+
+## 1. 目标
+
+把 v1（sanguo_vnpy）散落的数据资产（BaoStock parquet + vnpy SQLite db）收拢成统一的、可被 vnpy 原生调用的数据读取层；打通 NAS Docker 端到端链路。
+
+**范围约束**：只做数据"读/写/调度/校验"，不做回测/策略/Web（留 Phase 2+）。
+
+## 2. 交付清单
+
+### 代码模块（`sanguo_data/`）
+
+| 模块 | 职责 | 关键设计 |
+|------|------|---------|
+| `config.py` | 加载 `data_platform.yaml` | 统一配置入口 |
+| `datareader.py` | 读日 K → `BarData` | `read_parquet_daily` + `read_db_daily`（配 vnpy SETTINGS）+ `guess_exchange`（代码前缀判 SSE/SZSE） |
+| `datafeed.py` | 在线数据源抓取 | BaoStock + 东财/腾讯 fallback；`_fetch_baostock_with_timeout` 子进程隔离（修 v1 卡死坑） |
+| `datafeed/` | 数据源实现子包 | 可扩展 |
+| `datawriter.py` | 数据落盘 | parquet 年分区 + vnpy sqlite 原子写 |
+| `database/` | vnpy 数据库适配子包 | sqlite 路径配置 |
+| `scheduler.py` | `UpdateScheduler` | 增量更新 + 断点续传 + 熔断 |
+| `validator.py` | 数据完整性校验 | 缺口/异常值检测 |
+
+### 测试（`tests/data/`，16 passed）
+
+`test_config` / `test_datareader` / `test_datafeed` / `test_datawriter` / `test_scheduler` / `test_validator` / `test_spike_vnpy44`
+
+## 3. 关键 Fix（收尾阶段）
+
+| Gap | commit | 说明 |
+|-----|--------|------|
+| read_db_daily 没配 vnpy database 路径 | `339d85a` | 默认空 database.db 读不到 NAS 真实数据 → 加 `SETTINGS["database.database"]` 配置 |
+| spike 测试被全局 SETTINGS 污染 | `8829501` | read_db_daily 改全局 SETTINGS → spike 用 monkeypatch mock load_bar_data 隔离 |
+
+## 4. 部署产出（NAS Docker）
+
+- 容器 `sanguo_vnpy_v2` 重建加挂载 `/volume1/stock`（RW）
+- 镜像 `sanguo_vnpy_v2:with-sqlite`（docker commit 保 vnpy_sqlite，避免 NAS 弱 CPU pip 卡死）
+- 外网链路 `vnpy.mysanguo.top` 恢复正常（未改动原代理/转发设计）
+
+## 5. 端到端验证（真实数据）
+
+`scripts/smoke_e2e.py` 在临时容器内读 NAS `quant_trading.db`：
+
+```
+600000.SSE: 541 条
+000001.SZSE: 563 条
+300750.SZSE: 564 条
+区间: 2024-01-01 ~ 2026-06-30
+```
+
+## 6. 风险与兜底
+
+- **v1 db 被容器改**：当前 `quant_trading.db` 1.66→2.13GB（容器 RW 下 peewee create_tables 副作用）。
+- **兜底**：`/volume1/stock/sanguo_vnpy/data/` 含多个历史备份 `quant_trading_*.db.bak`（1.5G 各，20260519~20260522 + pre_interval_migration），原始可恢复。数据完整性已验证。
+
+## 7. 已知 Tech Debt（留后续 phase）
+
+| 项 | 影响 |
+|----|------|
+| `_load_stock_list` NotImplementedError | 部署前 copy v1，后续需补实现 |
+| datawriter 一致性回滚 | final triage 待定 |
+| validator row-by-row 全量校验性能 | 增量场景 OK，海量回测时需优化 |
+| peewee 版本冲突告警 | empyrical-reloaded 要 `peewee<3.17.4`，vnpy_sqlite 装 4.1.1 — **可能影响 Phase 2 因子层** |
+
+## 8. Phase 2 衔接点
+
+Phase 1 提供的下游可用接口：
+- `read_db_daily(symbol, start, end, cfg) → list[BarData]` — vnpy 原生 BarData，可直接喂 vnpy.alpha / ctabacktester
+- `read_parquet_daily(...)` — parquet 快速读取路径
+- `UpdateScheduler` — 增量数据更新
+
+Phase 2（因子/回测层）应基于这些接口构建，遵循 PRD ADR：vnpy.alpha 集成、因子层可插拔、multiprocessing+Ray 编排、不引 Qlib。