From d7926313a92c0bfd7ef932e7bd6f8769d43601eb Mon Sep 17 00:00:00 2001
From: cfdaily <cfdaily@gitee.com>
Date: Wed, 29 Apr 2026 20:20:32 +0800
Subject: [PATCH] auto-sync: 2026-04-29 20:20:32

---
 docs/05-user-manual.md | 204 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 204 insertions(+)
 create mode 100644 docs/05-user-manual.md

diff --git a/docs/05-user-manual.md b/docs/05-user-manual.md
new file mode 100644
index 00000000..61952f04
--- /dev/null
+++ b/docs/05-user-manual.md
@@ -0,0 +1,204 @@
+# 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实时数据。如需完整历史数据，联系赵云（数据护军）。
+
+---
+
+*三国量化团队 · 姜维（平台总督）*