craftlabs-authorization-sdk/docs/engineering/iterations/I9_WEBHOOK_DELIVERY_VISIBILITY_DESIGN.md

I9 设计 — Callback 详情可观测 Webhook 平台投递状态

角色：架构审查与实现规划；承接 I8（重放入队）之后的 只读观测 缺口。
日期：2026-04-07。

---

1. 走查结论（相对 I6/I7/I8）

主题	状态	说明
I7 异步出库	已落地	PENDING / SENT / DEAD 在 Webhook 库表。
I8 重放	已落地	平台 POST 代理 + Webhook replay；详情页仍看不到实时出库状态。
I7 复盘 §2 DEAD	文档过时	已具备 UI 重放（I8）；本迭代补 状态只读 并修订 I7 复盘表述。
OpenAPI / JDK	门禁	变更契约后须 JDK 17 + OpenApiContractSnapshotTest；见 contracts/README。

---

2. 目标与非目标

| 目标 | Ops 在 Callback 详情 查看与该收件箱 webhookReceiptId 对应的 webhook_platform_delivery 行摘要（status、attempts、lastError、nextRetryAt、updatedAt），无需直连 Webhook 库。 | | 非目标 | 浏览器调用 Webhook；改动比特契约；全量 M5-F08 仪表盘；Playwright 进 CI（列为 I9 后可选）。 |

---

3. API 与信任边界

与 I8 相同：仅 delivery-platform-api 凭 LICENSE_WEBHOOK_BASE_URL + LICENSE_WEBHOOK_OPS_TOKEN 访问 Webhook /internal/**；前端只打平台 JWT。

组件	方法	路径	说明
Webhook	GET	/internal/v1/platform-deliveries/by-receipt/{receiptId}	同 WebhookOpsTokenFilter；无行则 404。
Platform	GET	/api/v1/callback-inbox/{id}/webhook-delivery	@PreAuthorize 与 Inbox 一致（OPS/SYS_ADMIN）；无 webhookReceiptId 则 400；未配 Webhook 则 503。

响应体（双方 JSON 字段一致，便于直连 RestClient 反序列化）：

• receiptId (long)
• status (string)
• attempts (int)
• lastError (string, 可 null)
• nextRetryAt (date-time, 可 null)
• updatedAt (date-time)

---

4. 实现要点

1. Webhook：PlatformDeliveryService#getStatusByReceiptId 查表组装 Map/DTO；Controller 增加 GET。
2. 平台：WebhookDeliveryReplayClient#fetchDeliveryStatus（保留 Bean 名以减重构面）；CallbackInboxService#getWebhookDeliveryStatus → CallbackInboxController。
3. 前端：详情页在存在 webhookReceiptId 时请求上述 GET，展示 el-descriptions；失败时 不阻断 主详情（提示或短文案）。
4. 契约：UPDATE_OPENAPI=1 导出快照并提交。
5. 文档：更新 PARALLEL_ITERATION_INDEX I9 行；修正 I7_IMPLEMENTATION_REVIEW §2 DEAD 表述。

---

5. 验证

• mvn -f services/pom.xml verify（Java 17）
• npm run build（web/delivery-platform-ui）
• Webhook / 平台单测各 ≥1 条覆盖 GET 与平台代理

---

6. 修订记录

日期	说明
2026-04-07	初版：I9 出库可见性架构与 API。