288 lines
11 KiB
Markdown
288 lines
11 KiB
Markdown
## Context
|
||
|
||
**Current State:**
|
||
`backtest.py` (284 lines) 是单一文件，包含：
|
||
- 命令行参数解析
|
||
- 数据库连接和数据加载
|
||
- 策略动态加载和验证
|
||
- 回测执行逻辑
|
||
- 结果格式化输出
|
||
- 图表生成
|
||
|
||
**Constraints:**
|
||
- 需要保持现有功能完整性（数据加载、策略加载、回测执行、结果展示）
|
||
- 需要支持多股票回测（串行执行）
|
||
- 不考虑并发实现（保持简单）
|
||
- 错误处理采用立即失败策略
|
||
- 数据库配置明文存储，不考虑环境变量
|
||
|
||
**Stakeholders:**
|
||
- 开发者：需要清晰的模块划分和可复用的接口
|
||
- 终端用户：需要友好的 CLI 输出（进度条、表格化结果）
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
1. 分离核心逻辑与 CLI 界面，提升代码复用性
|
||
2. 提供标准化函数接口，供其他模块调用回测功能
|
||
3. 支持多股票批量回测（串行执行）
|
||
4. 集中管理配置（数据库、参数、配色）
|
||
5. 优化 CLI 输出体验（tabulate 表格化、tqdm 进度条）
|
||
|
||
**Non-Goals:**
|
||
1. 并行执行多股票回测（性能优化非目标）
|
||
2. 环境变量管理配置（配置明文存储即可）
|
||
3. 复杂的聚合统计（仅单股票结果拼接）
|
||
4. 图表文件合并（每个股票生成独立 HTML）
|
||
5. 配置文件热重载（启动时加载一次）
|
||
|
||
## Decisions
|
||
|
||
### Decision 1: 三层模块划分
|
||
**选择：** 分离为 `config.py`、`backtest_core.py`、`backtest_command.py` 三个文件
|
||
|
||
**理由：**
|
||
- **config.py**：集中管理所有配置，避免硬编码分散
|
||
- **backtest_core.py**：纯粹的业务逻辑，提供可复用的函数接口
|
||
- **backtest_command.py**：CLI 界面，负责参数解析和结果展示
|
||
|
||
**替代方案：**
|
||
- 方案 A：保留单一文件，但改进内部结构（函数分离）
|
||
- 拒绝理由：仍无法复用，CLI 和业务逻辑耦合
|
||
- 方案 B：使用类封装（如 `BacktestEngine` 类）
|
||
- 拒绝理由：增加复杂度，函数接口已足够
|
||
|
||
### Decision 2: BacktestResult 数据类
|
||
**选择：** 使用 `dataclasses.dataclass` 定义 `BacktestResult`
|
||
|
||
**理由：**
|
||
- 结构化返回结果，便于序列化和导出
|
||
- 类型提示支持，提升代码可读性
|
||
- 自动生成 `__init__`、`__repr__` 等方法，减少样板代码
|
||
|
||
**替代方案：**
|
||
- 方案 A：直接返回原始 `stats` 对象（backtesting 库返回）
|
||
- 拒绝理由：依赖 backtesting 库内部结构，耦合度高
|
||
- 方案 B：返回字典
|
||
- 拒绝理由：缺乏类型提示，容易拼写错误
|
||
|
||
### Decision 3: 批量回测策略
|
||
**选择：** 串行执行（`for` 循环），立即失败
|
||
|
||
**理由：**
|
||
- 简单可靠，易于调试
|
||
- 错误处理清晰（第一个失败就停止）
|
||
- 避免并发带来的资源竞争和复杂度
|
||
|
||
**替代方案：**
|
||
- 方案 A：并行执行（ThreadPoolExecutor）
|
||
- 拒绝理由：性能非目标，并发增加复杂度
|
||
- 方案 B：继续执行其他股票，最后统一报告错误
|
||
- 拒绝理由：用户需求是立即失败
|
||
|
||
### Decision 4: CLI 参数设计
|
||
**选择：** `--codes` 多值参数（`nargs='+'`），`--output-dir` 目录参数
|
||
|
||
**理由：**
|
||
- `--codes` 支持传入多个股票代码，如 `--codes 000001.SZ 600000.SH`
|
||
- `--output-dir` 为每个股票生成 `{code}.html`，如 `output/000001.SZ.html`
|
||
- 保持原有参数（`--start-date`、`--end-date`、`--strategy-file`、`--cash`、`--commission`、`--warmup-days`）
|
||
|
||
**替代方案：**
|
||
- 方案 A：`--code` 逗号分隔（如 `--code 000001.SZ,600000.SH`）
|
||
- 拒绝理由：需要额外解析逻辑，不直观
|
||
- 方案 B：`--code` 多次调用（如 `--code 000001.SZ --code 600000.SH`）
|
||
- 拒绝理由：argparse 的 `nargs='+'` 更符合习惯
|
||
|
||
### Decision 5: 输出优化库
|
||
**选择：** 使用 `tabulate` 表格化批量结果，使用 `tqdm` 显示进度条
|
||
|
||
**理由：**
|
||
- **tabulate**：提供美观的表格输出，支持多种格式（grid、simple 等）
|
||
- **tqdm**：提供实时进度条，提升用户体验
|
||
- 两个库都是轻量级，不引入复杂依赖
|
||
|
||
**替代方案：**
|
||
- 方案 A：手动格式化表格（字符串拼接）
|
||
- 拒绝理由：代码冗余，格式不够美观
|
||
- 方案 B：不使用进度条（仅输出完成提示）
|
||
- 拒绝理由：多股票回测耗时较长，用户需要进度反馈
|
||
|
||
### Decision 6: 结果展示策略
|
||
**选择：** 单股票使用详细格式（现有），多股票使用表格格式（新增）
|
||
|
||
**理由：**
|
||
- 单股票：保持原有的详细输出（每个指标单独一行）
|
||
- 多股票：使用 `tabulate` 表格横向对比，节省垂直空间
|
||
|
||
**替代方案：**
|
||
- 方案 A：所有情况都使用详细格式（拼接）
|
||
- 拒绝理由：多股票时输出过长，难以阅读
|
||
- 方案 B：所有情况都使用表格格式
|
||
- 拒绝理由：单股票时表格优势不明显，详细格式更清晰
|
||
|
||
### Decision 7: 配置管理方式
|
||
**选择：** 明文常量存储在 `config.py`
|
||
|
||
**理由：**
|
||
- 满足用户需求（不考虑信息安全）
|
||
- 避免引入 `python-dotenv` 依赖
|
||
- 代码简洁，修改直接
|
||
|
||
**替代方案：**
|
||
- 方案 A：环境变量（`os.getenv`）
|
||
- 拒绝理由：用户明确不需要
|
||
- 方案 B：配置文件（JSON/YAML）
|
||
- 拒绝理由：增加文件管理和解析复杂度
|
||
|
||
### Decision 8: 数据访问接口
|
||
**选择：** `load_data_from_db(code, start_date, end_date)` 函数签名保持不变
|
||
|
||
**理由：**
|
||
- 现有接口已满足需求（单次查询一个股票）
|
||
- 迁移成本低，直接复制到 `backtest_core.py`
|
||
|
||
**替代方案：**
|
||
- 方案 A：批量查询（`load_data_from_db(codes, start_date, end_date)`）
|
||
- 拒绝理由：需要修改 SQL 为 `IN` 子句，且结果聚合复杂
|
||
- 方案 B：连接池复用（全局 engine 对象）
|
||
- 拒绝理由：每次创建引擎的开销可接受（串行执行）
|
||
|
||
### Decision 9: 策略加载接口
|
||
**选择：** `load_strategy(strategy_file)` 返回 `(calculate_indicators, strategy_class)` 元组
|
||
|
||
**理由：**
|
||
- 保持现有接口，迁移成本低
|
||
- 函数返回两个值符合 Python 惯例
|
||
|
||
**替代方案：**
|
||
- 方案 A：返回类对象（策略类自带指标计算方法）
|
||
- 拒绝理由：现有策略文件结构分离了两者，修改成本高
|
||
- 方案 B：返回命名空间对象（封装两个属性）
|
||
- 拒绝理由：增加复杂度，元组足够
|
||
|
||
### Decision 10: 错误处理策略
|
||
**选择：** 立即失败（不捕获部分错误继续执行）
|
||
|
||
**理由：**
|
||
- 符合用户需求
|
||
- 简化错误追踪（第一个错误直接暴露）
|
||
- 避免"部分成功"的歧义状态
|
||
|
||
**替代方案：**
|
||
- 方案 A：捕获错误但继续执行，最后统一报告
|
||
- 拒绝理由：用户明确要求立即失败
|
||
|
||
## Risks / Trade-offs
|
||
|
||
### Risk 1: CLI 命令变化导致用户习惯中断
|
||
**风险：** 用户习惯使用 `python backtest.py`，需要切换到 `uv run python backtest_command.py`
|
||
|
||
**缓解：**
|
||
- 在项目根目录创建软链接 `backtest.py -> backtest_command.py`（可选）
|
||
- 或在 README 中明确说明新的使用方式
|
||
- 提供迁移指南（参数变化说明）
|
||
|
||
### Risk 2: 多股票串行执行耗时较长
|
||
**风险：** 10 个股票可能需要 10 倍时间（每个 30 秒 → 总计 5 分钟）
|
||
|
||
**缓解：**
|
||
- 使用 `tqdm` 进度条提供实时反馈
|
||
- 在 README 中说明性能限制
|
||
- 未来可扩展为并行执行（非当前目标）
|
||
|
||
### Risk 3: BacktestResult 字段可能与 backtesting 库不兼容
|
||
**风险：** backtesting 库升级后，stats 对象的键名可能变化
|
||
|
||
**缓解：**
|
||
- 使用 `.get(key, default)` 方法访问，避免 KeyError
|
||
- 提供默认值（0 或空字符串）
|
||
- 在文档中说明依赖的 backtesting 版本
|
||
|
||
### Risk 4: tabulate/tqdm 依赖未安装
|
||
**风险：** 用户运行时缺少依赖，导致 ImportError
|
||
|
||
**缓解：**
|
||
- 使用 `uv add` 明确添加依赖到 pyproject.toml
|
||
- 在 README 中说明安装步骤
|
||
- 错误信息中提示安装命令（`uv add tabulate tqdm`）
|
||
|
||
### Risk 5: 策略文件路径处理不一致
|
||
**风险：** 策略文件路径可能是相对路径或绝对路径，导致加载失败
|
||
|
||
**缓解：**
|
||
- 使用 `os.path.abspath()` 转换为绝对路径
|
||
- 在错误信息中提示用户检查路径
|
||
- 测试相对路径和绝对路径两种情况
|
||
|
||
### Risk 6: 图表输出目录不存在
|
||
**风险：** 用户指定的 `--output-dir` 不存在，导致保存失败
|
||
|
||
**缓解：**
|
||
- 使用 `os.makedirs(output_dir, exist_ok=True)` 自动创建
|
||
- 在错误信息中提示用户检查目录权限
|
||
|
||
### Risk 7: 内存占用（多股票同时加载数据）
|
||
**风险：** 如果同时加载多个股票数据，内存占用可能较高
|
||
|
||
**缓解：**
|
||
- 串行执行确保一次只加载一个股票的数据
|
||
- 单个股票的数据量可控（10 年约几 MB）
|
||
- future 可考虑流式处理（非当前目标）
|
||
|
||
## Migration Plan
|
||
|
||
### Step 1: 创建 config.py
|
||
1. 从 `backtest.py` 提取数据库配置
|
||
2. 添加默认回测参数
|
||
3. 添加图表配色配置
|
||
4. 测试导入无错误
|
||
|
||
### Step 2: 创建 backtest_core.py
|
||
1. 迁移 `load_data_from_db()` 函数（导入 config）
|
||
2. 迁移 `load_strategy()` 函数
|
||
3. 迁移 `apply_color_scheme()` 函数（使用 config 配置）
|
||
4. 定义 `BacktestResult` 数据类
|
||
5. 实现 `run_backtest()` 函数
|
||
6. 实现 `run_batch_backtest()` 函数
|
||
7. 单元测试核心函数
|
||
|
||
### Step 3: 创建 backtest_command.py
|
||
1. 实现 `parse_arguments()` 函数（支持 `--codes`）
|
||
2. 实现 `format_single_result()` 函数（详细格式）
|
||
3. 实现 `format_batch_results()` 函数（使用 tabulate）
|
||
4. 实现 `main()` 函数（调用 `run_batch_backtest()`）
|
||
5. 测试单股票回测
|
||
6. 测试多股票回测
|
||
|
||
### Step 4: 更新依赖
|
||
1. 运行 `uv add tabulate` 添加依赖
|
||
2. 运行 `uv add tqdm` 添加依赖
|
||
3. 运行 `uv sync` 同步依赖
|
||
|
||
### Step 5: 删除 backtest.py
|
||
1. 确认新功能完整（单股票、多股票、图表输出）
|
||
2. 确认错误处理正确（立即失败）
|
||
3. 删除 `backtest.py` 文件
|
||
4. 更新 README 说明新的使用方式
|
||
|
||
### Rollback Strategy
|
||
如果迁移过程中发现问题：
|
||
1. 保留 `backtest.py` 直到 `backtest_command.py` 完全可用
|
||
2. 使用 `git` 版本控制，可随时回退
|
||
3. 逐步迁移（先核心函数，后 CLI），确保每步可验证
|
||
|
||
## Open Questions
|
||
|
||
1. **BacktestResult 字段完整性：** 是否需要包含所有 backtesting.stats 的键，或仅包含当前用到的字段？
|
||
- 倾向：仅包含当前用到的字段（未来可扩展）
|
||
|
||
2. **表格格式选择：** tabulate 支持多种格式（grid、simple、pipe、html），多股票结果使用哪种？
|
||
- 倾向：grid（美观的边框格式）
|
||
|
||
3. **进度条粒度：** tqdm 进度条应该显示每个股票的回测进度，还是仅显示批量回测的总进度？
|
||
- 倾向：仅显示批量回测的总进度（股票 N/M）
|
||
|
||
4. **图表输出目录结构：** 多股票图表是平铺在 `output/` 下，还是按日期/策略分组？
|
||
- 倾向：平铺在 `output/` 下（简单）
|