From f255e5062ea016bfae04d15af4e7294f40f5dd31 Mon Sep 17 00:00:00 2001 From: claude_dev Date: Sun, 5 Jul 2026 11:08:59 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20vnpy=20=E9=87=8F?= =?UTF-8?q?=E5=8C=96=E5=B9=B3=E5=8F=B0=E7=AC=AC=E4=B8=80=E9=98=B6=E6=AE=B5?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E8=AE=BE=E8=AE=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 基于 PRD 落地分层架构： - 数据层（继承 v1，双存储 parquet+SQLite，cron+Web 更新） - 因子/回测层（vnpy.alpha 可插拔扩展 + BacktestingEngine 多进程优化） - Web API 层（FastAPI 自建 + JWT + 回测任务 pool） - 前端（Vue 3 + Vite + Naive UI，替换原生） - 部署（NAS Docker，uvicorn 单进程避 fork 坑） 含早期 spike 与 ADR 对应表 --- .../2026-07-05-vnpy-quant-platform-design.md | 179 ++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-05-vnpy-quant-platform-design.md diff --git a/docs/superpowers/specs/2026-07-05-vnpy-quant-platform-design.md b/docs/superpowers/specs/2026-07-05-vnpy-quant-platform-design.md new file mode 100644 index 0000000..284b1aa --- /dev/null +++ b/docs/superpowers/specs/2026-07-05-vnpy-quant-platform-design.md @@ -0,0 +1,179 @@ +# Sanguo VeighNa 量化平台 Design（架构设计） + +> **对应 PRD**：`docs/superpowers/specs/2026-07-05-vnpy-quant-platform-prd.md` +> **范围**：第一阶段（A 股回测 + 策略开发闭环） +> **日期**：2026-07-05 +> **状态**：Draft（待用户 review） + +--- + +## 1. 整体架构 + +``` +┌──────────────────────────────────────────────────────────────┐ +│ Web 前端（Vue 3 + Vite + Naive UI） │ +│ 因子研究 · 回测配置 · 多进程优化 · 结果展示 · 数据管理 │ +└──────────────────────────┬───────────────────────────────────┘ + │ HTTP / WebSocket +┌──────────────────────────┴───────────────────────────────────┐ +│ Web API 层（FastAPI 自建适配） │ +│ 认证(JWT) · 回测任务编排 · 因子查询 · 数据查询 · WS 推送 │ +└──────────────────────────┬───────────────────────────────────┘ + │ headless 程序化调用 +┌──────────────────────────┴───────────────────────────────────┐ +│ vnpy 引擎层（不改造） │ +│ vnpy.alpha(因子+横截面+ML) · BacktestingEngine+优化 │ +│ · run_optimization(multiprocessing) │ +└──────────────────────────┬───────────────────────────────────┘ + │ BarData +┌──────────────────────────┴───────────────────────────────────┐ +│ 数据层（继承 v1，NAS 容器本地读） │ +│ DataFeed(多源) · Validator · DataWriter/Reader · Scheduler │ +│ parquet(年分区) + SQLite(DbBarData) │ +└──────────────────────────────────────────────────────────────┘ + │ Docker 容器本地读 /volume1/stock/（无 SMB） +``` + +**核心原则**：vnpy 引擎层零改造；适配层（FastAPI + 前端）只做封装和编排；数据层完整继承 v1。 + +--- + +## 2. 数据层 + +### 2.1 组件（4 个单一职责，继承 v1 重组） +| 组件 | 职责 | 来源 | +|------|------|------| +| **DataFeed** | 多源接入（东财主 / BaoStock+超时 / 腾讯备），限流、重试、降级 | 继承 v1 `fallback.py` | +| **Validator** | 7 条 fatal 校验（D1-D7/R1/R7） | 直接 copy v1 `validator.py` | +| **DataWriter / DataReader** | 双存储读写：parquet（年分区）+ SQLite DbBarData | 继承 v1，适配 vnpy 4.4.0 | +| **UpdateScheduler** | 每日增量 + 断点续传 + 失败告警 | 继承 v1 增量逻辑 | + +### 2.2 数据流 +``` +更新链（每日 cron + Web 手动补）: + DataFeed → Validator → DataWriter → parquet + SQLite +读取链（回测时）: + DataReader → 统一输出 vnpy BarData → BacktestingEngine / vnpy.alpha +``` + +### 2.3 决策 +- **2.1 双存储保留**：parquet 利 pandas 批量研究（多因子），SQLite DbBarData 利 vnpy 引擎原生读取 +- **2.2 cron 自动 + Web 手动补** +- **BaoStock 加超时**（修 v1 卡死坑） +- **配置集中 YAML**（v1 散落代码 → v2 `config/data_platform.yaml`） + +--- + +## 3. 因子 / 回测层 + +### 3.1 因子层（vnpy.alpha + 可插拔扩展，落实 ADR-8） +| 子层 | 实现 | 扩展点 | +|------|------|--------| +| 因子定义 | 遵循 `vnpy.alpha` 的 `DataProxy` + `cs_function` 范式 | 自定义因子按此接口注册 | +| 因子库 | Alpha158/101（vnpy 内置） | 自定义因子库 + 未来因子，统一注册机制 | +| 因子分析器 | Alphalens（IC/IR/分层回测） | analyzer 接口可插拔，未来加其他不改架构 | + +### 3.2 回测层 +- **引擎**：vnpy `BacktestingEngine`（不改造） +- **多进程优化**：`run_optimization` / `run_ga_optimization`（`max_workers`，`output=False` headless） +- **海量扩展**：multiprocessing 起步 → Ray 分布式（未来，按需） + +### 3.3 回测任务编排 +``` +Web 提交回测 → API 层入任务队列 → multiprocessing pool 执行 + → 结果落库（SQLite 统计 + 文件净值/成交）→ WS 推送进度 +``` + +--- + +## 4. Web API 层 + +### 4.1 框架 +- **FastAPI 自建**（参考 webtrader 的「FastAPI + register 引擎方法」模式，不用 webtrader web.py） +- **uvicorn 单进程**（避开 fork 崩溃坑），回测用独立 multiprocessing pool + +### 4.2 路由（REST + WS） +| 模块 | 路由 | 功能 | +|------|------|------| +| 认证 | `/api/v1/auth/*` | JWT 登录/校验（单用户起步） | +| 因子 | `/api/v1/factor/*` | 因子查询/注册/分析（接 Alphalens） | +| 回测 | `/api/v1/backtest/*` | 提交/查询/取消/结果 | +| 数据 | `/api/v1/data/*` | 数据查询/手动补数据 | +| WS | `/ws/` | 回测进度/（未来）行情成交推送 | + +### 4.3 回测结果存储 +- **SQLite**：回测统计指标（收益/夏普/回撤等）+ 任务状态 +- **文件（JSON/parquet）**：净值曲线 + 成交明细（大数据，不入库） + +--- + +## 5. 前端 + +### 5.1 技术栈（推荐） +- **Vue 3 + Vite + Naive UI**（或 Element Plus） +- 理由：多因子/回测是中后台型应用，Vue 生态成熟、学习曲线低于 React、表格/图表组件齐全 +- **替换当前原生 HTML+JS**（当前 sanguo_web/static 前端） + +### 5.2 页面 +| 页面 | 功能 | +|------|------| +| 因子研究 | 因子查询/注册/IC-IR 分析（Alphalens 可视化） | +| 回测配置 | 选因子/策略/参数/标的/区间，提交回测 | +| 回测结果 | 统计指标 + 净值曲线 + 成交明细 | +| 数据管理 | 数据覆盖范围 + 手动补数据 + 更新日志 | +| （未来）交易 | 实盘/模拟（后续 spec） | + +--- + +## 6. 部署 + +### 6.1 NAS Docker（应用层/镜像层分离，沿用现有方案） +- 容器挂载 `/volume1/stock` → `/app/data`（本地读，无 SMB） +- 镜像：Python 3.10 + vnpy 4.4.0 + `vnpy.alpha` + `vnpy_ctabacktester` + Alphalens +- 代码 bind-mount，迭代 rsync + `docker restart` + +### 6.2 进程模型 +- **uvicorn 单进程**（Web API），避开多 worker fork 的 `threads can only be started once` 坑 +- **回测任务用 multiprocessing pool**（独立于 uvicorn 进程） +- 不动外网链路（frpc/socat/Caddy/vnpy.mysanguo.top） + +--- + +## 7. 早期 Spike（风险验证，落地前必做） +| Spike | 验证内容 | 风险等级 | +|-------|---------|---------| +| vnpy.alpha A 股适配 | T+1/100股/涨跌停/停牌 在 alpha 模块的支撑度 | 中 | +| vnpy 4.4.0 数据接口 | v1 适配器升级到 4.4.0（Interval/DbBarData） | 中 | +| run_optimization Docker 多进程 | 容器内 max_workers 行为与资源占用 | 低 | + +> Spike 在实施初期（数据层/因子层）穿插进行，发现问题立即停下确认。 + +--- + +## 8. 实施顺序（概要，详细 plan 由 writing-plans 出） +1. **数据层**：移植 v1（DataFeed/Validator/Writer/Reader/Scheduler）+ 适配 4.4.0 + BaoStock 超时 + YAML 配置 +2. **因子/回测层**：vnpy.alpha 集成 + 自定义因子注册接口 + analyzer 接口（Alphalens）+ 回测任务编排 +3. **Web API 层**：FastAPI 路由 + JWT + 回测任务 pool + WS +4. **前端**：Vue 3 脚手架 + 各页面 +5. **部署**：Docker 镜像 + 挂载 + 单进程 uvicorn + spike 验证 + +--- + +## 9. 与 PRD ADR 的对应 +| ADR | Design 落点 | +|-----|------------| +| ADR-1 不引 Qlib（用 vnpy.alpha） | §3.1 | +| ADR-2 multiprocessing + Ray（不用 Celery） | §3.2 / §3.3 | +| ADR-3 vnpy 引擎零改造 | §1 核心原则 | +| ADR-4 复用 v1 数据丢弃 v1 回测 | §2 | +| ADR-5 国金模拟独立 spec | 不在本 design 范围 | +| ADR-6 弃内嵌架构 | §1 / §4.1（uvicorn 单进程） | +| ADR-7 webtrader 按需启用 | §4.1（参考模式，不用 web.py） | +| ADR-8 因子层可插拔 | §3.1 扩展点 | + +--- + +## 变更记录 +| 日期 | 变更 | 来源 | +|------|------|------| +| 2026-07-05 | 初稿，基于 PRD + 多轮 brainstorming | superpowers brainstorming |