消息推送

2026-03-10 16:39:50 +08:00
parent ee9fabd806
commit e67016a6f4
18 changed files with 1176 additions and 49 deletions
--- a/docs/DELIVERY_E2E_TROUBLESHOOTING_20260310.md
+++ b/docs/DELIVERY_E2E_TROUBLESHOOTING_20260310.md
@@ -0,0 +1,215 @@
+# 物流 Webhook → 通知入库 → 推送到手机：联调问题记录（2026-03-10）
+
+本文记录本次将链路跑通时遇到的阻塞点、根因与修复方式，便于后续环境复现与排障。
+
+目标链路：
+1) webhook-receiver 接收物流回调并落库
+2) DB/服务侧写入 `notify_queue`
+3) `server/notify-worker.js` 消费 `notify_queue`，生成 `express_notifications`
+4) `server/push-server.js` 的 consumer 轮询 `express_notifications`，调用 `CLOUD_FUNC_URL` 推送到设备 `cid`
+
+---
+
+## 1. 症状：notify-worker 报 `order not found for waybill`
+
+**现象**
+- `notify_queue.process_status=skipped` 或 `failed`
+- `last_error=order not found for waybill`
+
+**根因**
+- `public.ml_orders` 启用了 RLS。
+- 后端通过 PostgREST 仅使用 `apikey`（或无法解码的 Bearer）访问时，`auth.uid()` 为空，RLS policy 不成立，导致对 `ml_orders` 的查询返回 `200 []`（看起来像“无数据”，实为被行级安全过滤）。
+
+**验证方法**
+- 对比：SQL Editor 里能查到订单，但经 `/rest/v1/ml_orders` 查不到。
+
+**临时修复（用于快速跑通链路）**
+```sql
+ALTER TABLE public.ml_orders DISABLE ROW LEVEL SECURITY;
+```
+
+**恢复建议（生产化方向）**
+- 不建议长期关闭 RLS。
+- 建议让后端使用可被 PostgREST 正确解码/信任的 service_role JWT，或通过 RPC/安全视图完成必要查询；避免依赖 `DISABLE RLS`。
+
+---
+
+## 2. 症状：写入 `express_notifications` 时报 `42P10`
+
+**现象**
+- `notify_queue.process_status=failed`
+- `last_error` 包含：
+  - `there is no unique or exclusion constraint matching the ON CONFLICT specification`
+
+**根因**
+- notify-worker / push-server 使用 PostgREST upsert：
+  - `POST /rest/v1/express_notifications?on_conflict=message_id`
+- 但数据库侧 `express_notifications(message_id)` 只有“部分唯一索引”（例如 `WHERE message_id IS NOT NULL`），无法匹配 `ON CONFLICT(message_id)`，触发 `42P10`。
+
+**修复（改为普通唯一索引）**
+- 执行脚本：
+  - `pages/mall/delivery/doc/需求文档/20260310_fix_express_notifications_on_conflict_message_id.sql`
+
+核心 SQL（摘要）：
+```sql
+DROP INDEX IF EXISTS public.ux_express_notifications_message_id;
+CREATE UNIQUE INDEX IF NOT EXISTS ux_express_notifications_message_id
+  ON public.express_notifications(message_id);
+```
+
+**修复后验证**
+- `notify_queue` 最新记录不再失败；`express_notifications` 能正常生成/更新。
+
+---
+
+## 3. 症状：push-server 启动失败 `EADDRINUSE 0.0.0.0:7301`
+
+**现象**
+- `node server/push-server.js` 直接退出
+- 提示端口占用
+
+**根因**
+- 7301 端口已有 node 进程占用（重复启动或遗留进程）
+
+**排查/处理（Windows）**
+```powershell
+netstat -ano | Select-String ":7301 "
+Get-Process -Id <PID>
+Stop-Process -Id <PID> -Force
+```
+
+---
+
+## 4. 症状：PGRST301（JWT 无法解码）导致访问异常
+
+**现象**
+- PostgREST 返回 `PGRST301` 或“JWT cannot be decoded/verified”
+
+**根因**
+- 在自托管/网关配置不一致时，手动发送 `Authorization: Bearer <SUPA_KEY>` 可能触发 JWT 解码失败。
+- 本仓库对 Supabase REST 调用默认只发 `apikey`，仅在显式 `SUPA_USE_BEARER=true` 时才附加 Bearer。
+
+**处理建议**
+- 保持 `SUPA_USE_BEARER=false`（默认）
+- 使用可用的 `apikey/service_role key` 走 Kong key-auth
+
+相关实现：
+- `server/push-server.js` 的 `supaFetch` 逻辑
+
+---
+
+## 5. 症状：数据库显示 `send_status=success`，但手机没弹通知
+
+**现象**
+- `express_notifications.send_status=success`
+- 但手机端没有系统通知/横幅
+
+**常见原因**
+1) 推送内容为空（部分通道/客户端不会展示空内容通知）
+2) 客户端处于前台/透传模式：消息到达但不自动弹系统通知（需要客户端本地展示）
+3) 手机系统通知权限/渠道被关闭、省电策略限制
+
+**本次定位与修复**
+- notify-worker 生成的 `express_notifications` 通常只有 `event_text_safe`（可作为标题），body/content 可能为空。
+- push-server consumer 调云函数时原先传入的 `content` 可能为空，导致“云函数返回成功，但不展示”。
+- 已在 `server/push-server.js` 增加兜底：当 body/content 为空时，使用 title/event_text_safe 作为 content。
+
+验证方法（直接调用云函数对 CID 推送）
+- 观察云函数返回中是否包含类似 `successed_online`；并对比手机是否实际展示。
+
+---
+
+## 6. 症状：merchant 侧 `send_status=no-targets`
+
+**现象**
+- `express_notifications.aud=merchant` 的记录 `send_status=no-targets`
+- `last_error=no active devices`
+
+**根因**
+- 设备绑定表 `push_devices` 仅存在 `user_id` 绑定，没有 `merchant_id` 绑定。
+
+**处理建议**
+- 让商家端也调用注册接口写入 `merchant_id` 维度的设备（或插入对应记录）。
+- push-server consumer 对 merchant 的设备查询路径是：
+  - `push_devices?merchant_id=eq.<recipient_id>&is_active=eq.true`
+
+---
+
+## 7. 端到端自检清单（最短路径）
+
+1) 触发 webhook 测试：
+- `node pages/mall/delivery/webhook-server/test-send.js`
+
+2) 查队列：
+- `notify_queue` 最新应为 `process_status=queued` 且 `last_error=null`
+
+3) 查通知：
+- `express_notifications` 最新应生成 `aud=user` 与 `aud=merchant` 两条
+- `aud=user` 通常应推进到 `send_status=success`
+
+4) 查设备：
+- `push_devices` 中对应 `user_id`/`merchant_id` 必须存在 `is_active=true` 的 `cid`
+
+---
+
+## 7.1 Windows 一键启动三服务（建议）
+
+为了保证与联调时一致的效果，推荐用脚本一次性启动 3 个后台进程（并落日志）：
+
+1) 启动（会默认释放 7201/7301 端口占用）：
+- `powershell -ExecutionPolicy Bypass -File .\server\scripts\start-delivery-backend.ps1`
+
+2) 触发与联调一致的 webhook 测试（打到本机 7201）：
+- `node .\pages\mall\delivery\webhook-server\test-send.js`
+
+3) 停止：
+- `powershell -ExecutionPolicy Bypass -File .\server\scripts\stop-delivery-backend.ps1`
+
+日志文件默认在仓库根目录：
+- `webhook-receiver.log/.err.log`
+- `notify-worker.log/.err.log`
+- `push-server.log/.err.log`
+
+PID 文件（用于停止/排查进程）在：
+- `server/.runtime/delivery-backend.pids.json`
+
+查看当前是否仍在运行（示例）：
+- `Get-Content .\server\.runtime\delivery-backend.pids.json`
+- `Get-Process -Id <PID>`
+
+注意：`test-send.js` 默认请求 `http://localhost:7201/webhook/express/status`，所以必须先启动 webhook-receiver。
+
+如果 `test-send.js` 返回 `{ ok: false, message: 'waybill not found' }`：
+- 说明数据库里没有 `platform_express_waybills.tracking_no = 'TEST_YT_20260206_0007'` 的运单记录。
+- 处理方式：先在 `platform_express_waybills` 补一条对应 tracking_no 的运单（并关联到你的 `ml_orders`），再重试发送。
+
+---
+
+## 8. 常用 SQL / 操作片段
+
+### 8.1 重跑某条队列记录（把 failed/skipped 重置为可再次消费）
+```sql
+UPDATE public.notify_queue
+SET processed_at = NULL,
+    process_status = NULL,
+    last_error = NULL
+WHERE id = '<notify_queue.id>';
+```
+
+### 8.2 检查 message_id 是否存在重复（创建唯一索引前）
+```sql
+SELECT message_id, COUNT(*)
+FROM public.express_notifications
+WHERE message_id IS NOT NULL
+GROUP BY message_id
+HAVING COUNT(*) > 1;
+```
+
+### 8.3 查看 `push_devices` 是否有绑定
+```sql
+SELECT *
+FROM public.push_devices
+WHERE user_id = '<user_id>' OR merchant_id = '<merchant_id>'
+ORDER BY updated_at DESC
+LIMIT 20;
+```
--- a/docs/DELIVERY_WEBHOOK_PUSH_SERVER_OVERVIEW.md
+++ b/docs/DELIVERY_WEBHOOK_PUSH_SERVER_OVERVIEW.md
@@ -53,9 +53,13 @@
  - `platform_express_waybills`（运单摘要 current_status_*）

 2) **消息生成段**（通常是“事件处理器/任务/触发器”，不在这两个服务里）
