sanguo_vnpy_v2/docs/superpowers/reports/2026-07-06-phase2-factor-backtest-completion.md

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。