# EA Bridge 接入说明

## 1. 桥接目录（Wine 共享目录）

Python 和 EA 通过 Wine 共享目录交换文件，路径完全对齐：

| 操作 | 路径 |
|------|------|
| Python 写请求 | `Terminal/Common/Files/gold_autotrade/bridge/to_ea/<signal_id>.request.json` |
| EA 写回执 | `Terminal/Common/Files/gold_autotrade/bridge/from_ea/<signal_id>.report.json` |
| EA 写行情快照 | `Terminal/Common/Files/gold_autotrade/bridge/market_snapshot.json` |
| Python 归档 | `data/bridge/archive/<signal_id>.report.json` |

**EA 端 BridgeRoot 参数**（在 EA 属性里设置）：
```
gold_autotrade/bridge
```

EA 会自动解析为 `Terminal/Common/Files/gold_autotrade/bridge/`，与 Python 写入路径完全一致。

> **注意**：Python 端会优先探测 Wine `Terminal/Common/Files`，找不到时再探测 `MQL5/Files`。Linux 无 Wine 时自动降级到项目目录 `data/bridge/`。

## 2. Python 侧运行

```bash
cd /path/to/gold_autotrade
python3 src/pipeline.py \
  --source ea_feed \
  --runtime-intent live_trade \
  --execution-mode ea_bridge \
  --symbol XAUUSD \
  --timeframe M5 \
  --input-path data/inbox/request.json \
  --output-path data/outbox/signal.json \
  --once
```

`--source ea_feed` 使用 EA 写回的 `market_snapshot.json` 作为实时行情与指标来源，不依赖 Python MetaTrader5 模块。

## 3. MT5 EA 侧部署

1. 把 `bridge/GoldAutoTradeBridgeEA.mq5` 放到 MT5 `MQL5/Experts` 目录并编译
2. 拖到 XAUUSD 图表上，保持自动交易开启
3. **确认 EA 属性中 `BridgeRoot` = `gold_autotrade/bridge`**
4. EA 每秒轮询 `to_ea/` 发现请求文件，执行后写回执到 `from_ea/`

## 4. 超时配置

EA 轮询间隔由 `TimerSeconds` 参数控制（默认 1 秒）。

Python 等待回执超时由 `EA_BRIDGE_TIMEOUT_S` 控制（默认 30 秒）。可通过 `execution_report_path.with_suffix(".timeout")` 文件自定义单次超时。

## 5. 回执格式

```json
{
  "signal_id": "sig_xxx",
  "status": "FILLED",
  "reason": "ORDER_FILLED",
  "order_id": 123456,
  "deal_id": 654321
}
```

可用 `status`：`FILLED` / `ACKED` / `REJECTED` / `TIMEOUT` / `RECONCILED` / `PARTIAL_FILL` / `RETRY_EXHAUSTED`
