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

Why

当前 backtest.py 存在职责混杂的问题：命令行参数解析、核心回测逻辑、数据访问、结果展示都耦合在单一文件中，导致：

• 难以在其他模块中复用回测功能
• 无法进行单元测试
• 仅支持单股票回测，无法批量处理

需要重构为分层架构，将核心逻辑与 CLI 界面分离，提升代码复用性和可维护性。

What Changes

• 创建 config.py：集中管理数据库配置、默认回测参数、图表配色
• 创建 backtest_core.py：核心回测引擎
  • 提供标准化接口 run_backtest()（单股票）
  • 提供批量接口 run_batch_backtest()（多股票，串行执行）
  • 封装数据访问和策略加载逻辑
  • 返回结构化结果对象 BacktestResult
• 创建 backtest_command.py：命令行界面
  • 支持多股票代码参数 --codes（接受多个值）
  • 使用 tabulate 优化批量结果的表格展示
  • 使用 tqdm 显示批量回测进度条
  • 保留原有的单股票详细输出格式
• 删除 backtest.py：不再需要，功能已迁移
• 依赖更新：添加 tabulate、tqdm 到项目依赖

Capabilities

New Capabilities

• batch-backtest: 批量回测功能，支持传入多个股票代码进行串行回测，并提供进度条和表格化结果展示

Modified Capabilities

• 无（其他均为实现重构，不改变 spec 级别行为）

Impact

• 代码影响：
  • 删除 backtest.py（284 行）
  • 新增 config.py（约 30 行）
  • 新增 backtest_core.py（约 250 行）
  • 新增 backtest_command.py（约 150 行）
• API 变化：
  • 新增 run_backtest(code, start_date, end_date, strategy_file, ...) 函数
  • 新增 run_batch_backtest(codes, start_date, end_date, strategy_file, ...) 函数
  • 新增 BacktestResult 数据类
• 命令行变化：
  • 单参数 --code 改为多值参数 --codes
  • 新增 --output-dir 参数，为每个股票生成独立 HTML 图表
  • 批量回测时显示进度条和表格化结果
• 依赖变化：
  • 新增 tabulate（表格格式化）
  • 新增 tqdm（进度条显示）
• 兼容性：
  • BREAKING: 删除原有 backtest.py，命令行使用方式从 python backtest.py 改为 uv run python backtest_command.py
  • 参数名称从 --code 改为 --codes