- 监听/轮询 `platform_express_tracking_events` 的新增事件
- 按推送策略（关键状态、去噪、幂等）生成“消息中心记录/推送任务”
- 写入 `express_notifications`（或调用 push-server 的 HTTP 接口让其写入）
+- 触发器把 `platform_express_tracking_events` 的关键状态事件写入队列表 `notify_queue`
+- 常驻 `notify-worker` 消费 `notify_queue`，按推送策略（关键状态、去噪、幂等）生成“消息中心记录/推送任务”
+- 写入 `express_notifications`（push-server consumer 会复用该表进行下发）
+
+相关实现（仓库内）：
+- 迁移脚本：`pages/mall/delivery/doc/需求文档/20260309_add_notify_queue_and_trigger.sql`
+- 常驻 worker：`server/notify-worker.js`

 3) **推送下发段**（Push Server + 云函数负责）
 - push-server consumer 读取 `express_notifications` 的待处理记录
@@ -72,8 +76,10 @@ flowchart LR
  WH --> EV[(platform_express_tracking_events)]
  WH --> WB[(platform_express_waybills)]

-  EV --> EP[事件处理器/任务/触发器]
-  EP --> N[(express_notifications)]
+  EV --> TRG[DB Trigger]
+  TRG --> Q[(notify_queue)]
+  Q --> W[notify-worker]
+  W --> N[(express_notifications)]

  App[App 客户端] -->|注册CID| PS[push-server :7301]
  PS --> D[(push_devices)]
