leopard-analysis/note_refactor.md

# 回测代码重构说明

## 概述

本次重构将原有的单一文件 `backtest.py` 拆分为模块化架构，提升代码复用性和可维护性。

## 文件结构变化

### 新增文件

1. **config.py** - 配置管理模块
   - 数据库配置（DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD）
   - 默认回测参数（DEFAULT_CASH, DEFAULT_COMMISSION, DEFAULT_WARMUP_DAYS）
   - 图表配色（BULL_COLOR, BEAR_COLOR）

2. **backtest_core.py** - 核心回测引擎
   - `BacktestResult` 数据类：结构化回测结果
   - `load_data_from_db()`：从数据库加载历史数据
   - `load_strategy()`：动态加载策略文件
   - `apply_color_scheme()`：应用图表配色
   - `run_backtest()`：单股票回测函数
   - `run_batch_backtest()`：批量回测函数（串行执行）

3. **backtest_command.py** - 命令行界面
   - `parse_arguments()`：解析命令行参数
   - `format_single_result()`：详细格式输出（单股票）
   - `format_batch_results()`：表格格式输出（多股票，使用 tabulate）
   - `main()`：主流程编排

### 删除文件

1. **backtest.py** - 原有单一文件（284 行）

## 接口变化

### 新增 API

```python
# 单股票回测
result = backtest_core.run_backtest(
    code='000001.SZ',
    start_date='2024-01-01',
    end_date='2024-12-31',
    strategy_file='strategies/sma_strategy.py',
    cash=100000,
    commission=0.002,
    warmup_days=365,
    output_dir=None  # 可选，为 None 时不生成图表
)

# 批量回测
results = backtest_core.run_batch_backtest(
    codes=['000001.SZ', '600000.SH'],
    start_date='2024-01-01',
    end_date='2024-12-31',
    strategy_file='strategies/sma_strategy.py',
    cash=100000,
    commission=0.002,
    warmup_days=365,
    output_dir='output/',  # 可选，为每个股票生成 {code}.html
    show_progress=True  # 可选，是否显示 tqdm 进度条
)
```

### 新增数据结构

```python
@dataclasses.dataclass
class BacktestResult:
    code: str
    equity_final: float
    equity_peak: float
    return_pct: float
    buy_hold_return_pct: float
    return_ann_pct: float
    volatility_ann_pct: float
    sortino_ratio: float
    calmar_ratio: float
    max_drawdown_pct: float
    avg_drawdown_pct: float
    max_drawdown_duration: float
    avg_drawdown_duration: float
    num_trades: int
    win_rate_pct: float
    sqn: float
```

## 命令行使用方式变化

### 旧方式（已删除）

```bash
python backtest.py --code 000001.SZ --start-date 2024-01-01 --end-date 2024-12-31 --strategy-file strategy.py
```

### 新方式

```bash
uv run python backtest_command.py --codes 000001.SZ --start-date 2024-01-01 --end-date 2024-12-31 --strategy-file strategies/sma_strategy.py
```

### 参数变化

| 参数名 | 变化 | 说明 |
|--------|--------|------|
| `--code` | 改为 `--codes` | 从单一参数改为多值参数（`nargs='+'`） |
| `--output` | 改为 `--output-dir` | 指定目录而非文件路径 |

### 新增参数

- `--output-dir`：指定图表输出目录（可选）
  - 单股票时：生成 `{code}.html` 在指定目录
  - 多股票时：为每个股票生成 `{code}.html` 在指定目录
  - 不指定时不生成图表

## 输出格式变化

### 单股票输出

保持原有的详细格式输出，每个指标单独一行：

```
============================================================
股票代码: 000001.SZ
============================================================
最终收益: 100981.58
峰值收益: 103731.54
总收益率（%）: 0.98
...
============================================================
```

### 多股票输出

新增表格格式输出（使用 tabulate，grid 格式）：

```
+------------+-----------+---------+-------------+------------+-------+
| 股票代码   |   收益率% |   胜率% |   最大回撤% |   交易次数 |   SQN |
+============+===========+=========+=============+============+=======+
| 000001.SZ  |      0.98 |     100 |       -2.65 |          1 |   nan |
| 600000.SH  |      0.04 |     100 |       -1.5  |          1 |   nan |
+------------+-----------+---------+-------------+------------+-------+
```

