medical-mall/server/消息推送文档/README.md

本文件为消息推送（Push Server）与云函数投递的精简说明，聚焦：该服务的职责、运行要点、快速启动命令与云函数调用约定。

目标读者：后端开发、联调/运维人员。更详细的实现细节请参考对应子文档与源码链接（下文有指引）。

概览

• 组件：
  • webhook-receiver：接收第三方物流回调并写入 platform_express_*（见 pages/mall/delivery/webhook-server）。
  • notify-worker：从 notify_queue 生成 express_notifications（消息中心记录）。
  • push-server：管理设备 CID、入队通知、消费者轮询并调用云函数下发推送（见 server/push-server.js）。

运行要点（快速）

• 一键启动（Windows PowerShell）：

powershell -ExecutionPolicy Bypass -File .\server\scripts\start-delivery-backend.ps1

• 停止：

powershell -ExecutionPolicy Bypass -File .\server\scripts\stop-delivery-backend.ps1

脚本说明（Windows PowerShell 5.1）：

• PID 文件：server/.runtime/delivery-backend.pids.json（由 start 脚本写入，UTF-8 无 BOM）。
• stop 脚本优先按 PID 停止，异常时会兜底释放端口（7201/7301）。
• 不停止直接重复启动，常见会报端口占用（EADDRINUSE）或出现多实例重复消费。
• 单独启动 push-server（示例）：

$env:CONFIG_FILE=(Resolve-Path .\server\config.json)
node server/push-server.js

• 启动 notify-worker：

node server/notify-worker.js

• 启动 webhook-receiver（开发）：

node .\pages\mall\delivery\webhook-server\webhook-receiver.js
# 测试脚本
node .\pages\mall\delivery\webhook-server\test-send.js

必备环境变量（最常用）

• SUPA_URL、SUPA_KEY（或 SERVICE_ROLE_KEY）— Supabase/PostgREST 地址与服务 key（后端专用）。
• CLOUD_FUNC_URL — 云函数 HTTP invoke 地址（push-server consumer 调用）。
• PUSH_TOKEN — 可选：云函数鉴权 token（由 push-server 透传）。
• ENABLE_CONSUMER / CONSUMER_POLL_MS — 是否启用消费者与轮询间隔。

云函数调用约定（push-server → 云函数）

• POST body（JSON）示例：

{
  "token":"<PUSH_TOKEN>",
  "push_clientid":"<CID>",
  "title":"...",
  "content":"...",
  "payload": { }
}

• 云函数兼容性提示：部分云厂商将真实请求体放在 event.body（字符串），云函数需先尝试解析 event.body。
• 成功判定：HTTP 2xx 且（可选）返回 JSON { errCode:0 }。

快速验证（端到端）

• 确保有一个活跃设备（写入 server/data/push_devices.json 或 Supabase push_devices）。
• 写入通知：

curl -X POST http://localhost:7301/api/v1/notifications -H "Content-Type: application/json" -d '{"aud":"user","recipient_id":123,"notification":{"title":"测试","body":"hello"}}'

• 等待消费者轮询并在 push-server 日志或 Supabase express_notifications.send_status 查看处理结果。

移除/精简说明

• 本文件已删除冗长的逐行排障示例、重复的 PowerShell 编码说明与历史已弃用的代理字段（如 PUSH_PROXY_URL 注释）。详细故障排查请看 DELIVERY_WEBHOOK_PUSH_SERVER_OVERVIEW.md 与各子文档。

重要链接

• push-server 源码： server/push-server.js
• 完整全链路数据流转分析：DELIVERY_NOTIFICATION_DATA_FLOW.md
• 运行与变更记录：PUSH_SERVER_README.md
• 消息生成Worker服务：NOTIFY_WORKER_README.md
• 云函数集成指引：UNI_PUSH2_CLOUD_FUNCTION.md
• 排错指南：DELIVERY_E2E_TROUBLESHOOTING_20260310.md
• webhook-receiver：../../pages/mall/delivery/webhook-server/README.md
• 部署脚本： server/scripts/start-delivery-backend.ps1
• 迁移脚本与 SQL： pages/mall/delivery/doc/需求文档/

如需我把这份精简后的内容合并到 DELIVERY_WEBHOOK_PUSH_SERVER_OVERVIEW.md 或把常用启动命令加入到仓库根 README，我可以继续提交修改。