Files

T

claude_dev 3d20489761 docs: 新增 vnpy 量化平台第一阶段 PRD

沉淀 superpowers brainstorming 多轮讨论：
- 项目初衷、核心原则（不改 vnpy/面向未来/复用 v1 数据）
- 第一阶段范围（A 股回测+策略开发闭环）与后续 spec 规划
- 8 条架构决策（ADR）：不引 Qlib/不用 Celery/vnpy 零改造/
  复用 v1 数据丢弃 v1 回测/国金模拟独立/弃内嵌架构/
  webtrader 按需启用/因子层可插拔
- v1 数据资产继承清单 + 数据源踩坑黑名单
- 风险与待决策项

2026-07-05 10:54:15 +08:00

11 KiB

Raw Blame History

Sanguo VeighNa 量化平台 PRD

文档信息

日期：2026-07-05

状态：Draft（待用户确认）

范围：vnpy 服务端 + Web 适配量化平台 · 第一阶段（A 股回测 + 策略开发闭环）

来源：superpowers brainstorming 多轮澄清（含 8 份调研报告）

1. 项目背景与目标

1.1 初衷（用户原话）

"我希望把 vnpy 作为服务端部署在 nas docker 上，利用其完整的量化能力，我们构建我们自己的 web 应用来完成量化的投研、回测、策略开发、模拟交易，甚至实盘。这里边我不想对 vnpy 做改造，还是希望通过适配来利用其完整的能力。"

1.2 核心原则（用户约束，逐条记录，不可违背）

不改造 vnpy：通过适配层利用其完整能力，不打补丁、不改 vnpy 核心
面向未来：架构要支撑多因子策略研究的海量回测
复用 v1 数据资产：v1（sanguo_vnpy）已下载的数据 + 数据源踩坑经验必须继承
批判性参考 v1：v1 有不合理设计，v1 回测代码从未成功；仅继承数据层，回测代码不参考
NAS Docker 分层部署：应用层/镜像层分离，不动外网链路（frpc/socat/Caddy/vnpy.mysanguo.top）

1.3 优先级（用户明确）

回测（最高）
策略开发
模拟验证
实盘（不急）

1.4 市场侧重

A 股各种金融产品（股票/ETF/可转债/期权）：主线
美股港股：其次
期货：不急

2. 范围定义

2.1 第一阶段（当前 spec 范围）

A 股回测 + 策略开发闭环，含：

数据层（继承 v1）
因子/研究层（vnpy.alpha + Alphalens 补 IC/IR）
回测层（vnpy BacktestingEngine + 多进程优化）
Web API 层（FastAPI 自建适配）
Web 前端（因子研究 / 回测配置 / 多进程优化 / 结果展示）
NAS Docker 部署

成功标准：在 Web 上配置因子 + 策略 + 参数 → 触发海量回测（多进程）→ 展示回测报告（统计 / 净值曲线 / 成交明细）。

2.2 后续阶段（独立 spec，不在本 PRD 范围）

阶段	内容	触发条件
Spec 2	国金客户端模拟环境（实时模拟盘）	用户提供国金客户端
Spec 3	实盘（A 股 gateway：tora/xtp）	模拟验证通过
Spec 4	美股港股 / 期货扩展	业务需要

用户原话："我会提供你国金客户端进行模拟环境搭建，这个需要作为一个单独的 topic"

2.3 非目标（第一阶段明确不做）

实时模拟盘（国金，独立 spec）
实盘交易
期货为主的产品
多用户 / 权限模型（先单用户）

3. 关键架构决策（ADR）

ADR-1: 不引入 Qlib，使用 vnpy.alpha

决策：多因子研究用 vnpy 4.4.0+ 内置 vnpy.alpha 模块，不引入 Qlib
依据（源码核实）：vnpy/alpha/ 含 Alpha158（源自 Qlib）/ Alpha101 因子库、横截面算子（cs_rank/mean/std）、ML 模型（Lasso/LightGBM/MLP）、多标的回测引擎、实盘 AlphaStrategy
理由：vnpy.alpha 已受 Qlib 启发且功能完备，保持 vnpy 单一生态，避免多系统集成
修正记录：多因子框架调研曾建议引 Qlib，源码核实后推翻

