leopard-analysis/openspec/changes/archive/2026-01-27-refactor-backtest-script/proposal.md

Proposal: Refactor Backtest Script

Why

当前回测系统使用 Jupyter Notebook (backtest.ipynb) 手动执行，存在以下问题：

• 不支持自动化批量回测，无法通过命令行调用
• 策略逻辑与数据获取混在一起，难以复用和切换
• 缺乏参数化配置，每次回测需要手动修改代码
• 无法方便地对比不同策略在同一股票、不同时间段的表现

通过将回测流程重构为命令行工具，可以实现：

• 支持命令行参数化调用，便于批量执行
• 策略模块化，支持动态加载不同的策略文件
• 简化数据加载逻辑，专注于回测核心流程
• 提高代码可维护性和可扩展性

What Changes

新增文件

1. backtest.py - 主流程脚本

   • 命令行参数解析 (--code, --start-date, --end-date, --strategy-file, --cash, --commission, --output)
   • 数据库连接与数据加载（查询复权后的价格数据）
   • 动态加载策略文件（通过 importlib）
   • 执行回测（使用 backtesting 库）
   • 结果输出：
     • 控制台中文格式化统计信息
     • HTML 图表文件（可选，通过 --output 参数控制）

2. strategy.py - 策略模板文件

   • calculate_indicators(data) 函数：计算策略所需的技术指标（如 SMA、MACD）
   • get_strategy() 函数：返回策略类
   • SmaCross 类：继承 backtesting.Strategy，实现交易逻辑（金叉买入、死叉卖出）

主要功能特性

• 动态策略加载：通过 --strategy-file 参数指定任意策略文件
• 简化的数据库访问：直接 SQL 查询获取数据，不引入额外抽象
• 指标计算策略化：每个策略文件自己定义需要计算的指标
• 结果输出控制：默认控制台输出，通过 --output 参数生成 HTML 图表

现有文件变更

• 无（新增文件，不修改现有 Notebook）

Capabilities

New Capabilities

• backtest-cli: 命令行回测工具，支持通过参数化方式执行量化回测
• strategy-loading: 动态加载策略模块，支持从指定路径导入策略类和指标计算函数
• data-fetching: 从 PostgreSQL 数据库获取股票历史价格数据，自动处理复权

Modified Capabilities

• 无（不涉及现有规范级别的需求变更）

Impact

代码影响

• 新增 backtest.py 作为主入口文件
• 新增 strategy.py 作为策略模板
• 可选新增 strategies/ 目录存放其他策略文件

依赖影响

新增依赖：

• sqlalchemy - 数据库连接
• backtesting - 回测引擎
• pandas, numpy - 数据处理（已存在于 Notebook 中）

API/系统影响

• 无外部 API 变更
• 数据库查询逻辑从 Notebook 迁移到 Python 脚本
• 输出从 Notebook 交互式展示改为命令行 + HTML 文件

用户影响

• 用户可以通过命令行执行回测，无需打开 Jupyter Notebook
• 策略开发者可以独立开发策略文件，通过约定接口集成到主流程
• 回测结果以 HTML 文件形式保存，便于分享和查看