# 03 - 详细设计

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

---

## 1. 回测服务模块（src/backtest-service/）

### 1.1 模块职责

将vnpy的BacktestingEngine封装为HTTP API服务，支持策略提交、任务调度、结果查询。

### 1.2 模块结构

```
src/backtest-service/
├── main.py              # FastAPI应用入口 + 生命周期管理
├── api.py               # API路由定义
├── executor.py          # vnpy回测执行器（核心）
├── models.py            # Pydantic数据模型
├── config.py            # 配置管理
├── task_queue.py        # 任务队列（线程池调度）
└── result_storage.py    # 结果持久化（磁盘存储）
```

### 1.3 核心流程

```
用户提交策略 → API接收 → 生成task_id → 入队pending
                                          │
                                     worker线程取出
                                          │
                                 executor.execute_backtest()
                                          │
                              ┌───────────┴───────────┐
                              │ 加载策略代码             │
                              │ 创建BacktestingEngine   │
                              │ 设置参数（合约/周期/资金） │
                              │ engine.run_backtesting() │
                              │ 收集结果统计             │
                              │ 生成图表（资金曲线）      │
                              └───────────┬───────────┘
                                          │
                              结果写入磁盘 → 用户查询
```

### 1.4 API接口

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/backtest/submit` | POST | 提交回测任务 |
| `/api/backtest/status/{task_id}` | GET | 查询任务状态 |
| `/api/backtest/result/{task_id}` | GET | 获取回测结果 |
| `/api/backtest/list` | GET | 任务列表（分页） |
| `/api/backtest/health` | GET | 健康检查 |
| `/api/backtest/delete/{task_id}` | DELETE | 删除任务 |

### 1.5 任务模型

```python
class BacktestTask:
    strategy_name: str          # 策略名称
    strategy_code: str          # 策略代码（必须含CtaTemplate子类）
    symbol: str                 # 合约代码（如 IF888.CFFEX）
    interval: str               # K线周期（1m/5m/1h/1d）
    start_date: date            # 开始日期
    end_date: date              # 结束日期
    capital: float              # 初始资金
    engine_type: str            # 引擎类型（cta）
    tick_size: Optional[float]  # 最小变动价位
```

### 1.6 vnpy 4.x适配要点

- Interval枚举精简：`1m → Interval.MINUTE`（4.x移除了FIVE_MINUTE等）
- BacktestingEngine初始化：需要先add_strategy再load_data
- 数据加载：通过engine.load_bar()或自定义数据适配器
- 结果获取：engine.calculate_result() + engine.calculate_statistics()

---

## 2. 数据适配层（src/adapters/）

### 2.1 职责

实现vnpy的BaseDatafeed接口，将本地/第三方数据源适配为vnpy可识别格式。

### 2.2 vnpy_local_data_adapter.py

已实现的本地数据适配器，支持：
- 从SQLite数据库读取K线数据
- 从CSV文件批量导入
- 时间范围过滤
- 转换为vnpy BarData对象

### 2.3 扩展计划

| 适配器 | 数据源 | 状态 |
|--------|--------|------|
| vnpy_local_data_adapter | 本地SQLite/CSV | ✅ 已完成 |
| akshare_data_adapter | akshare实时API | 🔜 规划中 |
| jqdata_adapter | 聚宽数据接口 | 🔜 规划中 |
| qmt_adapter | QMT交易终端 | 🔜 规划中 |

---

## 3. 容器镜像（docker/）

### 3.1 镜像分层构建

```dockerfile
# Layer 1: 基础镜像 + 系统依赖（低频变更）
FROM python:3.10-slim
RUN apt-get update && apt-get install -y ...

# Layer 2: Python基础依赖（低频变更）— vnpy/numpy/pandas等
COPY requirements/requirements-base.txt .
RUN pip install -r requirements-base.txt

# Layer 3: 额外依赖（高频变更）— akshare/tushare等
COPY requirements/requirements-extra.txt .
RUN pip install -r requirements-extra.txt
```

### 3.2 entrypoint.sh 启动流程

```bash
1. pip3 install vnpy_ctastrategy vnpy_sqlite   # 自动安装运行时依赖
2. sshd -D &                                     # SSH服务
3. jupyter lab &                                 # Jupyter开发环境
4. uvicorn backtest_service.main:app &           # 回测API服务
5. 健康检查                                       # 确认服务就绪
6. tail -f /dev/null                             # 保持容器运行
```

### 3.3 Volume挂载设计

```bash
docker run \
  -v /volume1/stock/sanguo_vnpy/bt-service:/app/scripts/backtest_service:ro \
  -v /volume1/stock/sanguo_vnpy/entrypoint.sh:/app/entrypoint.sh:ro \
  sanguo_vnpy:with-scripts
```

**设计理由**：代码通过volume挂载而非docker commit，便于更新和回滚。

---

## 4. 部署配置（config/）

### 4.1 Nginx反向代理

每个用户一个location配置，按路径分发到对应的Web端口：

```nginx
location /zhangfei/ {
    proxy_pass http://127.0.0.1:8004/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}
```

### 4.2 Systemd服务管理

每个用户两个systemd服务：
- `sanguo-trade-{user}.service` — 交易进程（RPC服务端）
- `sanguo-web-{user}.service` — Web进程（FastAPI）

支持独立启停，不影响其他用户。

---

*下一步：[04-deployment.md](04-deployment.md)*