ADR-2: 回测并发用 multiprocessing + Ray，不用 Celery

决策：海量回测用 vnpy 官方 run_optimization（multiprocessing）起步，需要跨机分布式时上 Ray
依据（源码核实）：run_optimization 支持 max_workers 多进程 + output=False headless；vnpy 社区分布式主流是 Ray
理由：回测是计算密集，Celery 偏 IO 任务队列；vnpy 社区无 Celery 回测案例；multiprocessing 是官方原生
修正记录：曾推荐 Celery+Redis，调研后推翻

ADR-3: vnpy 引擎层零改造

决策：vnpy 核心/官方组件不改动，只做 FastAPI + 前端适配层
依据：用户多次强调"不改造 vnpy 通过适配"；vnpy 官方组件（alpha/ctabacktester）能力完备

ADR-4: 复用 v1 数据层，丢弃 v1 回测代码

决策：v1 的 data_platform（数据源/fallback/validator/增量更新/已下载数据）完整继承；v1 回测代码（src/backtest-service）完全不参考
依据：用户明确"v1 回测没成功过""v1 有很多设计不合理，不要被误导"
继承清单：
- ✅ 直接 copy：validator.py、fallback.py、docs/data-platform/
- 🟡 适配 vnpy 4.4.0：daily_all_update.py、import_vnpy_*、vnpy_local_data_adapter.py
- ❌ 丢弃：v1 所有回测代码

ADR-5: 模拟环境（国金）作为独立 spec

决策：国金客户端模拟环境不混入第一阶段
依据：用户明确"单独 topic"；模拟需用户提供客户端

ADR-6: 不用当前 sanguo_web 的内嵌架构

决策：当前 sanguo_web（FastAPI 进程直接持有 MainEngine）重构为分离架构
依据：内嵌架构导致 mock 补丁、uvicorn fork 崩溃（threads can only be started once）、Web 与引擎耦合
新架构：vnpy 引擎调用封装为独立服务/模块，Web 层只做适配

ADR-7: vnpy_webtrader 按需启用 + 模式参考（不融合不抛弃）

决策：第一阶段（回测/因子）暂不启用 webtrader；后续实盘/行情阶段候选启用；自建 Web 层不基于 webtrader 的 web.py，但参考其「FastAPI + register MainEngine 方法」范式
依据：webtrader 只覆盖交易+行情，第一阶段用不上；扩展 webtrader web.py = 改造 vnpy（违背初衷）；它是 vnpy 官方组件，实盘阶段 add_app(WebTraderApp) 零改造即用
定位：留作工具箱，按需启用（非融合、非抛弃）

ADR-8: 因子层可插拔扩展

决策：因子定义、因子库、因子分析器三层均设计为可插拔扩展点，支持未来引入更多因子
扩展点：
- 因子定义统一接口：遵循 vnpy.alpha 的 DataProxy + cs_function 范式，自定义因子按此接口注册
- 因子库可插拔：Alpha158/101（vnpy 内置）+ 自定义因子 + 未来因子，统一注册机制
- 因子分析器可插拔：Alphalens 作为首个 analyzer（IC/IR），预留接口，未来加其他 analyzer 不改架构
依据：用户明确"未来会引入更多因子，扩展性希望要有"；Alphalens 不写死

4. 技术栈选型（分层）

层	选型	依据
数据层	继承 v1（NAS parquet/SQLite + 多源 fallback + validator + 增量更新）	v1 资产调研
因子/研究层	vnpy.alpha（Alpha158/101 + 横截面 + ML）+ Alphalens（补 IC/IR）	源码核实
回测层	vnpy `BacktestingEngine` + `run_optimization`（multiprocessing）	源码核实 headless
海量回测扩展	multiprocessing 起步 → Ray（分布式，未来）	社区主流
Web API	自建 FastAPI	—
前端	待定（当前原生 HTML+JS，多因子 UI 复杂，考虑 Vue/React）	design 阶段决策
部署	NAS Docker（应用层/镜像层分离，容器本地读数据）	部署文档

5. 数据资产（v1 继承，已确认）

5.1 NAS 数据实况（`/volume1/stock/`）

