# 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 等工具函数
```