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
parent 3d20489761
commit f255e5062e
1 changed files with 179 additions and 0 deletions
@@ -0,0 +1,179 @@
+# 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 |