数据	量级	跨度
日线 parquet	59985 文件 / 1.1GB	2010–2026，~5000 只/年
15min parquet	10457 文件 / 1.5GB	2025-09 ~ 2026-04，5193 只
vnpy SQLite `quant_trading.db`	1.4GB / 1281 万行	DbBarData 表（vnpy 原生格式）

5.2 数据源踩坑黑名单（必须继承，v1 血泪）

数据源	坑	v2 策略
新浪	datalen 800 硬限 + 已失效（返回 Error/2条）	暂禁
腾讯	amount 经常返回 0	保底备源
东方财富	Mac 直连被拒 + 需 Windows UA + 4s 限频	当天实时主源
BaoStock	无超时会卡死进程 + T+1 延迟	加超时后作全量历史主源（唯一无反爬）

5.3 关键利好

v1 的 SMB 坑（1.4GB SQLite 读超时、写被 SIGKILL）在 v2 NAS Docker 容器本地读下自动消失（容器直读 /volume1/stock/，不走网络）。

5.4 数据校验（继承 validator.py，7 条 fatal 规则）

D1: 价格 > 0
D2: OHLC 一致性（high ≥ max(O,C)，low ≤ min(O,C)）
D3: volume ≥ 0
D6: 日期不重复（保留最新）
D7: 非未来日期
R1/R7: 实时行情字段完整性

6. 调研发现摘要

6.1 vnpy 组件能力（源码核实）

组件	能力	备注
`vnpy.alpha`	多因子（Alpha158/101 + 横截面 + ML + 回测 + 实盘）	生产级，第一阶段核心
`vnpy_ctabacktester`	CTA 回测 + `run_optimization`（多进程，headless）	参数优化用
`vnpy_portfoliostrategy`	跨期套利 / 期权组合	非横截面选股（曾误解）
`vnpy_webtrader`	FastAPI REST + WS，交易+行情	不含策略/回测
`vnpy_rpcservice`	通用 RPC 通道	论坛称 demo，非首选

6.2 v1 架构教训（v2 必须避免）

v1 的 sanguo_web 是内嵌架构（FastAPI 直接持有 MainEngine）→ mock 补丁 + uvicorn fork 崩溃（threads can only be started once）
v1 回测代码从未跑通
v2 必须分离：vnpy 引擎层（独立）+ Web 适配层

7. 约束与风险

7.1 约束

不改造 vnpy 核心
NAS Docker 部署，不动外网链路
面向未来（海量回测可水平扩展）
复用 v1 数据资产

7.2 风险

风险	等级	缓解
vnpy.alpha 是 4.4.0+ 新模块，A 股适配（T+1/100股/涨跌停/停牌）未验证	中	第一阶段早期做 spike 验证
vnpy 4.x → 4.4.0 数据接口适配	中	继承 v1 适配器时测试
BaoStock 无超时卡死	中	加超时机制
run_optimization 多进程在 Docker 内资源限制	低	配置 max_workers
前端技术栈未定	低	design 阶段定

8. 待决策项（design 阶段敲定）

Web 前端技术栈（原生 JS / Vue / React）
用户模型（单用户 / 多用户）
回测结果存储（SQLite / PostgreSQL / 文件）
Alphalens 集成方式（独立服务 / 嵌入）
参数扫描 UI 形态
回测任务的提交/查询/取消 API 设计

9. 后续 spec 规划

当前：第一阶段回测+策略开发闭环 → design → plan → 实现
Spec 2：国金客户端模拟环境（待客户端）
Spec 3：实盘（A 股 gateway）
Spec 4：美股港股 / 期货扩展

10. 参考调研报告（本 PRD 的事实基础）

vnpy 服务端暴露组件调研（webtrader / rpcservice / scripttrader）
vnpy 量化能力栈程序化可行性
webtrader / rpcservice 源码核实（主线 clone）
SANGUO_VNPY 数据资产调研
v1 数据接入层深挖（含踩坑黑名单 + 继承清单）
vnpy 二开回测实践调研（multiprocessing + Ray）
多因子框架对比调研（Qlib / alphalens / vnpy）
vnpy.alpha / portfoliostrategy / ctabacktester 源码核实

变更记录

日期	变更	来源
2026-07-05	初稿，沉淀 brainstorming 全部讨论	superpowers brainstorming

11 KiB Raw Blame History Unescape Escape