sanguo/sanguo_vnpy_v2
2
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
94de7191f58a92214ad52d72285830d4c1f42904
sanguo_vnpy_v2/docs/superpowers/specs/2026-07-05-vnpy-quant-platform-design.md
T
claude_dev f255e5062e docs: 新增 vnpy 量化平台第一阶段架构设计 
基于 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 11:08:59 +08:00

8.7 KiB
Raw Blame History

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
Reference in New Issue View Git Blame Copy Permalink