添加后缀映射功能

README.md

@@ -11,10 +11,13 @@ mt5_backtest/
 │   ├── ini_generator.py         # 生成MT5配置文件
 │   ├── mt5_auto_runner.py       # 自动运行回测
 │   ├── batch_executor.py        # 批量执行器
-│   ├── result_parser.py        # 解析HTM/XML报告
-│   └── report_generator.py     # 生成汇总报告
+│   ├── result_parser.py         # 解析HTM/XML报告
+│   ├── report_generator.py      # 生成汇总报告
+│   ├── symbol_resolver.py       # 根品种别名解析（XAUUSD→XAUUSDc）
+│   └── optimizer/               # EA参数优化系统
 ├── config/                      # 配置文件目录
 ├── reports/                     # 回测报告输出目录
+├── tests/                       # 自检脚本（test_*.py / smoke_*.py）
 ├── logs/                        # 日志目录
 └── README.md                    # 本文档
 ```
@@ -26,6 +29,7 @@ mt5_backtest/
 - 扫描 MT5 的 `MQL5/Experts` 目录获取 EA 列表
 - 根据配置的 EA品种、时间周期、参数组合生成 INI 配置文件
 - 每个 INI 文件对应一次回测任务
+- 写入 INI 的 `Symbol=` 行通过 `scripts/symbol_resolver.py` 查表替换（见下文"根品种别名映射"）
 
 ### 2. 自动执行阶段 (mt5_auto_runner.py)
 - 通过命令行调用 MT5 终端: `terminal64.exe /config:xxx.ini`
@@ -79,6 +83,10 @@ eas:
 backtest_settings:
   symbols: ["EURUSD", "GBPUSD", "XAUUSD", "USDJPY"]
   timeframes: ["M1", "M5", "M15", "H1"]
+  # 可选：根品种别名映射（见下文"根品种别名映射"）
+  # symbol_aliases:
+  #   XAUUSD: XAUUSDc        # 逻辑 XAUUSD -> 实际 XAUUSDc
+  #   XAGUSD: XAGUSDm        # 逻辑 XAGUSD -> 实际 XAGUSDm
   date_range:
     from: "2026.01.01"
     to: "2026.01.04"
@@ -147,6 +155,66 @@ backtest_settings:
 | 原油 | XBRUSD, XTIUSD |
 | 数字货币 | BTCUSD, ETHUSD, LTCUSD |
 
+## 根品种别名映射 (`symbol_aliases`)
+
+MT5 自带品种（如 `XAUUSD`）历史深度和精度有限；用户常在 MT5 里添加自定义品种
+（如 `XAUUSDc` / `XAUUSDm`）作为更长时间范围或优化用途的"替身"。本系统通过 `symbol_aliases`
+让你在 yaml 里写一次逻辑品种名、由系统按表替换成实际 MT5 品种。
+
+### 写入 `config/ea_configs.yaml`
+
+```yaml
+backtest_settings:
+  symbols: [XAUUSD, XAGUSD, EURUSD]    # 用户的"逻辑品种"
+  symbol_aliases:
+    XAUUSD: XAUUSDc                    # 逻辑 XAUUSD -> 实际 XAUUSDc
+    XAGUSD: XAGUSDm                    # 逻辑 XAGUSD -> 实际 XAGUSDm
+    # EURUSD 不列 -> 始终 EURUSD
+```
+
+### 工作机制
+
+1. `scripts/ini_generator.py` 和 `scripts/optimizer/ea_batch_optimizer.py` 在
+   写 INI 的 `Symbol=` 之前调用 `scripts/symbol_resolver.resolve_symbol()`。
+2. 解析器是**纯查表**——没有任何"基于日期/优化/周期的智能判断"——写啥用啥：
+   - 别名表里有这个逻辑品种 → 用别名替换
+   - 没有 → 原样写入 `Symbol=`
+3. 两条调用路径共用同一份解析器（`scripts/symbol_resolver.py`），保证 GUI 回测页
+   和优化器生成的 INI 行为一致。
+
+### GUI 优化页
+
+GUI 优化页下拉只显示**逻辑品种**（不再同时列出 XAUUSD / XAUUSDc）。旁边有一个
+`→ XAUUSDc` 提示标签，**实时反映 yaml 里 `symbol_aliases` 当前配置下实际会用什么品种**。
+改 yaml 后重启 GUI 即可看到提示变化，无需在 GUI 里反复切换。
+
+### 验证
+
+无需 MT5 也能验：
+
+```bash
+python tests/test_symbol_resolver.py    # 9 条查表断言
+python tests/test_ini_generator.py      # 5 条端到端断言
+```
+
+需要 MT5 验证完整流水线：
+
+```bash
+python tests/smoke_alias_backtest.py
+# 跑两次真实回测：一次无别名 (Symbol=XAUUSD)，一次有别名 (Symbol=XAUUSDc)
+# 期望：C:\Users\Administrator\Desktop\mt5-backtest\reports 下生成两份 .htm 报告
+#       报告"交易品种"字段分别是 XAUUSD 和 XAUUSDc
+```
+
+> 注：`smoke_alias_backtest.py` 顶部硬编码了 MT5 路径和 data dir hash，复制到其他电脑后
+> 需要相应修改 `MT5_PATH` / `MT5_DATA_DIR` 常量。
+
+### 扩展点（ponytail）
+
+`scripts/symbol_resolver.py` 是共享函数入口，将来要把"配置源"切换成数据库或要做
+MT5 `SymbolSelect` 校验，**只改这一个文件**即可，所有调用方（ini 生成器、批量优化器、
+GUI 预览）同步生效。
+
 ## 如何添加新的时间周期
 
 编辑 `config/ea_configs.yaml`：
@@ -537,6 +605,7 @@ mt5_backtest/
 │   ├── batch_executor.py        # 批量执行器
 │   ├── result_parser.py        # 解析HTM/XML报告
 │   ├── report_generator.py     # 生成汇总报告
+│   ├── symbol_resolver.py     # 根品种别名解析（symbol_aliases 查表）
 │   └── optimizer/              # EA优化系统
 │       ├── ea_config_parser.py  # EA配置解析
 │       ├── smart_search.py      # 搜索策略
@@ -545,6 +614,7 @@ mt5_backtest/
 │       └── ea_batch_optimizer.py # 批量优化器
 ├── config/                      # 配置文件
 ├── reports/                     # 回测报告目录
+├── tests/                       # 自检脚本（test_symbol_resolver / test_ini_generator / smoke_alias_backtest）
 ├── optimizer/                   # 优化系统目录
 │   ├── configs/               # EA配置
 │   ├── set_files/             # SET文件
@@ -566,6 +636,19 @@ mt5_backtest/
 ### Q: 中文显示乱码
 HTM 报告采用 UTF-16-LE 编码，result_parser.py 会自动处理，无需手动转换
 
+### Q: 想用 MT5 自定义品种（如 XAUUSDc）跑同一 EA
+在 `config/ea_configs.yaml` 的 `backtest_settings` 下加：
+```yaml
+symbol_aliases:
+  XAUUSD: XAUUSDc
+```
+yaml 符号表里仍写 `XAUUSD`，系统会自动把 INI 的 `Symbol=` 替换为 `XAUUSDc`。
+详见上文"根品种别名映射"一节。
+
+### Q: 改了 `symbol_aliases` 后 GUI 提示没变
+GUI 启动时读取一次 `config/ea_configs.yaml`，改完后重启 GUI 即可看到
+`→ XAUUSDc` 提示标签更新。无需重新生成报告历史。
+
 ## 许可证
 
 MIT License