leopard-analysis/openspec/changes/archive/2026-01-28-refactor-backtest-separate-cli/design.md

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/ 下（简单）