外部集成与开放 API
ERP / WMS / TMS / OMS / 门店端 / 数仓 六类集成的方向、协议、频率、字段映射、负责人与健康状态；开放 API 的鉴权与配额；幂等键约定（业务单号 + 数据版本 + 时间戳，重复下发 409 拦截）与失败补偿队列。
!集成页的价值是回答三个问题：连了谁（系统 / 方向 / 协议 / 频率 / 字段映射 / 负责人）、怎么不写脏（幂等键 = 业务单号 + 数据版本 + 时间戳，重复下发 409 拦截）、失败怎么办（可重试与不可重试分开，死信可重放）。这三件事合起来才是 S4 + X13 的完整口径。
已接入系统
6个
ERP / WMS / TMS / OMS / 门店端 / 数仓
集成接口
28个
其中开放 API 12 个（对外 5 个）
今日调用
12,486次
库存 ATP 查询占 78.8%
调用成功率
99.62%
失败 47 次，其中 409 重复拦截 12 次
端到端时延 P95
218ms
决策导出接口 1.8s（异步分卷）
补偿队列积压
14条
超时重试 6 / 主数据 5 / 限流 3
集成配置清单
方向 / 协议 / 频率 / 字段映射 / 幂等键 / 负责人 / 健康状态| 外部系统 | 方向 | 协议 / 接口 | 同步频率 | 数据范围 | 字段映射 | 幂等键 | 负责人 | 健康状态 | 最近同步 |
|---|---|---|---|---|---|---|---|---|---|
| — | — | — | — | — | — | — | — | — | — |
| — | — | — | — | — | — | — | — | — | — |
| — | — | — | — | — | — | — | — | — | — |
| — | — | — | — | — | — | — | — | — | — |
| — | — | — | — | — | — | — | — | — | — |
| — | — | — | — | — | — | — | — | — | — |
共 6 个外部系统 / 28 个接口；健康状态取自近 24 小时成功率与同步时点偏差每页
i健康状态不是“接口通不通”，而是数据到没到、口径对不对：TMS 告警是因为签收回执延迟 2 单，门店端告警是因为 51 家门店 POS 延迟 > 6 小时（会直接影响本次决策的销量口径）。字段映射版本（MAP-*-vN）与字段字典（io-template 的 168 列）同源，改映射必须走版本发布。
一次下发 — 回执全过程（RP20251021-003 · 幂等键贯穿）
traceId + 幂等键可一路串到下游单号STEP 1
审批通过
09:05
STEP 2
生成幂等键
09:05
STEP 3
下发 ERP
09:06
STEP 4
ERP 建单回执
09:06
STEP 5
下发 WMS
09:06
STEP 6
出库回执
15:20
STEP 7
签收回执
18:40
09:05:12 · 审批通过
二级审批通过，生成幂等键 RP20251021-003__v2__202510210812（业务单号 + 数据版本 + 提单时间戳）
09:06:02 · 下发 ERP
POST /openapi/v1/replenishment/orders → 200 OK，ERP 单号 SO-20251021-0342；行级幂等键含 lineNo
09:06:03 · 重复下发拦截
调度器补跑再次触发同幂等键 → 服务端返回 409 DUPLICATE 并回放首次结果，未新建订单
09:06:08 · 下发 WMS
POST /wms/task，taskNo = TR20251021-003__v2__202510210812，回执 accepted，拣货波次 1 个
15:20:41 · 出库回执
WMS 回执 shipped，包裹 2 个 / 7 件，回写台账流水（按 storeId + skc + size + snapDate upsert）
18:42:34 · 签收回执（重试第 3 次成功）
TMS 回调超时后 2 次重试，612ms 成功；幂等键未变，OMS 侧未产生重复运单绑定
待办 · 门店收货确认
等待武林银泰店在门店 App 确认收货；超 48 小时触发 TPL-RECV-PENDING 通知与升级
鉴权方式与调用配额
- 鉴权 1 · 服务端
- OAuth2 客户端凭证（client_id / secret 存放于配置中心，90 天轮换）
- 鉴权 2 · 报文
- HMAC-SHA256 签名（appId + timestamp + nonce + body 摘要）
- 鉴权 3 · 网络
- 管理后台与开放 API 强制 IP 白名单；门店端移动访问不受限
- 配额单位
- 按调用方（client_id）而非按 IP，防止同 IP 多应用互相挤占
- 超配额响应
- 429 + Retry-After 头；连续超限 10 分钟自动降速并通知对接人
- 审计
- 每次调用记录 client_id、traceId、幂等键、耗时、结果码（G9 / X17）
密钥不落在代码里
客户端凭证与签名密钥统一由配置中心下发、支持双密钥并行轮换（灰度期新旧密钥都能验签），禁止写在对接文档、脚本或数据库明文中。
幂等键约定（X13 写入边界）
at-least-once 语义下，接收侧按业务键 upsert 是唯一正确姿势| 写入对象 | 业务键 | 幂等键规则 | 唯一索引 | 重复下发行为 | 幂等键生成方 |
|---|---|---|---|---|---|
| — | — | — | — | — | — |
| — | — | — | — | — | — |
| — | — | — | — | — | — |
| — | — | — | — | — | — |
| — | — | — | — | — | — |
| — | — | — | — | — | — |
共 6 类写入对象；幂等键必须落唯一索引，不能只靠应用层判重（重跑即重复开单）每页
- 键的构成
- 业务单号 + 数据版本（ver）+ 提单时间戳（ts），三段用“__”连接
- 真实样例
- RP20251021-003__v2__202510210812（单据级）· SH008 + 24AW-3890 + M + 2025-10-21（库存回写级）
- 为什么带版本
- 同一决策日可能多次改量导入（v1 → v2），不带版本号会把人工改量后的重发误判为重复
- 为什么由上游生成
- 下游按“门店 + SKC + 日期”自行判重会丢单据；键必须由本系统生成并随报文下发
- 接收侧义务
- 按下发的幂等键 upsert；已存在则返回 409 + 首次结果，不得静默新建
- 拦截留痕
- 每次 409 都写日志（含 traceId），可在 data-idempotent 页反查拦截原因
- 回放能力
- 失败补偿队列重放时必须携带原幂等键，保证重试无损
API 管理与调用配额
配额、鉴权、SLA 三件套逐接口可见| 开放接口 | 方法 | 鉴权方式 | 配额（按调用方） | 今日调用 | 平均时延 | SLA |
|---|---|---|---|---|---|---|
| — | — | — | — | — | — | — |
| — | — | — | — | — | — | — |
| — | — | — | — | — | — | — |
| — | — | — | — | — | — | — |
| — | — | — | — | — | — | — |
开放 API 共 12 个，对外可用 5 个；其余为内部服务间调用，不对外暴露每页
集成失败处理与补偿队列
可重试与不可重试必须分开，否则重试一万次也不会成功| 失败类型 | 可重试 | 处理策略 | 补偿方式 | 当前积压 |
|---|---|---|---|---|
| — | — | — | — | — |
| — | — | — | — | — |
| — | — | — | — | — |
| — | — | — | — | — |
| — | — | — | — | — |
积压合计 14 条；同一失败类型连续 3 次即升级为集成告警每页
近 7 天调用量（按系统）
总计 35,142 次 / 7 天，成功率 99.62%集成自检（每日 03:00 自动巡检）
| 自检项 | 结果 | 说明 |
|---|---|---|
| 接口清单与调用日志是否对齐 | 通过 | 28 个接口全部有近 24 小时调用记录 |
| 是否存在无幂等键的写接口 | 0 个 | 6 类写入对象全部声明幂等键与唯一索引 |
| 字段映射版本是否已发布 | 1 项待发布 | MAP-WMS-v6 草稿待发布（新增包裹体积字段） |
| 凭证是否临近轮换期 | 1 项 | TMS 客户端密钥剩余 12 天到期 |
| 补偿队列是否有超 24h 积压 | 3 条 | 主数据不匹配 5 条中 3 条超 24 小时，已派工单 |
i落地提醒（附录 D 第 11 条）：平台内部可以做到 exactly-once，一旦写外部系统（ERP 单据 / Kafka / WMS 接口）就退回 at-least-once，必须在接收侧按业务键 upsert，否则重跑就是重复开单。本页把幂等键做成系统的显式配置项，而不是散落在各接口文档里的一句话。