docs: 新增 vnpy 量化平台第一阶段 PRD
沉淀 superpowers brainstorming 多轮讨论： - 项目初衷、核心原则（不改 vnpy/面向未来/复用 v1 数据） - 第一阶段范围（A 股回测+策略开发闭环）与后续 spec 规划 - 8 条架构决策（ADR）：不引 Qlib/不用 Celery/vnpy 零改造/ 复用 v1 数据丢弃 v1 回测/国金模拟独立/弃内嵌架构/ webtrader 按需启用/因子层可插拔 - v1 数据资产继承清单 + 数据源踩坑黑名单 - 风险与待决策项
This commit is contained in:
@@ -0,0 +1,230 @@
|
||||
# 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. 回测（最高）
|
||||
2. 策略开发
|
||||
3. 模拟验证
|
||||
4. 实盘（不急）
|
||||
|
||||
### 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 规划
|
||||
1. **当前**：第一阶段回测+策略开发闭环 → design → plan → 实现
|
||||
2. **Spec 2**：国金客户端模拟环境（待客户端）
|
||||
3. **Spec 3**：实盘（A 股 gateway）
|
||||
4. **Spec 4**：美股港股 / 期货扩展
|
||||
|
||||
---
|
||||
|
||||
## 10. 参考调研报告（本 PRD 的事实基础）
|
||||
1. vnpy 服务端暴露组件调研（webtrader / rpcservice / scripttrader）
|
||||
2. vnpy 量化能力栈程序化可行性
|
||||
3. webtrader / rpcservice 源码核实（主线 clone）
|
||||
4. SANGUO_VNPY 数据资产调研
|
||||
5. v1 数据接入层深挖（含踩坑黑名单 + 继承清单）
|
||||
6. vnpy 二开回测实践调研（multiprocessing + Ray）
|
||||
7. 多因子框架对比调研（Qlib / alphalens / vnpy）
|
||||
8. vnpy.alpha / portfoliostrategy / ctabacktester 源码核实
|
||||
|
||||
---
|
||||
|
||||
## 变更记录
|
||||
| 日期 | 变更 | 来源 |
|
||||
|------|------|------|
|
||||
| 2026-07-05 | 初稿，沉淀 brainstorming 全部讨论 | superpowers brainstorming |
|
||||
Reference in New Issue
Block a user