消息推送和第三方接收后台搭建，未测试

pages/mall/delivery/webhook-server/README.md

@@ -0,0 +1,73 @@
+# Webhook 接收器 — 说明
+
+路径：`pages/mall/delivery/server/webhook-receiver.js`
+
+目的：接收承运方或 Mock Server 的 HTTP 回调（POST /webhook/express/status），将原始回文写入 `platform_express_event_raw`，并按项目现有映射更新 `platform_express_waybills` 与写入 `platform_express_tracking_events`。
+
+环境变量（必须/可选）：
+- `SUPA_URL`：Supabase REST 地址（示例 `http://192.168.1.62:18000`）
+- `SUPA_KEY`：Supabase service_role 或 anon key（用于 REST 写入）
+- `WEBHOOK_SECRET`（可选）：与第三方共享的 HMAC-SHA256 secret，用于校验 `X-Signature`（签名为 hex）
+- `PORT`（可选）：接收器监听端口，默认 `7201`
+
+启动（PowerShell）：
+```powershell
+$env:SUPA_URL='http://192.168.1.62:18000'
+$env:SUPA_KEY='your_service_role_key'
+# 可选验签
+$env:WEBHOOK_SECRET='your-secret'
+node pages/mall/delivery/server/webhook-receiver.js
+```
+
+启动（Linux / macOS / WSL）：
+```bash
+export SUPA_URL='http://192.168.1.62:18000'
+export SUPA_KEY='your_service_role_key'
+export WEBHOOK_SECRET='your-secret' # optional
+node pages/mall/delivery/server/webhook-receiver.js
+```
+
+测试（curl 模拟第三方推送）：
+```bash
+BODY='{"mailNo":"TEST_123","infoContent":"SENT","remark":"派送中","acceptTime":"2026-02-25 12:00:00","carrier":"YTO"}'
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+# 如果启用了 WEBHOOK_SECRET，计算签名：
+SIG=$(printf "%s%s" "$BODY" "$TS" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -hex | awk '{print $2}')
+
+curl -i -X POST http://localhost:7201/webhook/express/status \
+  -H "Content-Type: application/json" \
+  -H "X-Timestamp: $TS" \
+  -H "X-Client-Id: mock_carrier" \
+  -H "X-Signature: $SIG" \
+  -d "$BODY"
+```
+
+预期：接口返回 200 JSON {ok:true}（若未找到对应运单会返回 {ok:false, message:'waybill not found'}）。
+
+验证写入（查看 Supabase）：
+```bash
+# 示例：列最近 5 条原始回文
+curl -s -H "apikey: $SUPA_KEY" -H "Authorization: Bearer $SUPA_KEY" \
+  "$SUPA_URL/rest/v1/platform_express_event_raw?select=*&order=received_at.desc&limit=5" | jq .
+
+# 查看最近轨迹事件
+curl -s -H "apikey: $SUPA_KEY" -H "Authorization: Bearer $SUPA_KEY" \
+  "$SUPA_URL/rest/v1/platform_express_tracking_events?select=*&order=created_at.desc&limit=5" | jq .
+```
+
+与仓库中 Mock 实现的关系：
+- `pages/mall/delivery/test/mock-service.uts` 已包含写库逻辑（`pushWebhookData`、`bindShipment`、`runScenario`）。新接收器复用了同样的入库思路，但以 HTTP/REST 的形式对外暴露。
+
+注意事项：
+- 本接收器通过 Supabase REST API 直接写表，使用 `SUPA_KEY` 时请确保权限与密钥安全（不要将 service_role key 公开到前端）。
+- 如果你的 Supabase 接口部署在内网，请确保接收器能访问 `SUPA_URL`（网络/防火墙）。
+- 若需要更严格的验签/重放检测/幂等，请告知，我可以把这些能力加入接收器（例如记录并比对 dedupe_key 或检查 X-Timestamp 时间窗口）。
+
+下一步建议：
+- 若你要把第三方直接接到该接收器，请把 `WEBHOOK_SECRET` 与对方约定并启用验签。
+- 若需要我加重放防护或返回 4xx/5xx 更精确的逻辑，也可继续实现。
+
+文件位置：
+- [Webhook 接收器](pages/mall/delivery/server/webhook-receiver.js)
+
+作者：自动生成（可手动调整）