# 自动化回测服务 - 使用说明

## 概述

基于 vnpy 原生 `BacktestingEngine` 封装的 RESTful API 自动化回测服务。

支持：
- 通过 API 提交回测任务
- 自动排队控制并发
- 使用 vnpy 原生回测引擎执行
- 保存回测结果（CSV + 图表 + JSON）
- 查询任务状态和结果

## 架构设计

严格遵循 vnpy 原生设计，不修改核心，只做外层封装：

```
[API 服务] ← 接收任务
    ↓
[任务队列 + 进程池] ← 控制并发
    ↓
[BacktestingEngine (vnpy 原生)] ← 执行回测
    ↓
[文件存储] ← 保存结果
    ↓
[API 查询] ← 返回结果
```

## 启动方式

```bash
# 手动启动
cd /app/scripts/backtest-service
python main.py

# 后台运行
nohup python main.py > backtest-service.log 2>&1 &

# 查看日志
tail -f backtest-service.log
```

## 访问地址

启动后访问：
- 服务地址：http://container-ip:8088
- API 文档：http://container-ip:8088/docs → 可以直接在网页上测试API

## API 接口说明

| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 提交回测 | POST | `/api/backtest/submit` | 提交新的回测任务 |
| 任务列表 | GET | `/api/backtest/list` | 列出任务，支持分页和状态过滤 |
| 任务状态 | GET | `/api/backtest/status/{task_id}` | 查询任务状态 |
| 回测结果 | GET | `/api/backtest/result/{task_id}` | 获取完整回测结果 |
| 删除任务 | DELETE | `/api/backtest/delete/{task_id}` | 删除任务 |
| 健康检查 | GET | `/api/backtest/health` | 查看服务状态，返回任务统计 |

## 配置

可以通过环境变量覆盖默认配置：

| 环境变量 | 说明 | 默认值 |
|----------|------|--------|
| `MAX_WORKERS` | 最大并发回测数 | 2 |
| `HOST` | 监听地址 | 0.0.0.0 |
| `PORT` | 监听端口 | 8088 |
| `BASE_DIR` | 任务存储根目录 | /app/backtest_jobs |
| `DEBUG` | 调试模式 | True |

## 使用示例

### 1. 提交回测

```bash
curl -X POST http://127.0.0.1:8088/api/backtest/submit \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_name": "双均线策略",
    "strategy_code": "完整的策略Python代码...",
    "symbol": "IF888.CFFEX",
    "interval": "1h",
    "start_date": "2020-01-01",
    "end_date": "2025-01-01",
    "parameters": {
      "fast_window": 5,
      "slow_window": 20
    },
    "capital": 1000000
  }'
```

响应：
```json
{
  "code": 0,
  "msg": "任务提交成功",
  "data": {
    "task_id": "a1b2c3d4...",
    "status": "pending",
    "created_at": "2026-04-12T10:00:00+08:00"
  }
}
```

### 2. 查询任务状态

```bash
curl http://127.0.0.1:8088/api/backtest/status/a1b2c3d4
```

### 3. 获取回测结果

```bash
curl http://127.0.0.1:8088/api/backtest/result/a1b2c3d4
```

## 结果存储结构

```
/app/backtest_jobs/
├── pending/           # 等待执行
├── running/           # 执行中
├── completed/         # 已完成
│   └── <task_id>/
│       ├── task.json       # 任务信息
│       ├── result.json     # 回测结果
│       ├── equity.csv      # 每日净值
│       ├── equity_curve.png  # 收益曲线图
│       └── trades.csv      # 成交记录
└── failed/            # 执行失败
    └── <task_id>/
        ├── task.json
        └── result.json     # 包含错误信息
```

## 设计原则

1. **不改动 vnpy 核心**：完全复用原生 `BacktestingEngine`
2. **轻量级**：只用 Python 标准库，不引入额外第三方任务队列
3. **隔离性**：每个回测在独立进程，一个失败不影响其他
4. **可配置并发**：根据 CPU 性能调整 `MAX_WORKERS`，避免资源耗尽

## 作者

三国量化团队 姜维 伯约  
2026-04-12