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

> **角色**：架构审查与实现规划；承接 [I8](I8_WEBHOOK_DELIVERY_REPLAY_DESIGN.md)（重放入队）之后的 **只读观测** 缺口。  
> **日期**：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](../../../contracts/README.md)。 |

---

## 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](../PARALLEL_ITERATION_INDEX.md) I9 行；修正 [I7_IMPLEMENTATION_REVIEW](./I7_IMPLEMENTATION_REVIEW.md) §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。 |