Fix strategy regression baselines and tooling

Author: cloudQuant

.gitignore

@@ -144,4 +144,54 @@ report.html
 backtrader_master_tests_report.html
 backtrader_remove_metaprogramming_report.html
 backtrader_remove_metaprogramming_report_timing.json
-backtrader-master/*
+backtrader-master/*
+
+# Generated regression test baselines (per-strategy run.py produces them locally)
+tests/functional/strategies_regression/
+
+# Large local market data fixtures (1GB+, not suitable for git)
+tests/functional/datas/
+
+# Runtime / generated artifacts
+logs/
+examples/logs/
+*.log
+bandit-report.json
+bandit-report.*.json
+
+# Matplotlib runtime font cache
+.mplconfig/
+docs/.mplconfig/
+
+# Internal / personal docs (may contain credentials, real account info, etc.)
+docs/_internal/
+
+# Live trading certification artefacts (CTP penetration test credentials, etc.)
+examples/live_certification/
+
+# Reference-only local documentation config
+.readthedocs-zh.yaml
+
+# Local data copied for experiments; current tests do not reference these paths
+tests/datas/CFFEX_Futures_Contract_Data.csv
+tests/datas/ChiNext_ETF.csv
+tests/datas/SSE50_ETF.csv
+tests/datas/binance_bbo_demo/
+tests/datas/tick_data/
+
+# Local agent / planning workspaces
+_bmad/
+_bmad-output/
+.kiro/
+.opencode/
+.claude/
+.cursor/
+.windsurf/
+
+# Editor settings
+.vscode/
+
+# Misc local files
+*.csv.bak
+*.tmp
+*.bak

README.en.md

@@ -2,21 +2,21 @@
 
 English | [中文](README.md)
 
-[![Tests](https://github.com/yunjinqi/backtrader/actions/workflows/tests.yml/badge.svg)](https://github.com/yunjinqi/backtrader/actions/workflows/tests.yml)
-[![Build](https://github.com/yunjinqi/backtrader/actions/workflows/publish.yml/badge.svg)](https://github.com/yunjinqi/backtrader/actions/workflows/publish.yml)
-[![CodeQL](https://github.com/yunjinqi/backtrader/actions/workflows/codeql.yml/badge.svg)](https://github.com/yunjinqi/backtrader/actions/workflows/codeql.yml)
-[![Python Versions](https://img.shields.io/pypi/pyversions/backtrader.svg)](https://pypi.org/project/backtrader/)
-[![PyPI Version](https://img.shields.io/pypi/v/backtrader.svg)](https://pypi.org/project/backtrader/)
-[![License](https://img.shields.io/badge/license-GPL-blue.svg)](LICENSE)
+[![CI Tests](https://github.com/cloudQuant/backtrader/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/cloudQuant/backtrader/actions/workflows/tests.yml)
+[![Python](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-GPL%203.0-green)](LICENSE)
+[![Code style: flake8](https://img.shields.io/badge/code%20style-flake8-black)](https://flake8.pycqa.org/)
+[![GitHub stars](https://img.shields.io/github/stars/cloudQuant/backtrader?style=social)](https://github.com/cloudQuant/backtrader/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/cloudQuant/backtrader?style=social)](https://github.com/cloudQuant/backtrader/network/members)
+[![Gitee](https://img.shields.io/badge/mirror-Gitee-red)](https://gitee.com/yunjinqi/backtrader)
 
 ## Introduction
 
-A high-performance quantitative research tool built on backtrader, focused on medium-to-low frequency trading strategies with Cython/Numba optimizations for improved backtesting efficiency. This project is an enhanced version of backtrader that maintains compatibility while adding numerous practical features.
+An enhanced version of the backtrader Python library for quantitative trading and backtesting. This project keeps compatibility with the original backtrader while adding cryptocurrency support, futures-market integrations, extra testing utilities, and improved stability across Python 3.8-3.13.
 
 ### Core Features
 
-- 🚀 **Performance Optimization**: Core computation modules optimized with Cython and Numba for significantly faster backtesting
-- 📊 **Vectorized Backtesting**: Support for Time Series (TS) and Cross-Sectional (CS) vectorized backtesting frameworks
+- � **Event-Driven Architecture**: Fast and efficient event-driven backtesting engine
 - 🪙 **Cryptocurrency Support**:
   - CCXT integration supporting 100+ cryptocurrency exchanges
   - Funding rate backtesting for crypto perpetual contracts
@@ -26,8 +26,10 @@ A high-performance quantitative research tool built on backtrader, focused on me
   - CTP futures trading interface
   - Oanda forex trading
   - Traditional stock markets
-- 📈 **Rich Technical Indicators**: 60+ built-in technical indicators with custom indicator development support
-- 📝 **Strategy Analyzers**: Multiple performance analysis tools (Sharpe ratio, maximum drawdown, SQN, etc.)
+- 📈 **Rich Technical Indicators**: 50+ built-in indicators with custom indicator development support
+- � **Comprehensive Analyzers**: Sharpe ratio, drawdown, trade statistics, PyFolio integration, and custom analyzers
+- 🎯 **Flexible Order Types**: Market, limit, stop, stop-limit, bracket, and OCO orders
+- 📉 **Data Processing**: Resampling, replaying, and multi-timeframe analysis
 
 ### Version Information
 
@@ -38,7 +40,7 @@ A high-performance quantitative research tool built on backtrader, focused on me
 
 ### System Requirements
 
-- Python 3.8 - 3.12 (Python 3.11 recommended for best performance)
+- Python 3.8 - 3.13 (Python 3.11 recommended for best performance)
 - Operating Systems: Windows, Linux, macOS
 
 ### Installation
@@ -141,7 +143,6 @@ cerebro.plot()
 
 ### 2. Strategy Development
 - Event-driven strategy framework
-- Vectorized strategy framework (CS/TS)
 - Multi-asset, multi-timeframe strategy support
 - Signal system
 
@@ -192,39 +193,17 @@ data = store.getdata(
 cerebro.adddata(data)
 ```
 
-### Vectorized Backtesting Example
-
-```python
-# Time series vectorized strategy
-from backtrader.vectors import TimeSeriesStrategy
-
-class MyTSStrategy(TimeSeriesStrategy):
-    def compute_signal(self, data):
-        # Use numpy for vectorized calculations
-        sma_20 = data['close'].rolling(20).mean()
-        sma_50 = data['close'].rolling(50).mean()
-        
-        # Generate signals
-        signal = (sma_20 > sma_50).astype(int)
-        return signal
-```
-
 ## Documentation & Resources
 
+- 📚 [Project Documentation Index](docs/README.md)
+- 🛠️ [Installation & Troubleshooting Guide](docs/INSTALLATION_GUIDE.md)
+- 🧾 [Changelog](docs/CHANGELOG.md)
+- 🐛 [DataTrades Fix Note](docs/DATATRADES_FIX.md)
+- 🔌 [ExtendPandasFeed Fix Note](docs/EXTENDED_FEED_FIX.md)
 - 📚 [Official Documentation](https://www.backtrader.com/)
 - 📝 [CSDN Tutorial Series](https://blog.csdn.net/qq_26948675/category_10220116.html)
 - 💬 [Issue Tracker](https://gitee.com/yunjinqi/backtrader/issues)
-- 🔧 [Development Guide](CONTRIBUTING.md)
-
-## Performance Comparison
-
-Performance improvements with Cython optimization:
-
-| Module | Original Speed | Optimized Speed | Improvement |
-|--------|---------------|-----------------|-------------|
-| Indicator Calculations | 1.00x | 3-5x | 200-400% |
-| Vectorized Backtesting | N/A | 10-20x | - |
-| Order Matching | 1.00x | 2-3x | 100-200% |
+- 🔧 [Development Guide](CLAUDE.md)
 
 ## Contributing
 
@@ -238,18 +217,22 @@ We welcome code contributions, bug reports, and feature suggestions:
 
 ## Changelog
 
-### Latest Updates 2024
-- ✅ Added funding rate backtesting support for cryptocurrency
-- ✅ Fixed Python 3.12+ compatibility issues
-- ✅ Optimized Cython compilation process
+### 2026 Updates
+- ✅ Reorganized helper scripts under `scripts/`
+- ✅ Added the strategies regression framework (generated locally and gitignored)
+- ✅ Made `backtrader.analyzers.pyfolio` lazy-load `empyrical`
+
+### 2024 Updates
+- ✅ Added funding rate backtesting support for cryptocurrency perpetual contracts
+- ✅ Fixed Python 3.12 and 3.13 compatibility issues
+- ✅ Improved CCXT integration stability
 - ✅ Added CI/CD automated testing
 
 ### 2023 Updates
-- ✅ Implemented Time Series (TS) vectorized backtesting framework
-- ✅ Optimized Cross-Sectional (CS) strategy performance
+- ✅ Improved multi-exchange support
 - ✅ Fixed multiple known bugs
 
-For detailed changelog, see [CHANGELOG.md](CHANGELOG.md)
+For detailed changelog, see [docs/CHANGELOG.md](docs/CHANGELOG.md)
 
 ## License
 

README.md

@@ -464,12 +464,48 @@ class FundingRateStrategy(bt.Strategy):
 
 ### Documentation & Resources
 
-- 📚 [Official Backtrader Documentation](https://www.backtrader.com/)
+- 📚 [Project Documentation Index](docs/README.md)
+- 🛠️ [Installation & Troubleshooting Guide](docs/INSTALLATION_GUIDE.md)
+- 🧾 [Changelog](docs/CHANGELOG.md)
+- 🐛 [DataTrades Fix Note](docs/DATATRADES_FIX.md)
+- 🔌 [ExtendPandasFeed Fix Note](docs/EXTENDED_FEED_FIX.md)
+- 📖 [Official Backtrader Documentation](https://www.backtrader.com/)
 - 📝 [CSDN Tutorial Series (Chinese)](https://blog.csdn.net/qq_26948675/category_10220116.html)
 - 💬 [Issue Tracker - Gitee](https://gitee.com/yunjinqi/backtrader/issues)
 - 💬 [Issue Tracker - GitHub](https://github.com/cloudQuant/backtrader/issues)
 - 🔧 [Development Guide](CLAUDE.md)
 
+### Project Structure
+
+```
+backtrader/
+├── backtrader/                # Core framework package
+├── docs/                      # Project docs, changelog, installation guide, fix notes
+├── examples/                  # Runnable example projects
+├── scripts/                   # Maintenance & QA helper scripts
+│   ├── run_master_tests.py            # Full pytest run + HTML report
+│   ├── run_test_with_log.py           # Run a single test with branch-aware logging
+│   ├── sync_and_test.py               # Sync a test file across branches & run it
+│   ├── profile_performance.py         # cProfile-based strategy profiler
+│   ├── debug_macd_replay.py           # MACD-in-replay debugging harness
+│   ├── backtest_strategy_regression_expected.py  # Regression baseline generator
+│   ├── run_all_backtests.py           # Batch backtest runner
+│   └── test_python_versions_simple.sh/.bat  # Multi-version conda test runner
+├── strategies/                # Shared strategy helpers (e.g. benchmark_metrics)
+├── studies/                   # Research notebooks & UML
+├── tests/                     # Pytest test suites
+│   ├── original_tests/                # Upstream backtrader tests
+│   ├── strategies/                    # In-house strategy tests
+│   ├── funding_rate_examples/         # Crypto funding-rate tests
+│   └── functional/strategies_regression/  # 1000+ generated regression scripts (gitignored)
+├── pyproject.toml / setup.py / requirements.txt
+└── README.md / CLAUDE.md / LICENSE
+```
+
+> `tests/functional/strategies_regression/` is generated locally by
+> `scripts/backtest_strategy_regression_expected.py` and is intentionally
+> excluded from version control.
+
 ### Testing
 
 ```bash
@@ -480,11 +516,21 @@ pytest tests
 pytest tests --cov=backtrader --cov-report=html
 
 # Run specific test category
-pytest tests/original_tests  # Core functionality
-pytest tests/funding_rate_examples  # Crypto features
+pytest tests/original_tests        # Core functionality
+pytest tests/funding_rate_examples # Crypto features
+pytest tests/strategies            # In-house strategies
 
 # Run in parallel
 pytest tests -n 4
+
+# Convenience wrappers (always run from repo root)
+python scripts/run_master_tests.py                       # Full suite + HTML report
+python scripts/run_test_with_log.py tests/strategies/test_18_etf_rotation_strategy.py
+bash   scripts/test_python_versions_simple.sh            # Multi Python version sweep
+
+# Regenerate strategy regression baselines (long-running)
+python scripts/backtest_strategy_regression_expected.py \
+    tests/functional/strategies_regression --workers 4 --overwrite
 ```
 
 ### Contributing
@@ -499,6 +545,13 @@ We welcome code contributions, bug reports, and feature suggestions:
 
 ### Changelog
 
+#### 2026 Updates
+- ✅ Reorganised root-level helper scripts under `scripts/`
+- ✅ Added the strategies regression framework (1000+ per-strategy `run.py` baselines, generated locally and gitignored)
+- ✅ Made `backtrader.analyzers.pyfolio` lazy-load `empyrical` so `import backtrader` works without it on pandas 3
+- ✅ Replaced `risk_free_rate` keyword with `riskfreerate` for `SharpeRatio` across the regression suite
+- ✅ Normalised `comminfo.get_param('mult')` usage to `getattr(comminfo.p, 'mult', 1.0)`
+
 #### 2024 Updates
 - ✅ Added funding rate backtesting support for cryptocurrency perpetual contracts
 - ✅ Fixed Python 3.12 and 3.13 compatibility issues
@@ -511,7 +564,7 @@ We welcome code contributions, bug reports, and feature suggestions:
 - ✅ Fixed multiple known bugs
 - ✅ Enhanced CTP integration
 
-For detailed changelog, see [CHANGELOG.md](CHANGELOG.md) (if available)
+For detailed changelog, see [docs/CHANGELOG.md](docs/CHANGELOG.md)
 
 ### License
 
@@ -976,12 +1029,47 @@ class FundingRateStrategy(bt.Strategy):
 
 ### 文档与资源
 
-- 📚 [官方 Backtrader 文档](https://www.backtrader.com/)
+- 📚 [项目文档索引](docs/README.md)
+- 🛠️ [安装与环境排查](docs/INSTALLATION_GUIDE.md)
+- 🧾 [更新日志](docs/CHANGELOG.md)
+- 🐛 [DataTrades 修复说明](docs/DATATRADES_FIX.md)
+- 🔌 [ExtendPandasFeed 修复说明](docs/EXTENDED_FEED_FIX.md)
+- 📖 [官方 Backtrader 文档](https://www.backtrader.com/)
 - 📝 [CSDN 教程系列](https://blog.csdn.net/qq_26948675/category_10220116.html)
 - 💬 [问题反馈 - Gitee](https://gitee.com/yunjinqi/backtrader/issues)
 - 💬 [问题反馈 - GitHub](https://github.com/cloudQuant/backtrader/issues)
 - 🔧 [开发指南](CLAUDE.md)
 
+### 项目结构
+
+```
+backtrader/
+├── backtrader/                # 核心框架包
+├── docs/                      # 项目文档、更新日志、安装指南和修复说明
+├── examples/                  # 可运行示例项目
+├── scripts/                   # 辅助维护与 QA 脚本
+│   ├── run_master_tests.py            # 完整 pytest 运行 + HTML 报告
+│   ├── run_test_with_log.py           # 单个测试运行并按分支输出日志
+│   ├── sync_and_test.py               # 在分支间同步测试文件并对比运行
+│   ├── profile_performance.py         # 基于 cProfile 的策略性能分析
+│   ├── debug_macd_replay.py           # MACD replay 模式调试环境
+│   ├── backtest_strategy_regression_expected.py  # 回归基准生成器
+│   ├── run_all_backtests.py           # 批量回测运行器
+│   └── test_python_versions_simple.sh/.bat  # 多 Python 版本 conda 测试
+├── strategies/                # 公用策略辅助包（如 benchmark_metrics）
+├── studies/                   # 研究笔记与 UML 图
+├── tests/                     # Pytest 测试集
+│   ├── original_tests/                # 上游原版测试
+│   ├── strategies/                    # 自用策略测试
+│   ├── funding_rate_examples/         # 加密货币资金费率测试
+│   └── functional/strategies_regression/  # 1000+ 个生成的回归脚本（已加入 .gitignore）
+├── pyproject.toml / setup.py / requirements.txt
+└── README.md / CLAUDE.md / LICENSE
+```
+
+> `tests/functional/strategies_regression/` 由
+> `scripts/backtest_strategy_regression_expected.py` 本地生成，不跟随仓库提交。
+
 ### 测试
 
 ```bash
@@ -992,11 +1080,21 @@ pytest tests
 pytest tests --cov=backtrader --cov-report=html
 
 # 运行特定测试类别
-pytest tests/original_tests  # 核心功能
-pytest tests/funding_rate_examples  # 加密货币特性
+pytest tests/original_tests        # 核心功能
+pytest tests/funding_rate_examples # 加密货币特性
+pytest tests/strategies            # 自用策略
 
 # 并行运行
 pytest tests -n 4
+
+# 便捷包装脚本（始终从仓库根目录运行）
+python scripts/run_master_tests.py                       # 完整测试套件 + HTML 报告
+python scripts/run_test_with_log.py tests/strategies/test_18_etf_rotation_strategy.py
+bash   scripts/test_python_versions_simple.sh            # 多 Python 版本扫描
+
+# 重新生成策略回归基准（耗时较长）
+python scripts/backtest_strategy_regression_expected.py \
+    tests/functional/strategies_regression --workers 4 --overwrite
 ```
 
 ### 贡献指南
@@ -1011,6 +1109,13 @@ pytest tests -n 4
 
 ### 更新日志
 
+#### 2026年更新
+- ✅ 根目录辅助脚本全部归档到 `scripts/`
+- ✅ 新增策略回归测试框架（1000+ 个以策略为粒度的 `run.py`基准，本地生成、已 gitignore）
+- ✅ `backtrader.analyzers.pyfolio` 改为懒加载 `empyrical`，在 pandas 3 下也能正常 `import backtrader`
+- ✅ 策略回归套件中将 `SharpeRatio` 的 `risk_free_rate` 参数统一改为 `riskfreerate`
+- ✅ 将 `comminfo.get_param('mult')` 调用统一为 `getattr(comminfo.p, 'mult', 1.0)`
+
 #### 2024年更新
 - ✅ 增加了加密货币永续合约资金费率回测支持
 - ✅ 修复了 Python 3.12 和 3.13 兼容性问题
@@ -1023,7 +1128,7 @@ pytest tests -n 4
 - ✅ 修复了多个已知 bug
 - ✅ 增强了 CTP 集成
 
-详细更新日志请查看 [CHANGELOG.md](CHANGELOG.md)（如果有）
+详细更新日志请查看 [docs/CHANGELOG.md](docs/CHANGELOG.md)
 
 ### 许可证