新增 affiliate_dash 回调路由与幂等去重(阶段 5)

- POST /api/v1/open/affiliate-dash:验签 → 查任务(404 重试) → webhook_events 幂等闸门 → 状态同步
- migration 013:webhook_events(provider+event_id 唯一)
- task-repo findAffiliateDashTaskByOrder(仿 feifei 同构 SQL)
- notify-service:去重闸门在找到任务之后,任务未匹配不被 eventId 永久拦截
- typecheck + 212 测试通过;前置错误分支脚本验证通过

docs/ affiliate_dash_发货平台/affiliate-dash对接.md

@@ -540,3 +540,22 @@ order_site 处理要求：
 **效果**：核销由「发货完成后（分钟~小时级）」提前到「建单成功（秒级）」；91 卡信息一经消耗即核销，delivered 回调只做状态收敛。已核销成功的凭证在 delivered 时 `resolveTaskVouchers` 返回空，自然走 redeemed。
 
 **验证**：typecheck 通过；后端全量 212 测试通过。
+
+---
+
+## 20. 阶段 5 落地记录（v2.5 · 已完成）
+
+**回调路由打通**：挂载 `POST /api/v1/open/affiliate-dash`（与线上回调 URL `https://ks.khhao.com/api/v1/open/affiliate-dash` 一致）。
+
+| 文件 | 内容 |
+| --- | --- |
+| `db/migrations/013_affiliate_dash_webhook_events.sql` | `webhook_events` 表 + `(provider, event_id)` 唯一索引（回调幂等去重） |
+| `repositories/webhook-event-repo.ts` | `insertWebhookEventOnce`：`ON CONFLICT (provider, event_id) DO NOTHING`，冲突返回 `inserted=false` |
+| `repositories/task-repo.ts` | `findAffiliateDashTaskByOrder`：按 `context_json #>> '{affiliateDash,orderNo}'` / `clientOrderNo` 查任务（仿 `findKuaishouFeifeiTaskByOrder` 同构 SQL） |
+| `services/platforms/affiliate-dash/notify-service.ts` | `handleAffiliateDashNotify`：验签（X-Timestamp 容差→重算签名）→ 查任务（未匹配 404 触发重试）→ 幂等闸门（重复 eventId 直接 200 跳过）→ `createTaskEvent('affiliate_dash_notify_received')` → `syncAffiliateDashTaskStatus`（状态合并式可重入） |
+| `routes/affiliate-dash.ts` | `POST /`，rate limit 300/min，`req.rawBody` 验签（express.json verify 已存），全链路日志 |
+| `app.ts` | 挂载 `/api/v1/open/affiliate-dash` |
+
+**处理顺序设计**：去重闸门放在「找到任务」之后 —— 任务未建/已删时返回 404 让对方重试，而不是被 eventId 去重永久拦截；找到任务后冲突才视为重复投递直接 200。
+
+**验证**：typecheck 通过；后端全量 212 测试通过；脚本验证前置错误分支——缺签名头 401 / 时间戳超容差 401 / 验签失败 401 / 缺订单号 400 全部正确；「任务不存在→404」及幂等/同步路径依赖真实 DB，留待阶段 6 端到端演练（本沙箱无 postgres）。