@@ -177,6 +183,14 @@ flowchart LR
 - `public.express_notifications`
  - 存储待发通知、状态、重试信息等（用于消息中心/推送队列）

+字段语义（重要，避免联调误判）：
+- `status_code`：物流/业务状态（例如 `OUT_FOR_DELIVERY/DELIVERED/EXCEPTION`），由 webhook→tracking_events→notify-worker 生成。
+- `send_status`：投递处理状态（`null`=待发送，`processing/retrying/success/failed/no-targets`），由 push-server consumer 读写。
+
+迁移脚本：
+- 新环节（入队+worker）：`pages/mall/delivery/doc/需求文档/20260309_add_notify_queue_and_trigger.sql`
+- 字段拆分（consumer 必需）：`pages/mall/delivery/doc/需求文档/20260309_add_express_notifications_send_status.sql`
+
 迁移脚本参考：`pages/mall/delivery/doc/需求文档/20260224_add_push_devices_and_notifications.sql`

 ### 4.4 关键配置（env）
@@ -191,6 +205,38 @@ flowchart LR
 - `PUSH_TOKEN`：可选鉴权透传给云函数
 - 重试配置：`MAX_RETRIES / RETRY_INITIAL_MS / RETRY_FACTOR / RETRY_MAX_MS`

+### 4.4.1 云函数过期/URL 变更时，改哪里？
+
+现象：云函数链接过期或更换后，push-server 下发会出现 HTTP 4xx/5xx 或网络错误（日志里通常能看到调用 `CLOUD_FUNC_URL` 失败），并导致 `express_notifications.send_status` 长期处于 `retrying/failed`。
+
+需要修改的配置键：
+- `CLOUD_FUNC_URL`：云函数 HTTP invoke 地址（push-server consumer 与 `/api/v1/push/send` 都依赖它）
+- （如云函数鉴权也变化）`PUSH_TOKEN`
+
+配置可能存在于以下位置（按优先级理解即可）：
+1) **系统环境变量**（临时验证/单次启动最方便）
+2) **显式配置文件**：通过 `CONFIG_FILE/CONFIG_PATH` 指定的 `.json` 或 `.env`
+3) **默认配置文件**：`server/config.json`（`server/load-config.js` 会读取并注入 env）
+
+最常用改法（推荐）：修改 `server/config.json` 里的 `CLOUD_FUNC_URL`，然后重启 push-server。
+
+PowerShell 快速验证（不改文件，先确认新 URL 可用）：
+```powershell
+$env:CLOUD_FUNC_URL='https://new-cloudfunc.example/invoke'
+node server/push-server.js
+```
+
+改完必须做的动作：
+- **重启 push-server**：`CLOUD_FUNC_URL` 在进程启动时读取，改配置后不重启不会生效。
+
+CI/自动化（如果你用了 smoke test）：
+- GitHub Actions / CI 里若有云函数 smoke test，通常还需要同步更新 Secrets（例如 `CLOUD_FUNC_URL`）。
+
+最小 smoke test（确认云函数通不通）：
+```powershell
+curl.exe -sS -X POST "$env:CLOUD_FUNC_URL" -H "Content-Type: application/json" -d "{\"token\":\"$env:PUSH_TOKEN\",\"push_clientid\":\"<DEVICE_CID>\",\"title\":\"ping\",\"content\":\"pong\",\"payload\":{}}"
+```
+
 ### 4.5 常见问题（定位方向）
 - Supabase 报 `PGRST301` / 401：通常是 Bearer/JWT_SECRET 不匹配导致，优先只用 `apikey`（`SUPA_USE_BEARER=false`）。
 - `/api/v1/push/send` 返回 `push_clientid required`：云函数侧没有正确解析请求体（常见于 HTTP 触发器把 body 放在 `event.body`）。
