sanguo/sanguo_vnpy_v2
3
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7bbba554f8beeb5b9de540bfecef7aadd1b0bdbd
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

180 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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