docs(phase2): 因子/回测层完成报告（13 task, 54+4 passed, 覆盖率 81%, 端到端冒烟通过）

2026-07-06 11:47:50 +08:00
parent 8041d4a9a5
commit d9c4f15bc9
1 changed files with 47 additions and 0 deletions
@@ -0,0 +1,47 @@
+# Phase 2 因子/回测层 — 完成报告
+
+**日期**：2026-07-06  **状态**：✅ DONE  **分支**：feat/factor-backtest
+
+## 目标
+因子层（vnpy.alpha 封装）+ CTA 回测层 + 任务编排 + 轻量 FastAPI，形成因子研究与策略回测完整闭环。
+
+## 交付清单
+| 包 | 模块 | 职责 |
+|----|------|------|
+| sanguo_factor | data_adapter / alpha_lab / registry / library / analyzer | BarData→AlphaLab 转换 + AlphaLab 封装 + 因子表达式注册（7 内置）+ Alphalens 分析骨架 |
+| sanguo_backtest | result_store / cta_engine / cta_optimizer | SQLite+parquet 存储 + BacktestingEngine wrapper + run_optimization wrapper |
+| sanguo_orchestrator | task / pool / runner | 任务状态机 + TaskPool + Orchestrator 调度器 |
+| sanguo_api | schemas / app / routes | 轻量 FastAPI 5 路由（无 JWT/WS/前端） |
+
+## Spike 验证（3/3 PASS，落地前必做）
+- **S3 peewee**：PASS — alphalens-reloaded 0.4.6 + vnpy_sqlite peewee 4.1.1 共存，无 empyrical-reloaded 约束
+- **S1 vnpy.alpha A 股**：PASS — AlphaLab 存取 117 bars + ts_mean(close,5) 因子计算
+- **S2 run_optimization**：PASS — vnpy_ctastrategy 1.4.1 + spawn pool + max_workers
+
+## Spike 关键修正（覆盖 plan 假设）
+1. AlphaLab 列名 `open/high/low/close`（**非** `_price`）
+2. 表达式语法 `ts_mean(close,5)`（ts_/cs_ 算子 + 列名，**非** polars `pl.col`）
+3. `run_optimization` 是 `BacktestingEngine` 方法（vnpy 4.4.0 重构，非顶层函数，非 vnpy_ctabacktester）
+4. peewee 冲突不存在（容器装原版兼容）
+
+## 测试结果
+- **54 本地 passed**（factor/backtest/orchestrator/api，Python 3.14）
+- **4 容器 passed**（data_adapter，Python 3.10 + polars）
+- **端到端冒烟 PASS**：result_store + 7 因子 + API + data_adapter 真实 A 股 117 bars
+- **覆盖率 81%**（TOTAL 370 stmts）
+
+## 部署产出
+- 容器 `sanguo_vnpy_v2:with-backtester` 6.93GB（vnpy_ctastrategy 1.4.1 + pytest + vnpy_sqlite）
+- 安装目录 rsync 同步（NAS /volume1/homes/admin/.sanguo_projects/sanguo_vnpy_v2）
+- 测试策略：本地写代码（3.14）+ 容器跑 polars/vnpy.alpha 依赖测试
+
+## 已知 Tech Debt
+| 项 | 影响 |
+|----|------|
+| alpha_lab/analyzer 骨架 | alphalens tears 完整集成留 Phase 3（AlphaDataset 流程 S1 已证，tears pipeline 待补） |
+| optimize/factor 路由占位 | 返回 {task_id:"pending"}，submit_optimize/submit_factor 留 Phase 3 |
+| runner 同步执行 | _run_sync 非真异步，multiprocessing pool 留 Phase 3 |
+| datareader _VNPY_SRC bug fix | Task 8 修正（".." 两级→一级），Phase 1 conftest 兜底未暴露 |
+
+## Phase 3 衔接
+Web API 完整化（JWT/WS/Vue 前端）+ 真异步 multiprocessing pool + 组合回测 + 国金模拟独立 spec。