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

1. 依赖管理

• 1.1 运行 uv add tabulate 添加依赖
• 1.2 运行 uv add tqdm 添加依赖
• 1.3 运行 uv sync 同步依赖

2. 配置管理模块

• 2.1 创建 config.py 文件
• 2.2 在 config.py 中定义数据库配置常量（DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD）
• 2.3 在 config.py 中定义默认回测参数（DEFAULT_CASH, DEFAULT_COMMISSION, DEFAULT_WARMUP_DAYS）
• 2.4 在 config.py 中定义图表配色（BULL_COLOR, BEAR_COLOR）
• 2.5 测试 config.py 导入无错误

3. 核心回测引擎

• 3.1 创建 backtest_core.py 文件
• 3.2 在 backtest_core.py 中导入必要模块和 config
• 3.3 定义 BacktestResult dataclass（包含所有回测指标字段）
• 3.4 迁移 load_data_from_db() 函数（使用 config 数据库配置）
• 3.5 迁移 load_strategy() 函数（保持原有逻辑）
• 3.6 迁移 apply_color_scheme() 函数（使用 config 配色）
• 3.7 实现 run_backtest() 函数（单股票回测）
  • 3.7.1 实现预热期日期计算逻辑
  • 3.7.2 实现数据加载和策略加载调用
  • 3.7.3 实现指标计算和数据截取
  • 3.7.4 实现 Backtest 执行
  • 3.7.5 实现图表生成（可选）
  • 3.7.6 实现 BacktestResult 对象构建和返回
• 3.8 实现 run_batch_backtest() 函数（批量回测，串行）
  • 3.8.1 实现循环遍历股票代码
  • 3.8.2 实现为每个股票调用 run_backtest()
  • 3.8.3 实现为每个股票生成独立 HTML 文件
  • 3.8.4 实现结果列表收集和返回
  • 3.8.5 实现 tqdm 进度条显示（批量时）
• 3.9 测试 run_backtest() 单股票回测
• 3.10 测试 run_batch_backtest() 多股票回测

4. CLI 界面模块

• 4.1 创建 backtest_command.py 文件
• 4.2 在 backtest_command.py 中导入必要模块和 backtest_core
• 4.3 实现 parse_arguments() 函数
  • 4.3.1 定义 --codes 多值参数（nargs='+'）
  • 4.3.2 定义 --output-dir 目录参数
  • 4.3.3 保持原有参数（--start-date, --end-date, --strategy-file, --cash, --commission, --warmup-days）
  • 4.3.4 添加参数帮助文档和示例
• 4.4 实现 format_single_result() 函数（详细格式输出）
  • 4.4.1 实现每个指标单独一行的格式化
  • 4.4.2 保持原有 print_stats() 的输出格式
• 4.5 实现 format_batch_results() 函数（表格格式输出）
  • 4.5.1 实现使用 tabulate 生成表格
  • 4.5.2 定义表格列：股票代码、收益率%、胜率%、最大回撤%、交易次数、SQN
  • 4.5.3 实现表格数据填充（从 BacktestResult 对象提取）
  • 4.5.4 实现表格格式为 grid
• 4.6 实现 main() 函数
  • 4.6.1 调用 parse_arguments() 解析参数
  • 4.6.2 调用 run_batch_backtest() 执行批量回测
  • 4.6.3 根据结果数量调用 format_single_result() 或 format_batch_results()
  • 4.6.4 实现图表保存提示（指定 --output-dir 时）
  • 4.6.5 实现错误捕获和友好错误信息输出
  • 4.6.6 实现退出状态码设置（成功 0，失败非零）
• 4.7 添加 if __name__ == "__main__": main() 入口
• 4.8 测试单股票回测命令行调用 (uv run python backtest_command.py)
• 4.9 测试多股票回测命令行调用 (uv run python backtest_command.py)
• 4.10 测试错误处理（参数缺失、文件不存在等）

5. 清理旧代码

• 5.1 确认新功能完整（单股票、多股票、图表输出）
• 5.2 确认错误处理正确（立即失败）
• 5.3 删除 backtest.py 文件
• 5.4 验证 git 状态（仅删除旧文件，无其他修改）

6. 文档更新

• 6.1 更新 README.md（如果存在）
  • 6.1.1 说明新的命令行使用方式（uv run python backtest_command.py）
  • 6.1.2 说明参数变化（--code 改为 --codes）
  • 6.1.3 提供单股票和多股票示例
  • 6.1.4 说明 --output-dir 用法（多股票图表）
• 6.2 创建 note_refactor.md（可选，记录重构说明）
  • 6.2.1 说明文件结构变化
  • 6.2.2 说明接口变化
  • 6.2.3 提供迁移指南

7. 集成测试

• 7.1 测试单个股票完整流程（000001.SZ）
• 7.2 测试多个股票完整流程（000001.SZ 600000.SH）
• 7.3 测试指定 --output-dir 生成图表
• 7.4 测试不指定 --output-dir（不生成图表）
• 7.5 测试错误情况（无效股票代码、不存在的策略文件等）
• 7.6 验证进度条显示（多股票时）
• 7.7 验证表格格式输出（多股票时）
• 7.8 验证详细格式输出（单股票时）