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 请求体:

{
  "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	初稿：统一集成接口路径、自愈动作命名、错误码、安全约束