消息推送

server/PUSH_SERVER_README.md

@@ -3,6 +3,10 @@
 简要说明
 - 该文档记录对 `server/push-server.js` 的修改、运行所需的环境变量、表结构依赖、以及如何把 Supabase 的 cid 与通知通过云函数（`CLOUD_FUNC_URL`）下发的端到端操作步骤。
 
+组件补充（新增）
+- `server/notify-worker.js`：常驻 worker，从 `notify_queue` 生成/写入 `express_notifications`（消息入队）。
+- 说明文档：`server/NOTIFY_WORKER_README.md`（包含技术栈/依赖、配置项、监控与管理者摘要）。
+
 变更要点（代码修改摘要）
 - supaFetch: 默认仅发送 `apikey`；仅当 `SUPA_USE_BEARER=true` 时才发送 `Authorization: Bearer`。用于避免自托管 Supabase/Kong 场景下因 JWT_SECRET 不一致触发 `PGRST301`。
 - 新增 endpoint `/api/v1/notifications`：将通知写入 `express_notifications`（排队）；由消费者（轮询）读取待处理记录并 POST 到 `CLOUD_FUNC_URL`。
@@ -26,6 +30,20 @@
 - `public.push_devices`：用于存储设备 cid、user_id/merchant_id、is_active 等（见仓库迁移脚本 `20260224_add_push_devices_and_notifications.sql`）。
 - `public.express_notifications`：用于保存通知记录与状态（见迁移脚本）。
 
+字段语义（从 2026-03-09 起，重要变更）
+- `status_code`：物流/业务状态（如 `OUT_FOR_DELIVERY/DELIVERED/...`），由 `notify-worker` 写入。
+- `send_status`：投递处理状态（`null`=待发送，`processing/retrying/success/failed/no-targets`），由 push-server consumer 读写。
+
+为什么需要这个变更：引入 `notify-worker` 后，`status_code` 不再适合作为“投递状态”，否则 consumer 会捞不到记录（或把物流状态误当投递状态）。
+
+迁移脚本（必需执行一次）：
+- `pages/mall/delivery/doc/需求文档/20260309_add_express_notifications_send_status.sql`
+
+消息生成（可选但推荐）
+- `public.notify_queue`：轨迹事件入队表（由 DB trigger 写入）。
+- 迁移脚本：`pages/mall/delivery/doc/需求文档/20260309_add_notify_queue_and_trigger.sql`（创建 `notify_queue` + `AFTER INSERT` trigger）。
+- 常驻消费者：`server/notify-worker.js`（从 `notify_queue` 生成 `express_notifications`；push-server consumer 再负责下发）。
+
 关键环境变量（示例与说明）
 - SUPA_URL — Supabase REST（PostgREST）地址（内部建议 `http://rest:3000`）。
 - SERVICE_ROLE_KEY 或 SUPA_KEY — 用作 `apikey` 向 PostgREST 请求（不要把明文放到 Authorization 除非该值确为 JWT）。
@@ -34,6 +52,7 @@
 - CONSUMER_POLL_MS — 轮询间隔（毫秒）。
 - CLOUD_FUNC_URL — 云函数外网调用 URL（每个目标 cid 会对该 URL 发 POST）。
 - PUSH_TOKEN — (可选) 云函数鉴权 token（会在 POST body 的 token 字段中透传）。
+- PUSH_SERVER_PORT — (可选) push-server 监听端口，默认 7301（推荐用这个，便于与 webhook-receiver 共享同一份 `server/config.json`）。
 
 <!--
 UNI_PUSH_URL / UNI_PUSH_APPID / UNI_PUSH_SECRET / PUSH_PROXY_URL / PUSH_PROXY_TOKEN：仅在非云函数模式下使用；当前已不再使用。
@@ -101,7 +120,7 @@ Invoke-RestMethod -Uri 'http://localhost:7301/api/v1/notifications' -Method POST
 - 在 Supabase 中查询最近记录：
 
 ```sql
-select id, message_id, status_code, retry_count, last_error, updated_at
+select id, message_id, send_status, status_code, retry_count, last_error, updated_at
 from public.express_notifications
 order by created_at desc
 limit 10;