本文件为消息推送（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
powershell -ExecutionPolicy Bypass -File .\server\scripts\start-delivery-backend.ps1
```
- 停止：
```powershell
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（示例）：
```powershell
$env:CONFIG_FILE=(Resolve-Path .\server\config.json)
node server/push-server.js
```
- 启动 notify-worker：
```powershell
node server/notify-worker.js
```
- 启动 webhook-receiver（开发）：
```powershell
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）示例：
```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`）。
- 写入通知：
```bash
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](../push-server.js)
- 完整全链路数据流转分析：`DELIVERY_NOTIFICATION_DATA_FLOW.md`
- 运行与变更记录：`PUSH_SERVER_README.md`
- 消息推送_数据库表结构需求文档：`../../pages/mall/delivery/doc/需求文档(现用)/db/消息推送后台_数据库表结构需求文档.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](../scripts/start-delivery-backend.ps1)
- 迁移脚本与 SQL： pages/mall/delivery/doc/需求文档/

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