@@ -199,6 +245,65 @@ flowchart LR

 ---

+## 4.6 notify-worker（消息生成入队）
+
+### 4.6.1 作用（它负责哪一段）
+**一句话**：从 `notify_queue` 消费“需要生成消息的事件”，把它转换成 `express_notifications`（消息中心记录/推送任务），供 push-server consumer 后续下发。
+
+它关注的是：
+- **把事件变成消息**：把“物流事件”落成“可按 user/merchant 查询的消息记录”。
+- **收件人映射**：根据运单 → 订单，解析出 `user_id` / `merchant_id`。
+- **幂等入队**：对同一事件避免重复生成（靠稳定的 `message_id` upsert）。
+
+> 边界：notify-worker **不负责推送下发**；真正调用 `CLOUD_FUNC_URL` 的是 push-server consumer。
+
+### 4.6.2 位置与入口
+- 代码：`server/notify-worker.js`
+- 说明文档（更详细）：`server/NOTIFY_WORKER_README.md`
+
+### 4.6.3 核心行为（做了什么）
+1) 拉取待处理队列：`notify_queue?processed_at=is.null`（按 `created_at` 升序，批量处理）。
+2) 解析业务上下文：
+  - 查 `platform_express_waybills` 取 `order_id/order_no, tracking_no, carrier`
+  - 查 `ml_orders` 取 `user_id, merchant_id`
+3) 为每个受众写消息：
+  - 若 `user_id` 存在：写 `aud='user'`
+  - 若 `merchant_id` 存在：写 `aud='merchant'`
+  - 写入方式：upsert 到 `express_notifications`（`on_conflict=message_id`），避免重复。
+4) 回写队列处理结果：把 `notify_queue.processed_at` 置上，并写 `process_status/last_error`（queued/skipped/failed）。
+
+### 4.6.4 数据依赖（读/写哪些表）
+- 读取：`notify_queue`、`platform_express_waybills`、`ml_orders`
+- 写入：`express_notifications`
+
+关键字段口径：
+- `notify_queue.dedupe_key`：应尽量稳定（同一事件重复到达也一致），否则会造成重复消息。
+- `express_notifications.message_id`：脚本按 `aud|waybill_id|dedupe_key` 计算 hash 生成，用于幂等。
+
+### 4.6.5 配置与运行（最小要点）
+配置加载与 webhook/push-server 一致（复用 `server/load-config.js`），并支持同目录 `server/notify-worker.config.json`。
+
+常用环境变量：
+- `SUPA_URL`（必需）
+- `SERVICE_ROLE_KEY` 或 `SUPA_KEY`（必需，推荐 service_role）
+- `SUPA_USE_BEARER`（可选，默认 false）
+- `NOTIFY_WORKER_POLL_MS`（默认 2000）
+- `NOTIFY_WORKER_BATCH_SIZE`（默认 20）
+- `RUN_ONCE=true`（只跑一轮便退出，适合验证）
+
+启动示例（PowerShell）：
+```powershell
+node server/notify-worker.js
+```
+
+### 4.6.6 常见问题（定位方向）
+- 队列一直堆积：看 `notify-worker.err.log`/控制台错误；重点检查 `SUPA_URL/SERVICE_ROLE_KEY` 是否正确、表/字段是否存在。
+- 都是 skipped：通常是运单找不到订单（`platform_express_waybills` 缺 `order_id/order_no` 或 `ml_orders` 查不到）。
+- 重复消息：检查上游写入 `notify_queue.dedupe_key` 是否稳定（避免 `Date.now()` 这种随机值）。
+- RLS/403：优先使用 `SERVICE_ROLE_KEY`，并确保 PostgREST 有权限访问相关表。
+
+---
+
 ## 5. 给联调/运维的“最小心智模型”

 - Webhook-receiver 只负责：**接收** & **入库**（`platform_express_*`）。
