external-integration-architecture

name	external-integration-architecture
description	外部集成架构专家 Owner — 当任务涉及第三方 API、Webhook、OAuth、回调、provider/connector、配额、重试、降级、供应商锁定、外部故障或集成文档时使用；要求隔离外部边界并设计失败恢复。

External Integration Architecture Skill

定位

本 Skill 负责外部集成 Owner 视角。它要求把第三方能力当作不稳定边界处理：认证、回调、配额、重试、降级、审计和退出策略都要可验证。

触发条件

场景	是否触发
第三方 API、OAuth、Webhook、callback、provider、connector、adapter、外部 SDK	必须
任务涉及重试、超时、配额、限流、外部失败、降级、供应商锁定或回放	必须
文档或示例描述外部接入流程	必须
纯仓库内部逻辑且无外部系统边界	N/A + skipReason

核心门禁

Gate	要求	证据
ExternalIntegrationArchitectureGate	外部边界、认证回调、配额重试、降级和锁定风险必须成矩阵	providerBoundary、quotaRetryPolicy
ProviderBoundaryGate	外部 payload 不得污染公共业务契约	adapter、mapper、contract
AuthCallbackGate	OAuth、签名、回调、重放和状态校验必须设计	authCallbackModel
QuotaRetryDegradationGate	配额、重试、幂等、超时、降级和失败恢复必须明确	failureDegradation
VendorLockInGate	供应商锁定和替换成本必须说明	lockInExitPlan

执行步骤

1. 区分业务契约、内部 provider adapter、外部 payload。
2. 识别认证、签名、callback、webhook、重放、幂等和审计边界。
3. 设计配额、限流、重试、退避、超时、降级和最终一致性。
4. 记录供应商锁定、替换成本、兼容层和迁移路径。
5. 为成功、失败、部分成功、重复回调和外部不可用建立验证。

输出字段

## ExternalIntegrationArchitectureGate

| 字段 | 内容 |
|------|------|
| providerBoundary | 业务契约 / adapter / 外部 payload 边界 |
| authCallbackModel | OAuth、签名、callback、webhook、重放防护 |
| quotaRetryPolicy | 配额、限流、超时、重试、退避 |
| webhookIdempotency | webhook 去重、幂等、顺序和重放 |
| failureDegradation | 外部失败、部分成功、降级、恢复 |
| lockInExitPlan | 供应商锁定、替换成本、迁移策略 |
| evidenceMatrix | 判断 -> 官方文档 / 代码 / 测试 / 日志 / 运行时证据 |

反模式

反模式	修正
直接把 provider 字段暴露给业务 API	使用 mapper 和标准 result
只处理 200 响应	补配额、超时、重试、部分成功和失败恢复
Webhook 不做幂等和重放处理	定义 event id、signature、dedupe、replay 策略
集成文档只写申请 key	补 callback、权限、限制、错误和恢复

与其他 Skill 的关系

• api-contract-architecture：外部 adapter 不能反向污染公共 API。
• security-threat-modeling：认证、签名、webhook 和密钥边界需要威胁建模。
• production-readiness-sre：外部故障、配额和降级进入运行风险矩阵。