重构回测代码架构，新增批量回测功能

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

@@ -0,0 +1,96 @@
+## 1. 依赖管理
+
+- [x] 1.1 运行 `uv add tabulate` 添加依赖
+- [x] 1.2 运行 `uv add tqdm` 添加依赖
+- [x] 1.3 运行 `uv sync` 同步依赖
+
+## 2. 配置管理模块
+
+- [x] 2.1 创建 config.py 文件
+- [x] 2.2 在 config.py 中定义数据库配置常量（DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD）
+- [x] 2.3 在 config.py 中定义默认回测参数（DEFAULT_CASH, DEFAULT_COMMISSION, DEFAULT_WARMUP_DAYS）
+- [x] 2.4 在 config.py 中定义图表配色（BULL_COLOR, BEAR_COLOR）
+- [x] 2.5 测试 config.py 导入无错误
+
+## 3. 核心回测引擎
+
+- [x] 3.1 创建 backtest_core.py 文件
+- [x] 3.2 在 backtest_core.py 中导入必要模块和 config
+- [x] 3.3 定义 BacktestResult dataclass（包含所有回测指标字段）
+- [x] 3.4 迁移 load_data_from_db() 函数（使用 config 数据库配置）
+- [x] 3.5 迁移 load_strategy() 函数（保持原有逻辑）
+- [x] 3.6 迁移 apply_color_scheme() 函数（使用 config 配色）
+- [x] 3.7 实现 run_backtest() 函数（单股票回测）
+  - [x] 3.7.1 实现预热期日期计算逻辑
+  - [x] 3.7.2 实现数据加载和策略加载调用
+  - [x] 3.7.3 实现指标计算和数据截取
+  - [x] 3.7.4 实现 Backtest 执行
+  - [x] 3.7.5 实现图表生成（可选）
+  - [x] 3.7.6 实现 BacktestResult 对象构建和返回
+- [x] 3.8 实现 run_batch_backtest() 函数（批量回测，串行）
+  - [x] 3.8.1 实现循环遍历股票代码
+  - [x] 3.8.2 实现为每个股票调用 run_backtest()
+  - [x] 3.8.3 实现为每个股票生成独立 HTML 文件
+  - [x] 3.8.4 实现结果列表收集和返回
+  - [x] 3.8.5 实现 tqdm 进度条显示（批量时）
+- [x] 3.9 测试 run_backtest() 单股票回测
+- [x] 3.10 测试 run_batch_backtest() 多股票回测
+
+## 4. CLI 界面模块
+
+- [x] 4.1 创建 backtest_command.py 文件
+- [x] 4.2 在 backtest_command.py 中导入必要模块和 backtest_core
+- [x] 4.3 实现 parse_arguments() 函数
+  - [x] 4.3.1 定义 --codes 多值参数（nargs='+'）
+  - [x] 4.3.2 定义 --output-dir 目录参数
+  - [x] 4.3.3 保持原有参数（--start-date, --end-date, --strategy-file, --cash, --commission, --warmup-days）
+  - [x] 4.3.4 添加参数帮助文档和示例
+- [x] 4.4 实现 format_single_result() 函数（详细格式输出）
+  - [x] 4.4.1 实现每个指标单独一行的格式化
+  - [x] 4.4.2 保持原有 print_stats() 的输出格式
+- [x] 4.5 实现 format_batch_results() 函数（表格格式输出）
+  - [x] 4.5.1 实现使用 tabulate 生成表格
+  - [x] 4.5.2 定义表格列：股票代码、收益率%、胜率%、最大回撤%、交易次数、SQN
+  - [x] 4.5.3 实现表格数据填充（从 BacktestResult 对象提取）
+  - [x] 4.5.4 实现表格格式为 grid
+- [x] 4.6 实现 main() 函数
+  - [x] 4.6.1 调用 parse_arguments() 解析参数
+  - [x] 4.6.2 调用 run_batch_backtest() 执行批量回测
+  - [x] 4.6.3 根据结果数量调用 format_single_result() 或 format_batch_results()
+  - [x] 4.6.4 实现图表保存提示（指定 --output-dir 时）
+  - [x] 4.6.5 实现错误捕获和友好错误信息输出
+  - [x] 4.6.6 实现退出状态码设置（成功 0，失败非零）
+- [x] 4.7 添加 `if __name__ == "__main__": main()` 入口
+- [x] 4.8 测试单股票回测命令行调用 (`uv run python backtest_command.py`)
+- [x] 4.9 测试多股票回测命令行调用 (`uv run python backtest_command.py`)
+- [x] 4.10 测试错误处理（参数缺失、文件不存在等）
+
+## 5. 清理旧代码
+
+- [x] 5.1 确认新功能完整（单股票、多股票、图表输出）
+- [x] 5.2 确认错误处理正确（立即失败）
+- [x] 5.3 删除 backtest.py 文件
+- [x] 5.4 验证 git 状态（仅删除旧文件，无其他修改）
+
+## 6. 文档更新
+
+- [x] 6.1 更新 README.md（如果存在）
+  - [x] 6.1.1 说明新的命令行使用方式（`uv run python backtest_command.py`）
+  - [x] 6.1.2 说明参数变化（--code 改为 --codes）
+  - [x] 6.1.3 提供单股票和多股票示例
+  - [x] 6.1.4 说明 --output-dir 用法（多股票图表）
+- [x] 6.2 创建 note_refactor.md（可选，记录重构说明）
+  - [x] 6.2.1 说明文件结构变化
+  - [x] 6.2.2 说明接口变化
+  - [x] 6.2.3 提供迁移指南
+
+## 7. 集成测试
+
+- [x] 7.1 测试单个股票完整流程（000001.SZ）
+- [x] 7.2 测试多个股票完整流程（000001.SZ 600000.SH）
+- [x] 7.3 测试指定 --output-dir 生成图表
+- [x] 7.4 测试不指定 --output-dir（不生成图表）
+- [x] 7.5 测试错误情况（无效股票代码、不存在的策略文件等）
+- [x] 7.6 验证进度条显示（多股票时）
+- [x] 7.7 验证表格格式输出（多股票时）
+- [x] 7.8 验证详细格式输出（单股票时）