From 3d204897618fa0bad37d19699d65e09911620fe2 Mon Sep 17 00:00:00 2001 From: claude_dev Date: Sun, 5 Jul 2026 10:54:15 +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?=20PRD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 沉淀 superpowers brainstorming 多轮讨论： - 项目初衷、核心原则（不改 vnpy/面向未来/复用 v1 数据） - 第一阶段范围（A 股回测+策略开发闭环）与后续 spec 规划 - 8 条架构决策（ADR）：不引 Qlib/不用 Celery/vnpy 零改造/ 复用 v1 数据丢弃 v1 回测/国金模拟独立/弃内嵌架构/ webtrader 按需启用/因子层可插拔 - v1 数据资产继承清单 + 数据源踩坑黑名单 - 风险与待决策项 --- .../2026-07-05-vnpy-quant-platform-prd.md | 230 ++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-05-vnpy-quant-platform-prd.md diff --git a/docs/superpowers/specs/2026-07-05-vnpy-quant-platform-prd.md b/docs/superpowers/specs/2026-07-05-vnpy-quant-platform-prd.md new file mode 100644 index 0000000..c303a68 --- /dev/null +++ b/docs/superpowers/specs/2026-07-05-vnpy-quant-platform-prd.md @@ -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 |