ai-ops/docs/INTEGRATION_CONTRACT.md

# AI-Ops 集成接口契约（Integration Contract）

> 版本：v1.0 | 状态：正式版
> 本文档是 AI-Ops 与立交桥主项目（gateway/supply-api/token-runtime）集成时的唯一信源源。
> 所有集成接口的路径、命名、字段、错误码均以本文档为准。

---

## 1. 集成原则

1. **唯一信源源**：本文档覆盖的所有接口，以 INTERFACE.md 为技术基准，以本文档为集成契约准。
2. **路径统一**：集成接口路径使用 `/internal/` 前缀，表明为内部服务间通信，不对外暴露。
3. **命名统一**：所有自愈动作类型使用 snake_case，统一为：`switch_route`、`throttle`、`restart_instance`、`invoke_script`、`isolate_node`。
4. **错误码统一**：所有错误码使用 `{SOURCE}_{CATEGORY}_{CODE}` 格式。
5. **审计覆盖**：任何修改类操作（POST/PUT/DELETE/PATCH）必须记录审计日志。

---

## 2. 与 Bridge Gateway 集成

### 2.1 接口清单

| 方法 | 路径 | 请求 | 响应 | 说明 | 审计 |
|------|------|------|------|------|------|
| 查询服务状态 | `GET /internal/gateway/health` | - | `{"status":"up","services":{}}` | 诊断时查询各服务健康状态 | 否 |
| 获取路由策略 | `GET /internal/gateway/routes` | - | `{"routes":[]}` | 读取当前路由配置，用于影响面分析 | 否 |
| 修改路由策略 | `POST /internal/gateway/routes` | `{"action":"switch_route","target":"","config":{}}` | `{"success":true}` | 自愈动作调用 | 是 |
| 获取请求量统计 | `GET /internal/gateway/metrics` | `?metric=qps&duration=5m` | `{"value":1234.5}` | 采集指标数据 | 否 |

### 2.2 安全约束

- `/internal/gateway/metrics` 仅限内网 IP 访问（10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16）或需携带有效的服务间 API Key。
- 公网直接访问返回 403 Forbidden。
- 修改路由策略必须经过 AI-Ops 审计流程，由 HLD §3.3 审计设计章节规范。

### 2.3 字段规范

**`POST /internal/gateway/routes` 请求体**:
```json
{
  "action": "switch_route",      // 必填，枚举: switch_route/throttle/restart_instance/invoke_script/isolate_node
  "target": "service_a",         // 必填，目标资源 ID
  "config": {                    // 可选，动作特定参数
    "fallback_provider": "p_b",  // switch_route 时指定备用供应商
    "rate_limit_rps": 1000       // throttle 时指定限流值
  },
  "dry_run": false               // 可选，默认 false，true 时仅验证不执行
}
```

**`修改路由策略` 错误码**:
| 错误码 | HTTP 状态 | 说明 |
|---------|-----------|------|
| `OPS_GWY_4001` | 400 | 请求参数验证失败 |
| `OPS_GWY_4002` | 404 | 目标资源不存在 |
| `OPS_GWY_4003` | 409 | 目标资源正在被其他操作修改 |
| `OPS_GWY_5001` | 500 | gateway 内部错误 |

---

## 3. 与 supply-api 集成

### 3.1 接口清单

| 方法 | 路径 | 请求 | 响应 | 说明 | 审计 |
|------|------|------|------|------|------|
| 查询供应商状态 | `GET /internal/supply/accounts/health` | - | `{"accounts":[]}` | 诊断供应商健康状态 | 否 |
| 获取审计日志格式 | `GET /internal/supply/audit/schema` | - | `{"schema":{}}` | 确保审计事件格式一致 | 否 |

### 3.2 安全约束

- 供应商健康接口仅限内网访问。
- 审计日志格式接口用于初始化时校验 schema 一致性，不对外暴露。

---

## 4. 与 platform-token-runtime 集成

### 4.1 接口清单

| 方法 | 路径 | 请求 | 响应 | 说明 | 审计 |
|------|------|------|------|------|------|
| 获取 Token 消耗 | `GET /internal/runtime/token-usage` | `?window=1h` | `{"total":12345,"by_model":{}}` | 采集 Token 消耗指标 | 否 |
| 获取容量使用率 | `GET /internal/runtime/capacity` | - | `{"utilization":0.75}` | 采集容量指标 | 否 |

### 4.2 安全约束

- Token 消耗接口可能包含敏感信息，仅限内网访问。
- 返回的 Token 数量应为汇总值，不得暴露用户级别的明细。

---

## 5. 错误码映射总表

| 错误码 | HTTP 状态 | 来源 | 说明 |
|---------|-----------|-------|------|
| `OPS_GEN_4001` | 400 | 通用 | 请求参数错误 |
| `OPS_GEN_4002` | 401 | 通用 | 未授权 |
| `OPS_GEN_4003` | 403 | 通用 | 权限不足 |
| `OPS_GEN_4004` | 404 | 通用 | 资源不存在 |
| `OPS_GEN_4005` | 409 | 通用 | 资源冲突 |
| `OPS_GEN_4006` | 413 | 通用 | 请求体过大 |
| `OPS_GEN_5001` | 500 | 通用 | 内部服务错误 |
| `OPS_MET_4001` | 400 | metric | 指标名称无效 |
| `OPS_MET_4002` | 400 | metric | 时间范围不合法 |
| `OPS_ALT_4001` | 400 | alert | 规则名称已存在 |
| `OPS_ALT_4002` | 400 | alert | 规则参数验证失败 |
| `OPS_ALT_4003` | 409 | alert | 版本冲突 |
| `OPS_HEAL_4001` | 400 | healing | 自愈动作参数无效 |
| `OPS_HEAL_4002` | 409 | healing | 自愈动作正在执行中 |
| `OPS_HEAL_4003` | 400 | healing | 回滚目标执行不存在 |
| `OPS_AUD_4001` | 403 | audit | 无权进行审计操作 |
| `OPS_AUD_4101` | 400 | audit | 回滚目标资源不存在 |
| `OPS_AUD_4102` | 409 | audit | 回滚目标已被后续修改覆盖 |
| `OPS_CAP_4001` | 400 | capacity | 容量指标不存在 |
| `OPS_GWY_4001` | 400 | gateway | 请求参数验证失败 |
| `OPS_GWY_4002` | 404 | gateway | 目标资源不存在 |
| `OPS_GWY_4003` | 409 | gateway | 目标资源正在被其他操作修改 |
| `OPS_GWY_5001` | 500 | gateway | gateway 内部错误 |

---

## 6. 变更日志

| 版本 | 日期 | 修改人 | 内容 |
|------|------|---------|------|
| v1.0 | 2026-05-11 | TechLead | 初稿：统一集成接口路径、自愈动作命名、错误码、安全约束 |