# 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 |