# Quickstart

## 1. 校验规则文件

```bash
cd /path/to/gold_autotrade
python3 ops/check_configs.py
```

## 2. 决策执行最小流程

1. 接收 MT5 数据并构造 `GoldSignalContext`
2. 生成 `AiTradePlan` 并按 `contracts/ai_trade_plan.schema.json` 校验
3. 执行 `config/data_quality_rules.json`
4. 执行 `config/agent_orchestration_rules.json`
5. 执行 `config/risk_governor_rules.json`
6. 输出符合 `contracts/signal.schema.json` 的执行信号
7. 把执行结果写入决策账本与运行日志

```bash
python3 src/run_executor.py \
  --input ops/sample_request.json \
  --output ops/sample_signal.json
```

## 3. 对话调参发布流程

1. 飞书/QQ 接收调参请求
2. `ops/chat_command_rules.json` 鉴权与审批
3. 配置中心生成新版本
4. 按 `ops/release_gates.json` 先灰度后全量
5. 触发回滚条件时自动回滚

## 4. 部署运行

```bash
cd /path/to/gold_autotrade
python3 src/pipeline.py \
  --source file \
  --runtime-intent offline_train \
  --symbol XAUUSD \
  --timeframe M5 \
  --execution-mode file \
  --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 \
  --once
```

或使用一键脚本：

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

## 5. 对话调参执行

```bash
cd /path/to/gold_autotrade
python3 src/chat_tuning.py \
  --role admin \
  --channel feishu \
  --text "把单笔风险改为0.6%" \
  --approved true
```

## 6. 端到端烟雾测试

```bash
cd /path/to/gold_autotrade
./ops/e2e_smoke.sh
```

## 7. 控制面 API

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

健康检查与调参示例：

```bash
curl -s http://127.0.0.1:8787/health
curl -s -X POST http://127.0.0.1:8787/tune \
  -H 'X-Api-Key: change-me-token' \
  -H 'X-Tenant: tenant_a' \
  -H 'X-Idempotency-Key: req-001' \
  -H 'Content-Type: application/json' \
  -d '{"role":"admin","channel":"feishu","text":"把最小置信度改为0.7","approved":true}'
```

Webhook 调参示例（需配置 FEISHU_WEBHOOK_TOKEN 或 QQ_WEBHOOK_TOKEN）：

```bash
curl -s -X POST "http://127.0.0.1:8787/webhook/qq?token=change-qq-webhook-token" \
  -H 'Content-Type: application/json' \
  -d '{"tenant_id":"tenant_a","text":"把最小置信度改为0.7"}'
```

Webhook 重放防护示例（可选）：

```bash
curl -s -X POST "http://127.0.0.1:8787/webhook/qq?token=change-qq-webhook-token" \
  -H 'Content-Type: application/json' \
  -H 'X-Timestamp: 1730000000' \
  -H 'X-Nonce: req-1001' \
  -d '{"tenant_id":"tenant_a","text":"把最小置信度改为0.7"}'
```

查看租户运行态：

```bash
curl -s 'http://127.0.0.1:8787/runtime/tenants' -H 'X-Api-Key: change-me-token'
curl -s 'http://127.0.0.1:8787/runtime' -H 'X-Api-Key: change-me-token' -H 'X-Tenant: tenant_a'
curl -s 'http://127.0.0.1:8787/runtime/metrics?tenant_id=tenant_a' -H 'X-Api-Key: change-me-token'
curl -s 'http://127.0.0.1:8787/audit/export?tenant_id=tenant_a&limit=50&offset=0&category=SET_MIN_CONFIDENCE' -H 'X-Api-Key: change-me-token'
```

快照与回滚：

```bash
curl -s -X POST http://127.0.0.1:8787/config/snapshot/create \
  -H 'X-Api-Key: change-me-token' -H 'Content-Type: application/json' \
  -d '{"tenant_id":"tenant_a","reason":"before_tuning"}'
curl -s -X POST http://127.0.0.1:8787/config/snapshot/list \
  -H 'X-Api-Key: change-me-token' -H 'Content-Type: application/json' \
  -d '{"tenant_id":"tenant_a"}'
curl -s -X POST http://127.0.0.1:8787/config/snapshot/rollback \
  -H 'X-Api-Key: change-me-token' -H 'Content-Type: application/json' \
  -d '{"tenant_id":"tenant_a","tag":"<snapshot_tag>"}'
```

## 8. 安装升级回滚

```bash
cd /path/to/gold_autotrade
./deploy/install_app.sh "$HOME/gold_autotrade_app"
./deploy/upgrade_app.sh "$HOME/gold_autotrade_app"
python3 deploy/release_manager.py --action list --target-root "$HOME/gold_autotrade_app"
./deploy/rollback_app.sh "$HOME/gold_autotrade_app" <release_tag>
```

## 9. MT5 direct 压测

```bash
cd /path/to/gold_autotrade
python3 ops/mt5_direct_stress.py --symbol XAUUSD --iterations 30 --sleep-ms 200
```

## 10. 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
```

Bridge EA 接入细节见：`ops/ea_bridge_guide.md`

运行意图约束：

```text
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)
```

## 10. MT5 Direct 生产增强功能

### 重试与故障分类
MT5 Direct Mode 自动重试失败订单（最多 3 次，指数退避），故障类型：
- `INIT_FAILED`：MT5 连接初始化失败
- `ORDER_REJECTED`：订单被拒绝（非临时性）
- `TIMEOUT`：订单发送超时
- `PARTIAL_FILL`：部分成交
- `RETRY_EXHAUSTED`：所有重试次数耗尽

### 查看每日执行统计
```bash
# 查看今天的执行统计
cat logs/mt5_exec_stats.$(date +%Y%m%d).ndjson

# 统计计数
grep '"status":"FILLED"' logs/mt5_exec_stats.$(date +%Y%m%d).ndjson | wc -l
```

### 灰度发布与自动回滚
每次决策前自动评估 release_gates.json 中的回滚触发器：
- 命中 `drawdown_spike`（日内回撤 > 2%）→ 自动回滚
- 命中 `error_rate_spike`（15分钟错误率 > 3%）→ 自动回滚
- 命中 `ack_timeout_spike`（15分钟ACK超时率 > 4%）→ 自动回滚

查看当前灰度模式：
```bash
# 查看租户运行时状态（包含 promotion_mode）
curl -s 'http://127.0.0.1:8787/runtime' -H 'X-Api-Key: change-me-token' -H 'X-Tenant: tenant_a'
```

查看回滚触发器状态（GET /runtime/metrics 响应中的 `rollback_triggers` 字段）：
```bash
curl -s 'http://127.0.0.1:8787/runtime/metrics?tenant_id=default' -H 'X-Api-Key: change-me-token'
```

## 11. 验收检查清单

```bash
cd /path/to/gold_autotrade

# 1. 配置文件校验
python3 ops/check_configs.py
# 预期：{"ok": true, "checked_json_files": 11}

# 2. 端到端烟雾测试
bash ops/e2e_smoke.sh
# 预期：e2e smoke passed

# 3. 控制面接口
curl -s http://127.0.0.1:8787/health
# 预期：{"ok": true, "service": "gold-control-api"}

# 4. 指标查询
curl -s 'http://127.0.0.1:8787/runtime/metrics?tenant_id=default' \
  -H 'X-Api-Key: change-me-token'
# 预期：返回 execution / decision / runtime / rollback_triggers 统计

# 5. 压测脚本
python3 ops/mt5_direct_stress.py --iterations 20 --mode mock --workers 4
# 预期：生成 logs/mt5_direct_stress.{timestamp}.json，含 P50/P95 延迟
```