@@ -259,10 +364,72 @@ flowchart LR

 ---

+## 5.2 联调/运维速记（2026-03-10）
+
+下面是本仓库在“webhook → 入库 → 入队 → notify-worker 生成通知 → push-server consumer 调云函数推送到手机”端到端跑通时，最容易踩到的坑与对应结论（只写要点；细节见排障文档）。
+
+更详细的排障与 SQL 清单：`docs/DELIVERY_E2E_TROUBLESHOOTING_20260310.md`
+
+### 5.2.1 最常见的故障与根因（按出现频率）
+
+1) **notify-worker 报 “order not found for waybill” 但数据库明明有订单**
+- 典型根因：`ml_orders` 开了 RLS，PostgREST 用 `apikey` 查询会返回空数组（看起来像“没数据”）。
+- 处理建议：生产上用 `SERVICE_ROLE_KEY` 或服务端 JWT + 正确策略；联调阶段可以临时放开/调整策略以确认链路。
+
+2) **写 `express_notifications` upsert 报 `42P10`（ON CONFLICT 找不到唯一约束）**
+- 典型根因：表上是“部分唯一索引（partial unique index）”，而 PostgREST 的 `on_conflict=message_id` 只能匹配“普通 UNIQUE 约束/索引”。
+- 处理建议：确保存在普通唯一索引：`UNIQUE(message_id)`（不要带 WHERE 条件）。
+
+3) **push-server 启动失败：`EADDRINUSE` / 7301 端口被占用**
+- 典型根因：旧进程未退出、或端口被其它程序占用。
+- 处理建议：先释放端口再启动；一键启动脚本会自动尝试清理 7201/7301。
+
+4) **日志显示云函数调用 success，但手机不弹通知**
+- 典型根因：下发的 `content/body` 为空或过短，在某些系统/机型上会被折叠为“不展示”。
+- 处理建议：确保推送请求里至少有稳定的 `title` + `content`（本仓库已在 consumer 侧做了 content 兜底）。
+
+5) **`send_status=no-targets`（找不到目标设备）**
+- 典型根因：`push_devices` 里没有对应 `user_id/merchant_id` 的活跃 `cid`（未注册/已注销/绑定字段为空）。
+- 处理建议：先用 App 触发注册接口写入设备表；若要商家端收推送，必须正确绑定 `merchant_id`。
+
+### 5.2.2 Windows 下一键启动/停止（后台常驻）
+
+为方便“可运维 + 可自启动”，仓库提供了 PowerShell 脚本把 3 个常驻进程统一拉起/停掉：
+
+- 启动（会尽量释放 7201/7301，并把进程 PID 写入 runtime 文件）：
+```powershell
+powershell -ExecutionPolicy Bypass -File .\server\scripts\start-delivery-backend.ps1
+```
+
+- 停止（按 PID 文件停止进程）：
+```powershell
+powershell -ExecutionPolicy Bypass -File .\server\scripts\stop-delivery-backend.ps1
+```
+
+- PID 文件位置（便于运维查进程/做自启接入）：
+  - `server/.runtime/delivery-backend.pids.json`
+
+> 说明：脚本按自身路径定位仓库 root，因此可以在任意工作目录执行；并会按 `server/load-config.js` 的规则加载配置（最常见是 `server/config.json`）。`CLOUD_FUNC_URL` 等配置变更后需重启进程才会生效。
+
+### 5.2.3 快速复现（和联调一致的 E2E）
+
+1) 先启动后台（见上节）。
+2) 触发 webhook 测试请求：
+```powershell
+node .\pages\mall\delivery\webhook-server\test-send.js
+```
+3) 观察链路：
+- webhook-receiver 日志是否收到请求；若返回 `{ ok:false, message:'waybill not found' }`，先补齐 `platform_express_waybills` 对应运单。
+- notify-worker 是否把队列变成 `express_notifications`。
+- push-server consumer 是否把 `send_status` 推进到 `success`（或 `no-targets/retrying/failed`）。
+
+---
+
 ## 6. 进一步阅读（从“总览”到“可落地”）

 - webhook-receiver：`pages/mall/delivery/webhook-server/README.md`
 - push-server（运行与变更记录）：`server/PUSH_SERVER_README.md`
+- notify-worker（消息生成入队）：`server/NOTIFY_WORKER_README.md`
 - push-server（消费者与云函数约定）：`server/README.md`
 - 配置加载器：`server/load-config.js`
 - 业务方案与隐私口径：