### 进度条

多股票回测时显示 tqdm 进度条：

```
批量回测: 50%|█████     | 1/2 [00:07<00:07, 7.82s/it]
```

## 依赖变化

### 新增依赖

- `tabulate`：表格格式化
  - 版本：0.9.0
  - 用途：批量回测结果的表格化输出

- `tqdm`：进度条显示
  - 版本：4.67.1
  - 用途：批量回测时的实时进度反馈

## 特性增强

### 新增功能

1. **批量回测**：支持传入多个股票代码进行串行回测
   - 命令：`--codes 000001.SZ 600000.SH`
   - 输出：表格化结果对比
   - 进度条：实时显示回测进度

2. **图表生成**：为每个股票生成独立 HTML 图表
   - 参数：`--output-dir output/`
   - 输出：`{code}.html` 在指定目录
   - 自动创建目录：`os.makedirs(output_dir, exist_ok=True)`

3. **进度条显示**：使用 tqdm 提供实时反馈
   - 多股票时自动显示
   - 可通过 `show_progress=False` 禁用

## 兼容性说明

### BREAKING CHANGES

1. **命令行入口变化**
   - 旧：`python backtest.py`
   - 新：`uv run python backtest_command.py`

2. **参数名称变化**
   - `--code` → `--codes`（从单值改为多值）

### 兼容性保证

- 所有原有功能完整保留
- 核心回测逻辑无变化
- 策略加载方式不变
- 数据访问接口不变

## 代码行数对比

| 文件 | 旧行数 | 新行数 | 变化 |
|------|---------|---------|------|
| backtest.py | 284 | - | -284 |
| config.py | - | 20 | +20 |
| backtest_core.py | - | ~200 | +200 |
| backtest_command.py | - | ~120 | +120 |
| **总计** | **284** | **~340** | **+56** |

## 迁移指南

### 对于开发者

如果需要在其他模块中调用回测功能：

```python
from backtest_core import run_backtest, run_batch_backtest, BacktestResult

# 单股票回测
result = run_backtest(
    code='000001.SZ',
    start_date='2024-01-01',
    end_date='2024-12-31',
    strategy_file='strategies/sma_strategy.py'
)

# 批量回测
results = run_batch_backtest(
    codes=['000001.SZ', '600000.SH'],
    start_date='2024-01-01',
    end_date='2024-12-31',
    strategy_file='strategies/sma_strategy.py'
)

# 访问结果
print(result.return_pct)
print(result.win_rate_pct)
```

### 对于终端用户

**单股票回测示例：**

```bash
uv run python backtest_command.py \
  --codes 000001.SZ \
  --start-date 2024-01-01 \
  --end-date 2024-12-31 \
  --strategy-file strategies/sma_strategy.py
```

**多股票回测示例：**

```bash
uv run python backtest_command.py \
  --codes 000001.SZ 600000.SH \
  --start-date 2024-01-01 \
  --end-date 2024-12-31 \
  --strategy-file strategies/sma_strategy.py
```

**生成图表示例：**

```bash
uv run python backtest_command.py \
  --codes 000001.SZ \
  --start-date 2024-01-01 \
  --end-date 2024-12-31 \
  --strategy-file strategies/sma_strategy.py \
  --output-dir output/
```

## 错误处理

- **立即失败策略**：遇到第一个错误立即停止，不继续执行其他股票
- **友好错误提示**：捕获异常并打印清晰的错误信息
- **退出状态码**：成功返回 0，失败返回非零
- **回溯信息**：打印完整的堆栈跟踪以便调试

## 性能考虑

- **串行执行**：当前采用串行执行，确保简单可靠
- **未来扩展**：未来可改为并行执行（ThreadPoolExecutor）以提升性能
- **数据加载**：每次回测创建独立的数据库连接，避免连接池复杂度

## 总结

本次重构实现了：
- ✅ 代码模块化：核心逻辑与 CLI 界面分离
- ✅ 可复用性：提供标准化 API 供其他模块调用
- ✅ 功能增强：支持批量回测和图表生成
- ✅ 用户体验：表格化结果和进度条显示
- ✅ 代码质量：更清晰的模块划分和类型提示