KEEL · 龙骨 · A CURRICULUM FOR THE AI ERA
03. 客户系统怎样接进来而不失控？ — keel 龙骨
事件助手需要 ticket、metrics、change 和 runbook。真实客户环境里，这些数据来自不同身份系统、网络区域和 schema 版本；接口超时与重复 webhook 比 prompt 更早决定项目能否上线。
事件助手需要 ticket、metrics、change 和 runbook。真实客户环境里，这些数据来自不同身份系统、网络区域和 schema 版本；接口超时与重复 webhook 比 prompt 更早决定项目能否上线。
Integration Contract 的六个部分
| 部分 | 需要固定的内容 |
|---|---|
| Identity | service principal、用户委派、tenant 和 scope |
| Transport | REST/webhook/queue、TLS、签名和超时 |
| Schema | 版本、必填字段、枚举、时间和单位 |
| Semantics | event ID、业务幂等键、顺序和删除含义 |
| Data policy | PII/secret 分类、留存、日志和地域 |
| Failure | retryable、dead-letter、unknown、reconcile 和 owner |
模型不能“智能修复”身份、租户或版本错误。先用 JSON Schema/Pydantic 等验证，再把已授权、已归一的数据交给 Harness。
Webhook 的最小安全边界
配套项目验证：HMAC 签名、时间容差、tenant、schema version 和 event ID replay。运行：
python courses/advanced/fde-customer-delivery/course/project/examples/02_signed_webhook.py
相同 event ID 与相同 payload 重放时返回已有 receipt；相同 ID 换 payload 必须报冲突。签名正确也不等于业务授权，tenant 和 scope 仍要校验。
从模拟接口走向真实 adapter
不要直接删掉模拟层。先把已有的 simulator 固定成一组稳定 port（对外接口），再按同一组 port 增加真实 adapter 和 contract tests，最后在一套与生产隔离的 staging 环境里做联调。这样开发仍可确定性运行，真实凭据和网络问题只存在于 adapter 边界。
判断自己做到了没有，看两件事：一是停掉真实依赖时，整套流程还能用 simulator 跑通；二是把 simulator 换成真实 adapter 时，上层代码一行都不用改。
本章交付物
- Integration inventory 和数据流图；
- 一份版本化 Data Contract；
- 签名、重放、跨租户、超时和 schema 演进测试；
- 凭据 owner、轮换和故障升级说明。
自测
- HTTP 200 是否等于业务接收成功？
- webhook 重试后怎样证明没有重复业务效果？
- schema 新增、删除和含义变化分别怎样兼容？