# Gold Autotrade 落地包

本目录提供可直接执行的策略工程规则，不包含空泛概念。

## 目录说明

- `config/data_quality_rules.json`：MT5 数据真实性与完整性规则
- `config/risk_governor_rules.json`：不可绕过的风险裁决规则
- `config/agent_orchestration_rules.json`：openclaw 多 Agent 编排与冲突处理规则
- `config/token_latency_budget.json`：token 成本与时效预算规则
- `config/webhook_profiles.json`：飞书/QQ webhook 字段映射规则
- `contracts/ai_trade_plan.schema.json`：AI 交易计划输入契约
- `contracts/signal.schema.json`：执行信号输出契约
- `ops/chat_command_rules.json`：QQ/飞书对话调参规则
- `ops/release_gates.json`：灰度发布与回滚门禁规则
- `runbooks/incident_playbooks.json`：自动检测与故障处置剧本
- `src/pipeline.py`：部署运行入口，包含 MT5 输入适配、决策执行、异常检测
- `src/execution_state.py`：执行状态机与幂等对账
- `src/ledger.py`：决策账本落盘
- `src/chat_tuning.py`：QQ/飞书命令调参与审批执行
- `src/mt5_execution.py`：MT5 下单与回执分发（file/mock/direct/ea_bridge）
- `src/control_api.py`：控制面 API（健康检查、调参、停机）
- `src/tenant_manager.py`：租户配置隔离与租户工作空间管理
- `src/config_snapshot.py`：租户配置快照与回滚能力
- `src/webhook_adapter.py`：Webhook 平台字段映射适配
- `deploy/run_local.sh`：本地一键启动脚本
- `deploy/docker-compose.yml`：容器化部署入口
- `deploy/install_app.sh`：安装发布脚本
- `deploy/upgrade_app.sh`：升级发布脚本
- `deploy/rollback_app.sh`：回滚发布脚本
- `deploy/release_manager.py`：发布版本管理器
- `ops/e2e_smoke.sh`：端到端烟雾测试脚本
- `ops/mt5_direct_stress.py`：MT5 direct 模式压测脚本
- `ops/ea_bridge_guide.md`：MT5 Bridge EA 对接说明
- `bridge/GoldAutoTradeBridgeEA.mq5`：桥接 EA 模板

## 执行顺序

1. 先校验输入是否符合 `ai_trade_plan.schema.json`
2. 执行 `data_quality_rules.json`，失败则拒绝新开仓
3. 执行 `agent_orchestration_rules.json`，产出候选决策
4. 执行 `risk_governor_rules.json`，得到 APPROVED/CLAMPED/REJECTED
5. 输出 `signal.schema.json` 结构给 MT5 执行端
6. 按 `token_latency_budget.json` 控制调用成本与超时降级
7. 异常时按 `incident_playbooks.json` 自动处置
8. 版本发布遵循 `release_gates.json`

## 最小接入要求

- 决策请求必须带 `signal_id`、`symbol`、`timeframe`、`confidence`
- 开仓请求必须带 `sl_price`
- 每次执行必须回写 `execution_report`
- 所有参数变更必须经过 `chat_command_rules.json` 权限与审批规则

## 一键部署

```bash
cd /path/to/gold_autotrade
./deploy/run_local.sh
```

## MT5 实时源模式

```bash
cd /path/to/gold_autotrade
python3 src/pipeline.py \
  --source mt5 \
  --runtime-intent live_trade \
  --symbol XAUUSD \
  --timeframe M5 \
  --execution-mode direct \
  --input-path data/inbox/request.json \
  --output-path data/outbox/signal.json \
  --execution-report-path data/inbox/execution_report.json \
  --poll-seconds 2 \
  --enable-incident-autofix true
```

## MT5 Bridge EA 模式

```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 \
  --execution-report-path data/inbox/execution_report.json \
  --once
```

运行意图强约束：
- `offline_train`：`source=file` + `execution-mode=file|mock`
- `paper_trade`：`source=mt5|ea_feed` + `execution-mode=mock`
- `live_trade`：`source=mt5|ea_feed` + `execution-mode=direct|ea_bridge`

## 控制面 API

```bash
cd /path/to/gold_autotrade
python3 src/control_api.py --host 127.0.0.1 --port 8787 --token change-me-token
```

调用调参接口需带 `X-Api-Key`，并可用 `X-Tenant` 隔离租户配置。
Webhook 调参可通过 `token` 参数或 `X-Webhook-Token` 头验证，密钥来自 `.env` 中 `FEISHU_WEBHOOK_TOKEN`/`QQ_WEBHOOK_TOKEN`。
Webhook 支持重放防护：`X-Timestamp` 时间窗校验 + `X-Nonce` 幂等去重。
控制面支持租户级限流与幂等，默认每租户每分钟 60 次，幂等窗口 600 秒。
控制面支持审计导出接口：`GET /audit/export?tenant_id=<id>&limit=<n>&offset=<n>&category=<intent>`。
控制面支持租户快照接口：`/config/snapshot/create`、`/config/snapshot/list`、`/config/snapshot/rollback`。

## 新增模块说明（v2）

### MT5 Direct Mode 生产增强（src/mt5_execution.py）
- **指数退避重试**：最多 3 次，间隔 0.5s → 1s → 2s
- **连接健康检测**：每次下单前探测 MT5 连接状态，失败自动重连（最多 2 次）
- **订单回执一致性**：signal_id ↔ order/deal ID 交叉验证，写入每日统计
- **故障标准化**：INIT_FAILED / ORDER_REJECTED / TIMEOUT / PARTIAL_FILL / RETRY_EXHAUSTED
- **日志分日**：logs/mt5_exec_stats.{YYYYMMDD}.ndjson

### 指标聚合（src/metrics_agg.py）
- **执行层**：FILLED/REJECTED/TIMEOUT/RETRY_EXHAUSTED 计数 + P50/P95 延迟
- **决策层**：15m/1h/1d 时间窗口内的批准率/拒绝率/错误率
- **运行状态**：当日回撤、连续亏损、熔断次数
- **回滚触发评估**：按 release_gates.json 自动判断是否触发门禁

### 灰度发布（src/rollout_manager.py）
- **状态机**：shadow → paper → canary_10pct → full
- **门禁评估**：每个决策前检查 promotion gates，决定是否允许通过
- **自动回滚**：任一 rollback_trigger 命中 → 自动回滚到上一个快照 + 写审计事件
- **无快照回滚**：激活 kill_switch 并写审计事件

### 控制面 API（GET /runtime/metrics）
- 返回：execution 统计、decision 窗口统计、runtime 状态、回滚触发器状态
- 支持 `?tenant_id=<id>` 查询指定租户

## 压测脚本（ops/mt5_direct_stress.py）
```bash
# 顺序压测
python3 ops/mt5_direct_stress.py --iterations 50 --mode direct --symbol XAUUSD

# 并发压测（4 workers）
python3 ops/mt5_direct_stress.py --iterations 100 --workers 4 --mode direct

# 预热 + 压测
python3 ops/mt5_direct_stress.py --iterations 100 --workers 4 --warmup 10

# Mock 模式（无需 MT5）
python3 ops/mt5_direct_stress.py --iterations 20 --mode mock --workers 4

# 报告输出到 logs/mt5_direct_stress.{timestamp}.json
```

报告字段：total / FILLED / REJECTED / TIMEOUT + P50/P95/P99 延迟 + 吞吐率。
