# 05 - 用户手册

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

---

## 1. 概述

本手册面向三国量化团队所有成员，说明如何使用回测服务进行策略回测。

## 2. 服务地址

| 服务 | 地址 | 用途 |
|------|------|------|
| 回测API | `http://192.168.2.154:8088` | 提交/查询回测任务 |
| API文档 | `http://192.168.2.154:8088/docs` | Swagger交互式文档 |
| Jupyter | `http://192.168.2.154:8888` | 开发环境（token: sanguo123） |

## 3. 提交回测任务

### 3.1 策略代码要求

策略代码必须包含一个继承自 `CtaTemplate` 的类：

```python
from vnpy_ctastrategy import CtaTemplate
from vnpy.trader.object import BarData

class MyStrategy(CtaTemplate):
    """你的策略类名"""
    
    parameters = []    # 策略参数列表
    variables = []     # 策略变量列表
    
    def on_init(self):
        self.write_log("策略初始化")
    
    def on_start(self):
        self.write_log("策略启动")
    
    def on_stop(self):
        self.write_log("策略停止")
    
    def on_bar(self, bar: BarData):
        # 在这里写你的策略逻辑
        pass
```

### 3.2 提交请求

**端点**: `POST http://192.168.2.154:8088/api/backtest/submit`

```json
{
    "strategy_name": "my_ma_strategy",
    "strategy_code": "from vnpy_ctastrategy import CtaTemplate\n\nclass MyStrategy(CtaTemplate):\n    def on_bar(self, bar):\n        pass",
    "symbol": "510300.SSE",
    "interval": "1d",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "capital": 1000000,
    "engine_type": "cta"
}
```

**参数说明**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| strategy_name | string | ✅ | 策略名称 |
| strategy_code | string | ✅ | 策略代码（含CtaTemplate子类） |
| symbol | string | ✅ | 合约代码（如 510300.SSE, IF888.CFFEX） |
| interval | string | ✅ | K线周期（1m/5m/15m/1h/1d） |
| start_date | date | ✅ | 开始日期（YYYY-MM-DD） |
| end_date | date | ✅ | 结束日期（YYYY-MM-DD） |
| capital | float | ✅ | 初始资金 |
| engine_type | string | ✅ | 引擎类型（固定为"cta"） |
| tick_size | float | ❌ | 最小变动价位 |

### 3.3 Python调用示例

```python
import requests
import time

API_URL = "http://192.168.2.154:8088/api/backtest"

# 提交任务
response = requests.post(f"{API_URL}/submit", json={
    "strategy_name": "dual_ma",
    "strategy_code": open("my_strategy.py").read(),
    "symbol": "510300.SSE",
    "interval": "1d",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "capital": 1000000,
    "engine_type": "cta"
})

task_id = response.json()["data"]["task_id"]
print(f"任务已提交: {task_id}")

# 轮询等待结果
while True:
    status = requests.get(f"{API_URL}/status/{task_id}").json()
    state = status["data"]["status"]
    
    if state in ("completed", "failed"):
        break
    
    print(f"状态: {state}")
    time.sleep(2)

# 获取结果
result = requests.get(f"{API_URL}/result/{task_id}").json()

if result["data"]["status"] == "completed":
    stats = result["data"]["statistics"]
    print(f"总收益率: {stats['total_return']:.2%}")
    print(f"夏普比率: {stats['sharpe_ratio']:.2f}")
    print(f"最大回撤: {stats['max_drawdown']:.2%}")
else:
    print(f"回测失败: {result['data']['error_message']}")
```

### 3.4 curl调用示例

```bash
# 提交任务
TASK=$(curl -s -X POST http://192.168.2.154:8088/api/backtest/submit \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_name": "test",
    "strategy_code": "from vnpy_ctastrategy import CtaTemplate\nclass T(CtaTemplate):\n    def on_bar(self, bar): pass",
    "symbol": "510300.SSE",
    "interval": "1d",
    "start_date": "2024-01-01",
    "end_date": "2024-06-30",
    "capital": 1000000,
    "engine_type": "cta"
  }')

TASK_ID=$(echo $TASK | python3 -c "import sys,json;print(json.load(sys.stdin)['data']['task_id'])")

# 查询状态
curl http://192.168.2.154:8088/api/backtest/status/$TASK_ID | python3 -m json.tool

# 获取结果
curl http://192.168.2.154:8088/api/backtest/result/$TASK_ID | python3 -m json.tool
```

## 4. 查询任务

### 4.1 单个任务状态

```bash
GET /api/backtest/status/{task_id}
```

返回字段：
- `status`: pending / running / completed / failed
- `created_at`: 创建时间
- `started_at`: 开始执行时间
- `completed_at`: 完成时间

### 4.2 任务列表

```bash
GET /api/backtest/list?page=1&page_size=10&status=completed
```

### 4.3 回测结果

```bash
GET /api/backtest/result/{task_id}
```

结果字段：
- `statistics`: 回测统计（收益率、夏普比率、最大回撤等）
- `error_message`: 失败时的错误信息
- `result_csv_path`: 结果CSV文件路径
- `equity_curve_png_path`: 资金曲线图路径

## 5. 常见问题

### Q: 策略提交后失败，提示"没有找到CtaTemplate子类"
**A**: 策略代码中必须定义一个继承自 `CtaTemplate` 的类。

### Q: 合约代码格式是什么？
**A**: `{合约代码}.{交易所代码}`，如：
- 沪深300ETF: `510300.SSE`
- 沪深300指数: `000300.SSE`
- 中证500股指: `IC888.CFFEX`

### Q: 支持哪些K线周期？
**A**: `1m`(1分钟), `5m`(5分钟), `15m`(15分钟), `1h`(1小时), `1d`(日线)

### Q: 数据从哪里来？
**A**: 当前使用akshare实时数据。如需完整历史数据，联系赵云（数据护军）。

---

*三国量化团队 · 姜维（平台总督）*