完成回测脚本

2026-01-27 18:30:41 +08:00
parent 53e72e2f84
commit 5c4a70d7f0
14 changed files with 2739 additions and 0 deletions
--- a/openspec/changes/archive/2026-01-27-refactor-backtest-script/design.md
+++ b/openspec/changes/archive/2026-01-27-refactor-backtest-script/design.md
@@ -0,0 +1,441 @@
+# Design: Refactor Backtest Script
+
+## Context
+
+### 当前状态
+
+现有的回测系统基于 Jupyter Notebook (`backtest.ipynb`)，包含以下手动执行步骤：
+1. 通过 SQL magic 查询数据库获取股票价格数据（含复权）
+2. 数据预处理（重命名列、设置索引）
+3. 计算技术指标（SMA10, SMA30, SMA60, SMA120）
+4. 定义策略类（SmaCross，金叉买入、死叉卖出）
+5. 执行回测并打印结果
+6. 生成交互式图表（Bokeh）
+
+### 约束条件
+
+- 数据库：PostgreSQL (leopard_dev@81.71.3.24)
+- 数据表：`leopard_daily` (日线数据), `leopard_stock` (股票信息)
+- 回测引擎：`backtesting` Python 库
+- 复权逻辑：`price * factor`（factor 从数据库获取）
+- 输出格式：中文标签 + Bokeh HTML 图表
+
+### 利益相关者
+
+- 量化研究员：需要快速测试不同策略、不同股票的回测表现
+- 策略开发者：需要独立开发策略，通过标准接口集成
+- 运维人员：需要支持批量自动化回测任务
+
+## Goals / Non-Goals
+
+### Goals
+
+1. **命令行化执行** - 通过命令行参数完成回测，无需交互式环境
+2. **策略模块化** - 策略逻辑与主流程分离，支持动态加载不同策略文件
+3. **参数化配置** - 支持股票代码、时间范围、初始资金、手续费率等参数
+4. **简化的数据访问** - 保持简单的数据库连接逻辑，不引入过度抽象
+5. **清晰的结果输出** - 控制台中文统计 + 可选的 HTML 图表文件
+
+### Non-Goals
+
+- ❌ 不支持多时间周期（仅日线）
+- ❌ 不支持多股票组合回测（仅单股票）
+- ❌ 不支持参数优化（固定策略参数）
+- ❌ 不支持实盘交易接口
+- ❌ 不引入复杂的依赖注入或插件系统
+- ❌ 不实现 Web UI 或 API 接口
+
+## Decisions
+
+### D1: 文件结构 - 单一入口文件 + 策略文件
+
+**决策**:
+- `backtest.py` - 包含所有主流程逻辑（参数解析、数据加载、回测执行、结果输出）
+- `strategy.py` - 策略模板（指标计算函数 + 策略类）
+- 可选 `strategies/` 目录 - 存放其他策略文件
+
+**理由**:
+- 用户要求简化文件数量，保持流程集中
+- 单一入口文件便于理解和维护
+- 策略文件独立，便于多人协作开发
+
+**替代方案**:
+- 将数据加载、结果输出拆分为独立模块 - 被用户拒绝（"设计的文件太多了，需要简化"）
+
+---
+
+### D2: 策略接口 - 两个必需函数 + 策略类
+
+**决策**: 策略文件必须提供：
+
+1. **`calculate_indicators(data)` 函数**
+   ```python
+   def calculate_indicators(data: pd.DataFrame) -> pd.DataFrame:
+       """计算策略所需的技术指标，返回添加了指标列的 DataFrame"""
+   ```
+
+2. **`get_strategy()` 函数**
+   ```python
+   def get_strategy() -> type:
+       """返回策略类（Strategy 的子类）"""
+   ```
+
+3. **策略类定义**
+   ```python
+   from backtesting import Strategy
+
+   class MyStrategy(Strategy):
+       def init(self):
+           """注册指标到 backtesting 框架"""
+           pass
+
+       def next(self):
+           """每个时间步的决策逻辑"""
+           pass
+   ```
+
+**理由**:
+- 将指标计算与交易逻辑分离，主流程可以预处理所有数据
+- `get_strategy()` 函数提供清晰的加载接口
+- 遵循 `backtesting` 库的接口规范
+
+**替代方案**:
+- 将 `calculate_indicators` 作为策略类的方法 - 问题：主流程无法先计算指标，必须在 Strategy 类中注册
+
+---
+
+### D3: 策略动态加载 - 使用 `importlib`
+
+**决策**:
+```python
+import importlib.util
+
+def load_strategy(strategy_file):
+    """动态加载策略文件"""
+    spec = importlib.util.spec_from_file_location(module_name, strategy_file)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    calculate_indicators = module.calculate_indicators
+    strategy_class = module.get_strategy()
+    return calculate_indicators, strategy_class
+```
+
+**理由**:
+- 支持任意路径的策略文件（如 `strategy.py`, `strategies/macd.py`）
+- 无需预定义策略列表或配置文件
+- Python 标准库，无额外依赖
+
+**替代方案**:
+- 约定式加载（所有策略放在 `strategies/` 目录） - 灵活性不足
+- 配置文件映射策略名称和文件路径 - 增加维护成本
+
+---
+
+### D4: 数据库连接 - 简化 SQLAlchemy 连接
+
+**决策**:
+```python
+import sqlalchemy
+
+conn_str = f"postgresql://{user}:{password}@{host}/{database}"
+engine = sqlalchemy.create_engine(conn_str)
+df = pd.read_sql(query, engine)
+engine.dispose()
+```
+
+**理由**:
+- 用户要求"数据库访问保持简单，不需要太多抽象"
+- SQLAlchemy 提供基础连接池和 SQL 注入防护
+- 支持参数化查询（未来扩展）
+
+**SQL 查询**:
+```sql
+SELECT
+    trade_date,
+    open * factor AS Open,
+    close * factor AS Close,
+    high * factor AS High,
+    low * factor AS Low,
+    volume AS Volume,
+    COALESCE(factor, 1.0) AS factor
+FROM leopard_daily daily
+LEFT JOIN leopard_stock stock ON stock.id = daily.stock_id
+WHERE stock.code = '{code}'
+  AND daily.trade_date BETWEEN '{start_date} 00:00:00'
+                          AND '{end_date} 23:59:59'
+ORDER BY daily.trade_date
+```
+
+**替代方案**:
+- 直接使用 `psycopg2` - 需要手动处理游标和类型转换
+- 引入 ORM 模型 - 过度抽象，与"保持简单"要求矛盾
+
+---
+
+### D5: 执行顺序 - 先计算指标，再执行回测
+
+**决策**:
+```
+1. load_data_from_db() → 获取原始价格数据
+2. calculate_indicators(data) → 添加指标列到 DataFrame
+3. Backtest(data, strategy_class) → 执行回测
+```
+
+**理由**:
+- 指标计算与回测分离，便于调试和验证
+- 避免在 Strategy 类的 `init()` 中重复计算
+- 支持可视化指标（如果需要）
+
+**示例流程**:
+```python
+data = load_data_from_db('000001.SZ', '2024-01-01', '2025-12-31')
+# data 包含: Open, High, Low, Close, Volume, factor
+
+data = calculate_indicators(data)
+# data 新增: sma10, sma30, sma60, sma120
+
+bt = Backtest(data, SmaCross, cash=100000, commission=0.002)
+stats = bt.run()
+```
+
+**替代方案**:
+- 在 Strategy 类的 `init()` 中计算指标 - 导致指标逻辑分散，难以调试
+
+---
+
+### D6: 输出格式 - 控制台 + 可选 HTML 文件
+
+**决策**:
+
+**控制台输出**:
+- 始终打印回测统计信息（中文格式化）
+- 使用 notebook 中定义的 `INDICATOR_MAPPING` 映射
+
+**HTML 输出**:
+- 仅当指定 `--output` 参数时生成
+- 使用 `backtesting` 库的 `bt.plot(filename=..., show=False)` 方法
+- 生成独立的 HTML 文件，无需浏览器环境
+
+**理由**:
+- 用户要求"输出包括命令行输出和 html 文件输出，使用一个参数控制"
+- 控制台输出便于快速查看，HTML 文件便于分享和详细分析
+- `show=False` 确保在无头环境中也能生成文件
+
+**示例用法**:
+```bash
+# 仅控制台输出
+python backtest.py --code 000001.SZ --start-date 2024-01-01 --end-date 2025-12-31 --strategy-file strategy.py
+
+# 控制台 + HTML 文件
+python backtest.py --code 000001.SZ --start-date 2024-01-01 --end-date 2025-12-31 --strategy-file strategy.py --output result.html
+```
+
+**替代方案**:
+- 始终生成 HTML 文件 - 增加不必要的磁盘 I/O
+- 自动在浏览器打开 - 不适用于服务器环境
+
+---
+
+### D8: 预热天数 - 命令行参数控制
+
+**决策**:
+```python
+parser.add_argument('--warmup-days', type=int, default=365,
+                   help='预热天数（默认: 365，约一年）')
+```
+
+**执行逻辑**:
+1. 用户从数据库查询的日期范围：`--start-date` 到 `--end-date`
+2. 回测前，从数据中截取最后 N 天（由 `--warmup-days` 指定）
+3. 截取的数据用于指标计算和回测
+
+**理由**:
+- 用户明确要求："如果命令行参数指定了，就用参数指定的时长，否则默认预热时长为一年"
+- 简化实现，不需要自动计算各策略所需的最长预热期
+- 灵活性高，用户可根据需要调整预热天数
+- 避免复杂化：不解析策略代码以确定最长指标周期
+
+**示例**:
+```python
+# 查询 2024-01-01 到 2025-12-31 的数据（2 年）
+data = load_data_from_db('000001.SZ', '2024-01-01', '2025-12-31')  # 约 500 条记录
+
+# 默认预热 365 天，取最后 1 年的数据用于回测
+data = data.iloc[-365:]  # 2025-01-01 到 2025-12-31
+
+# 用户指定预热 180 天
+data = data.iloc[-180:]  # 2025-07-01 到 2025-12-31
+```
+
+**替代方案**:
+- 自动计算策略所需的最长指标周期 - 需要解析策略代码，复杂度高
+- 不截取数据，依赖策略自己处理 NaN - 但用户明确要求预热天数控制
+
+---
+
+### D7: 数据库凭证 - 环境变量
+
+**决策**:
+```python
+# 数据库配置（开发环境，直接硬编码）
+DB_HOST = '81.71.3.24'
+DB_NAME = 'leopard_dev'
+DB_USER = 'your_username'
+DB_PASSWORD = 'your_password'
+```
+
+**理由**:
+- 用户明确要求："数据库凭证不使用环境变量，开发人员直接硬编码到代码里即可"
+- 开发环境仅内部使用，无安全风险
+- 简化实现，无需环境变量管理
+- 不引入额外的配置文件或库
+
+**替代方案**:
+- 使用环境变量 - 用户明确拒绝
+- 使用配置文件 - 增加维护成本，用户明确不需要
+
+---
+
+## Risks / Trade-offs
+
+### R1: SQL 注入风险
+
+**风险**: 当前查询使用字符串拼接，存在 SQL 注入风险
+
+**缓解措施**:
+- 用户要求"数据库访问保持简单"，暂不实现参数化查询
+- 文档中明确说明输入格式（股票代码、日期）
+- 后续可在 `load_data_from_db()` 中添加输入验证
+
+---
+
+### R2: 策略文件加载失败
+
+**风险**: 动态加载策略文件时，文件不存在或代码错误会导致运行时崩溃
+
+**缓解措施**:
+- 使用 `try-except` 捕获 `ImportError` 和 `AttributeError`
+- 提供清晰的错误信息："策略文件 {file} 加载失败: {error}"
+- 在文档中说明策略文件的标准接口
+
+---
+
+### R3: 指标计算性能
+
+**风险**: 大数据集（如 10 年日线数据）计算指标可能较慢
+
+**缓解措施**:
+- 使用 pandas 的向量化操作（已实现）
+- 考虑在文档中提示：首次运行可能较慢，后续可缓存指标数据
+- 当前不优化（属于非目标范围）
+
+---
+
+### R4: 策略接口兼容性
+
+**风险**: 用户编写的策略文件可能不符合接口要求（缺少 `calculate_indicators` 或 `get_strategy`）
+
+**缓解措施**:
+- 提供 `strategy.py` 作为标准模板
+- 在 `load_strategy()` 中进行接口检查
+- 运行时捕获 `AttributeError` 并提示缺失的函数
+
+---
+
+### R5: 图表生成失败
+
+**风险**: Bokeh 生成 HTML 文件时可能因数据格式或依赖问题失败
+
+**缓解措施**:
+- 仅在用户指定 `--output` 参数时才尝试生成图表
+- 使用 `try-except` 捕获异常，不影响统计信息输出
+- 错误提示："图表生成失败，但回测已完成: {error}"
+
+---
+
+### R6: 时区和日期处理
+
+**风险**: 数据库中的日期与用户输入的日期可能存在时区差异
+
+**缓解措施**:
+- 当前 SQL 查询使用 `BETWEEN 'start_date 00:00:00' AND 'end_date 23:59:59'` 覆盖全天
+- 假设数据库和用户输入使用相同的时区（本地时间）
+- 文档中说明日期格式为 `YYYY-MM-DD`
+
+---
+
+## Resolved Decisions
+
+1. **数据库凭证管理**: ✅ 已决定 - 直接硬编码在代码中
+   - 实现方式：在 backtest.py 中定义 DB_HOST, DB_NAME, DB_USER, DB_PASSWORD 常量
+   - 不使用环境变量、不使用配置文件
+   - 开发人员可直接修改代码中的凭证
+   - 无安全风险（仅开发环境内部使用）
+
+2. **错误处理详细程度**: ✅ 已决定 - 仅打印到控制台，不写入日志文件
+   - 实现方式：所有错误信息直接使用 `print()` 输出到 stdout/stderr
+   - 不引入日志库（logging）
+   - 保持输出简洁，便于管道处理
+
+3. **指标预热期**: ✅ 已决定 - 通过 `--warmup-days` 命令行参数控制
+   - 实现方式：默认 365 天（约 1 年），用户可指定其他值
+   - 不自动计算策略所需的最长指标周期
+   - 使用 `data.iloc[-warmup_days:]` 截取数据
+
+4. **多策略并行**: ✅ 已决定 - 不支持一次回测运行多个策略
+   - 实现方式：每次命令执行只支持单个策略文件
+   - 如需对比策略，用户需多次执行命令
+   - 不实现多进程/多线程并行回测
+
+---
+
+## Implementation Overview
+
+### 核心流程
+
+```
+main()
+  ├─ parse_arguments()            # 解析命令行参数
+  ├─ load_data_from_db()         # 从数据库获取价格数据
+  │   └─ 返回 DataFrame: [Open, High, Low, Close, Volume, factor]
+  ├─ load_strategy()             # 动态加载策略文件
+  │   └─ 返回: (calculate_indicators, strategy_class)
+  ├─ calculate_indicators(data)   # 计算技术指标
+  │   └─ 返回添加了指标列的 DataFrame
+  ├─ Backtest(data, strategy)    # 执行回测
+  │   └─ 返回 stats 对象
+  ├─ print_stats(stats)          # 控制台输出中文统计
+  └─ bt.plot(filename=..., show=False)  # 可选：生成 HTML 图表
+```
+
+### 文件结构
+
+```
+leopard_analysis/
+├── backtest.py                 # 主流程脚本
+├── strategy.py                 # SMA 策略模板
+├── strategies/                # 其他策略（可选）
+│   ├── macd_strategy.py
+│   ├── rsi_strategy.py
+│   └── ...
+├── .env                      # 数据库凭证（可选）
+├── requirements.txt            # 依赖列表
+└── README.md                 # 使用说明（可选）
+```
+
+### 依赖关系
+
+```
+backtest.py
+  ├─ argparse           # 命令行参数解析
+  ├─ sqlalchemy        # 数据库连接
+  ├─ pandas            # 数据处理
+  ├─ importlib        # 动态模块加载
+  └─ backtesting       # 回测引擎
+
+strategy.py
+  ├─ pandas            # DataFrame 操作
+  ├─ backtesting       # Strategy 基类
+  └─ backtesting.lib   # crossover 等工具函数
+```