补充方案

server/消息推送文档/DELIVERY_WEBHOOK_PUSH_SERVER_OVERVIEW.md

@@ -126,13 +126,14 @@ flowchart LR
 - `PATCH platform_express_waybills`：更新 `current_status_code/current_status_text/last_synced_at`
 - `INSERT platform_express_tracking_events`：写入归一化事件事实数据（包含 raw_payload、dedupe_key 等）
 
-> 注意：当前实现的 `dedupe_key` 使用 `WEBHOOK_ + Date.now()`，更偏向“留痕与追溯”；如需严格幂等（重复回调不重复入库），建议按文档口径构造稳定 dedupe_key（例如 `tracking_no|event_code|event_time`）。
+> 当前实现的 `dedupe_key` 使用稳定哈希（基于 tracking_no / carrier / status_code / event_time / event_code / event_text 的截断组合），用于保证 webhook 重复回调不会重复写入事件表，从而避免重复入队/重复通知。
 
 ### 3.4 验签（可选）
 - 配置 `WEBHOOK_SECRET` 后会校验：
   - `X-Timestamp`、`X-Signature`
-  - 签名算法：`HMAC-SHA256(secret, bodyText + timestamp)`，输出 hex
-- 目前验签失败不会直接拒绝入库（会在 raw 表记录 `signature_valid=false`），可按需要升级为“验签失败直接 4xx”。
+  - 签名算法：`HMAC-SHA256(secret, rawBodyText + timestamp)`，输出 hex（务必使用**原始请求体文本**参与计算）
+- 默认行为：验签失败不会直接拒绝入库（会在 raw 表记录 `signature_valid=false`）。
+- 可选严格模式：设置 `WEBHOOK_REJECT_INVALID_SIGNATURE=true` 后，验签失败将直接返回 HTTP 401。
 
 ### 3.5 配置与启动方式
 接收器会先通过 `server/load-config.js` 把配置注入 `process.env`，优先级是：