# 02 - 系统架构设计

**版本**: v1.0
**日期**: 2026-04-29

---

## 1. 架构总览

```
┌─────────────────────────────────────────────────────────────┐
│                     三国量化团队（7个Agent）                    │
│  诸葛亮 · 庞统 · 张飞 · 关羽 · 赵云 · 司马懿 · 姜维            │
└───────────┬─────────────────────────────────┬───────────────┘
            │ 提交策略                         │ 查看结果
            ▼                                 ▼
┌───────────────────────┐         ┌───────────────────┐
│   回测API服务          │         │  OpenClaw Gateway  │
│   FastAPI :8088       │         │  任务调度/通信      │
│   /api/backtest/*     │         └───────────────────┘
└───────────┬───────────┘
            │ 调用
            ▼
┌───────────────────────┐
│   vnpy BacktestingEngine │  ← vnpy 4.x原生回测引擎
│   CTA策略回测            │
└───────────┬───────────┘
            │ 读取数据
            ▼
┌───────────────────────┐
│   数据层               │
│   SQLite / akshare     │  ← 本地数据 + 实时数据
└───────────────────────┘

            所有服务运行在：
┌─────────────────────────────────────┐
│        群晖 NAS Docker 容器           │
│  192.168.2.154                       │
│  sanguo_vnpy:with-scripts 镜像       │
│  restart: unless-stopped             │
└─────────────────────────────────────┘
```

## 2. 分层架构

```
┌────────────────────────────────────┐
│  适配层 (src/)                      │  ← 我们的代码
│  ├── backtest-service/  回测API服务  │
│  ├── adapters/          数据适配器   │
│  └── scripts/           启动脚本     │
├────────────────────────────────────┤
│  vnpy框架层 (pip install vnpy)      │  ← 开源框架，不修改
│  ├── BacktestingEngine  回测引擎     │
│  ├── CtaTemplate       策略基类      │
│  ├── BaseDatafeed      数据接口      │
│  └── BaseGateway       交易网关      │
├────────────────────────────────────┤
│  基础设施层 (docker/)               │
│  ├── Dockerfile         镜像构建     │
│  ├── entrypoint.sh      容器启动     │
│  └── requirements/      依赖管理     │
└────────────────────────────────────┘
```

## 3. 核心设计决策

### 3.1 适配层 vs Fork

| 方案 | 适用场景 | 当前选择 |
|------|---------|---------|
| **适配层**（继承/封装） | 新策略、新数据源、新网关 | ✅ 当前采用 |
| **Fork vnpy** | 修改回测引擎核心、修改事件机制 | 🔜 预留 |

原则：优先通过继承和封装实现需求，vnpy接口不满足时再考虑fork。

### 3.2 数据架构

```
数据获取层（赵云负责）
    │
    ├── akshare（实时行情）
    ├── tushare（历史数据）
    └── 本地CSV/Parquet
    │
    ▼
数据适配层（src/adapters/）
    │
    ├── vnpy_local_data_adapter.py  ← 实现BaseDatafeed接口
    │
    ▼
数据存储层
    │
    └── SQLite（vnpy标准数据库）
```

### 3.3 多用户隔离

每个用户独立进程对，通过Nginx反向代理统一入口：

```
用户        RPC端口   Web端口   Nginx路径
诸葛亮       2010      8001     /zhugeliang/
庞统         2020      8002     /pangtong/
司马懿       2030      8003     /simayi/
张飞         2040      8004     /zhangfei/
关羽         2050      8005     /guanyu/
赵云         2060      8006     /zhaoyun/
姜维         2070      8007     /jiangwei/
```

### 3.4 容器化部署

```
sanguo_vnpy 容器
├── 8888  Jupyter Lab（开发环境）
├── 8088  回测API服务（FastAPI）
├── 8000  WebTrader（预留）
├── 2222  SSH（运维通道）
└── /app/scripts/backtest_service  ← volume挂载代码
```

## 4. 技术选型

| 组件 | 选型 | 理由 |
|------|------|------|
| 量化框架 | vn.py 4.x | 开源、社区活跃、架构成熟 |
| API服务 | FastAPI + uvicorn | 异步高性能、自动文档 |
| 数据库 | SQLite | 轻量、vnpy原生支持 |
| 数据源 | akshare + tushare | 免费A股数据 |
| 容器 | Docker | 环境隔离、可移植 |
| 部署 | 群晖NAS | 团队已有硬件、7×24运行 |

---

*下一步：[03-detailed-design.md](03-detailed-design.md)*