From 83ca15b57bca6c88205e6ea5a328c7ae99c16e0c Mon Sep 17 00:00:00 2001 From: claude_dev Date: Sun, 5 Jul 2026 23:47:07 +0800 Subject: [PATCH] =?UTF-8?q?docs(phase2):=20=E5=9B=A0=E5=AD=90/=E5=9B=9E?= =?UTF-8?q?=E6=B5=8B=E5=B1=82=20design=EF=BC=88brainstorming=203=20?= =?UTF-8?q?=E8=BD=AE=E7=A1=AE=E8=AE=A4=EF=BC=8C=E5=BE=85=20review=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...026-07-05-phase2-factor-backtest-design.md | 235 ++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-05-phase2-factor-backtest-design.md diff --git a/docs/superpowers/specs/2026-07-05-phase2-factor-backtest-design.md b/docs/superpowers/specs/2026-07-05-phase2-factor-backtest-design.md new file mode 100644 index 0000000..fbe28dc --- /dev/null +++ b/docs/superpowers/specs/2026-07-05-phase2-factor-backtest-design.md @@ -0,0 +1,235 @@ +# Phase 2 因子/回测层 Design（架构设计） + +> **对应 PRD**：`docs/superpowers/specs/2026-07-05-vnpy-quant-platform-prd.md` +> **承接**：Phase 1 数据层（已 DONE，见 `docs/superpowers/reports/2026-07-05-phase1-data-layer-completion.md`） +> **范围**：因子层 + CTA 回测层 + 任务编排 + 轻量 FastAPI +> **日期**：2026-07-05 +> **状态**：Draft（待用户 review） + +--- + +## 0. 范围决策（brainstorming 已确认） + +| 决策点 | 选择 | 理由 | +|--------|------|------| +| Phase 2 范围 | 因子层 + CTA 回测层 + 任务编排 + 轻量 FastAPI（完整闭环） | 用户要"因子+回测全做" | +| 回测范式 | 因子分层回测 + CTA 策略回测两条都要 | 覆盖多因子研究 + 策略回测两个闭环 | +| 编排边界 | 含轻量 FastAPI（提交/查询，无 JWT/WS/前端） | 计算层稳了再套完整 Web（Phase 3） | +| 代码组织 | 方案 A 分层解耦（4 包） | 单一职责、独立可测、vnpy 零改造 | + +--- + +## 1. 架构总览 + +``` +┌──────────────────────────────────────────────┐ +│ sanguo_api (轻量 FastAPI) │ +│ POST /backtest/cta · /optimize · /factor │ +│ GET /task/{id} · /task/{id}/result │ +└──────────────┬───────────────────────────────┘ + │ submit_task +┌──────────────┴───────────────────────────────┐ +│ sanguo_orchestrator (编排层) │ +│ multiprocessing pool · 任务状态机 · runner │ +└──────┬───────────────────────────┬───────────┘ + │ │ +┌──────┴────────────┐ ┌──────────┴────────────┐ +│ sanguo_factor │ │ sanguo_backtest │ +│ vnpy.alpha 适配 │ │ BacktestingEngine │ +│ 因子注册(可插拔) │ │ run_optimization │ +│ Alphalens 分析 │ │ result_store │ +└──────┬────────────┘ └──────────┬────────────┘ + │ │ + └───────────┬───────────────┘ + │ read_db_daily / read_parquet_daily +┌──────────────────┴───────────────────────────┐ +│ Phase 1 数据层（已 DONE） │ +└──────────────────────────────────────────────┘ +``` + +**核心原则**（继承自 PRD/design）： +- vnpy 引擎层零改造（ADR-3），适配层只包装 +- 因子层可插拔（ADR-8） +- 多进程 + Ray（不用 Celery，ADR-2） +- 不引 Qlib（用 vnpy.alpha，ADR-1） + +**两条回测路径物理隔离**： +- 因子分层回测 → `sanguo_factor.analyzer`（Alphalens IC/IR/分层收益） +- CTA 策略回测 → `sanguo_backtest.cta_engine`（BacktestingEngine 时间序列） + +--- + +## 2. 组件设计 + +### 2.1 `sanguo_factor/`（因子层） + +| 模块 | 职责 | 关键接口 | +|------|------|---------| +| `alpha_adapter.py` | vnpy.alpha 适配（DataProxy + cs_function 范式） | 内部，封装 vnpy.alpha 数据接入 | +| `registry.py` | 因子注册机制（`@register_factor` 装饰器，ADR-8 可插拔） | `register_factor(name, fn)` / `get_factor(name)` | +| `library.py` | Alpha158/101 内置因子 + 自定义因子统一注册 | `list_factors()` / `list_categories()` | +| `analyzer.py` | Alphalens 适配（IC/IR/分层回测），analyzer 接口可插拔 | `compute_factors(symbols, names, start, end) → DataFrame`
`analyze_factor(values, fwd_returns) → FactorReport` | + +**因子注册范式**（遵循 vnpy.alpha）： +```python +@register_factor("ma5", category="trend") +def ma5(proxy: DataProxy, symbol: str, dt: datetime) -> float: + # cs_function 范式 + ... +``` +自定义因子按此接口注册，与 Alpha158/101 内置因子统一管理。 + +**扩展点**：analyzer 接口可插拔——未来加非 Alphalens 分析器不改架构。 + +### 2.2 `sanguo_backtest/`（回测层，CTA 路径） + +| 模块 | 职责 | 关键接口 | +|------|------|---------| +| `cta_engine.py` | BacktestingEngine wrapper（单标的策略回测，headless） | `run_cta_backtest(strategy, symbol, params, start, end) → BacktestResult` | +| `cta_optimizer.py` | run_optimization wrapper（参数网格，`max_workers`，`output=False`） | `run_cta_optimization(strategy, symbol, grid, start, end) → list[OptResult]` | +| `result_store.py` | 结果存储：SQLite 统计 + parquet 净值/成交 | `save_result(result) → id` / `load_result(id)` / `list_results(filter)` | + +**结果存储 schema**（SQLite `backtest_stats` 表）： +- 任务字段：`id, task_id, type(cta/optimize/factor), status, created_at` +- 策略字段：`strategy, symbol, params(json), start, end` +- 指标字段：`return, sharpe, max_drawdown, win_rate, ...` +- 文件指针：`equity_path(parquet), trades_path(parquet)` +- 错误信息：`error_msg(text, 任务 failed 时记录异常)` + +> 净值曲线 + 成交明细不入库（大数据），存 parquet 文件，db 存路径指针。 + +**因子层范围边界**：本 design 因子层只到 **Alphalens 分层分析**（IC/IR/分层收益），**不含组合回测**（选股→加权→调仓的主动组合管理）。组合回测是更复杂的范式，留待未来 phase。 + +### 2.3 `sanguo_orchestrator/`（编排层） + +| 模块 | 职责 | +|------|------| +| `pool.py` | multiprocessing pool（基于 S2 spike 结果定 max_workers 策略） | +| `task.py` | 任务状态机：`pending → running → done/failed` | +| `runner.py` | 调度器：分发 cta_backtest / cta_optimization / factor_analysis | + +**接口**： +- `submit_task(task_spec) → task_id`（异步，立即返回） +- `get_task_status(task_id) → TaskStatus` +- `get_task_result(task_id) → Result` + +### 2.4 `sanguo_api/`（轻量 FastAPI） + +| 路由 | 功能 | +|------|------| +| `POST /api/v1/backtest/cta` | 提交 CTA 回测任务 | +| `POST /api/v1/backtest/optimize` | 提交参数优化任务 | +| `POST /api/v1/factor/analyze` | 提交因子分析任务 | +| `GET /api/v1/task/{id}` | 查询任务状态 | +| `GET /api/v1/task/{id}/result` | 获取任务结果 | + +**不含**（留 Phase 3）：JWT 认证、WS 进度推送、Vue 前端。 + +--- + +## 3. 数据流 + +``` +因子分析闭环： + read_db_daily → compute_factors(多 symbol) → analyze_factor(Alphalens) + → FactorReport(IC/IR/分层收益) → 报告文件(parquet + html) + +CTA 回测闭环： + read_db_daily → BacktestingEngine(strategy, params) + → 统计指标入 SQLite + 净值/成交入 parquet + +参数优化闭环： + read_db_daily → run_optimization(grid, max_workers) + → 多组结果入 SQLite + 最优组合标记 + +API 触发链： + FastAPI 收请求 → orchestrator.submit_task → pool 异步执行 + → 结果落库 → GET /task/{id} 轮询状态/结果 +``` + +--- + +## 4. Spike 前置（Phase 2 第一步，落地前必做） + +| 顺序 | Spike | 验证内容 | 风险 | Fail 的 fallback | +|------|-------|---------|------|-----------------| +| **S3 先** | peewee 版本冲突 | Alphalens(empyrical-reloaded 要 peewee<3.17.4) vs vnpy_sqlite(peewee 4.1.1) 能否共存 | 中 | alphalens-reloaded 替代 / venv 隔离 / 降级 peewee | +| **S1** | vnpy.alpha A 股支撑度 | T+1/100 股/涨跌停/停牌 在 alpha 模块的支撑度 | 中 | 自建轻量因子层（pandas + ta-lib） | +| **S2** | run_optimization 多进程 | 容器内 `max_workers` 行为 + NAS 弱 CPU 资源占用 | 低 | 降级单进程 + 自建 pool | + +**S3 最先**：依赖冲突不解决，Alphalens 装不上，S1 无法跑。 +**S1 关键路径**：决定因子层方案 A 可行性，fail 则 fallback 自建因子层（影响范围限 `sanguo_factor`，不影响 `sanguo_backtest`）。 + +--- + +## 5. 错误处理 + +| 场景 | 策略 | +|------|------| +| 数据缺失 | 复用 Phase 1 `validator`，缺失数据任务直接 `failed` | +| 因子计算异常 | 单因子失败隔离（try/except + 记录），不影响其他因子 | +| 回测异常 | 捕获 → 任务状态 `failed` → 错误信息入 `backtest_stats.error_msg` | +| 多进程子进程崩溃 | 主进程感知（`Pool.apply_async` callback/errback）→ 任务标记 `failed` | +| API 参数非法 | Pydantic 校验 → 422 返回明确错误 | + +--- + +## 6. 测试策略 + +| 类型 | 范围 | 工具 | +|------|------|------| +| 单元测试 | 每组件独立（mock vnpy 引擎、mock pool） | pytest，复用 Phase 1 conftest | +| 集成测试 | 因子计算 + CTA 回测端到端（真实 vnpy，小数据集） | pytest + 真实 vnpy_v4.4.0 | +| Spike | S1/S2/S3 风险探测（非 pass/fail 测试，是验证 task） | 独立 spike script | +| 覆盖率 | ≥ 80% | pytest-cov | + +--- + +## 7. 关键风险 + +| 风险 | 等级 | 缓解 | +|------|------|------| +| vnpy.alpha 不支持 A 股特性 | 中 | S1 spike 前置，fail 则 `sanguo_factor` fallback 自建 | +| NAS 弱 CPU（braswell 2 核）海量回测慢 | 中 | S2 评估 max_workers，接口预留 Ray 分布式（Phase 3+） | +| peewee 冲突阻塞 Alphalens | 中 | S3 前置解决 | +| BacktestingEngine headless 调用坑（fork/Qt） | 低 | Phase 1 已验证 Python 3.14 + vnpy 4.4.0 不拉 Qt；S2 复验 | + +--- + +## 8. 与 PRD ADR 对应 + +| ADR | 本 design 落点 | +|-----|---------------| +| ADR-1 不引 Qlib（用 vnpy.alpha） | §2.1 因子层基于 vnpy.alpha | +| ADR-2 multiprocessing + Ray（不用 Celery） | §2.3 pool.py，§7 Ray 预留 | +| ADR-3 vnpy 引擎零改造 | §1 核心原则，§2 各 wrapper 只包装 | +| ADR-4 复用 v1 数据丢弃 v1 回测 | §3 数据流复用 Phase 1 接口 | +| ADR-8 因子层可插拔 | §2.1 registry.py + analyzer 接口 | + +--- + +## 9. Phase 1 衔接 + +Phase 2 全部基于 Phase 1 提供的下游接口构建： +- `read_db_daily(symbol, start, end, cfg) → list[BarData]` — vnpy 原生 BarData，直接喂 vnpy.alpha / BacktestingEngine +- `read_parquet_daily(...)` — parquet 快速读取路径（因子批量计算用） +- `UpdateScheduler` — 数据增量更新（回测前确保数据新鲜） + +--- + +## 10. 实施顺序（概要，详细 plan 由 writing-plans 出） + +1. **Spike 前置**：S3(peewee) → S1(vnpy.alpha A 股) → S2(run_optimization) +2. **因子层** `sanguo_factor`：alpha_adapter + registry + library + analyzer +3. **回测层** `sanguo_backtest`：cta_engine + cta_optimizer + result_store +4. **编排层** `sanguo_orchestrator`：pool + task + runner +5. **API 层** `sanguo_api`：5 路由 FastAPI +6. **集成 + 端到端冒烟** + +--- + +## 变更记录 + +| 日期 | 变更 | 来源 | +|------|------|------| +| 2026-07-05 | 初稿，基于 brainstorming 3 轮决策 | superpowers brainstorming |