修改消息后台的启动和停止文件并整理文档

server/消息推送文档/UNI_PUSH2_CLOUD_FUNCTION.md

@@ -0,0 +1,116 @@
+Uni‑Push2 云函数化指南
+
+概述
+- 后台实现概览：
+  - `webhook-receiver`（pages/mall/delivery/webhook-server）：接收第三方/Mock Webhook，验签并写入 `platform_express_tracking_events`（原始留痕 `platform_express_event_raw`）。
+  - `notify_queue`（或触发器）：新事件入队，作为消息生成的可靠中间件。
+  - `notify-worker.js`：消费 `notify_queue`，为每个收件人生成/upsert 到 `express_notifications`（含 `message_id`/`dedupe_key`、`event_text_safe` 等）。
+  - `push-server.js`：提供设备管理 API（`push/register` 等）并作为推送消费者（轮询 `express_notifications`），对每个目标 `cid` POST 到配置的 `CLOUD_FUNC_URL`（云函数），或在非云函数模式下调用推送通道。
+  - 云函数（Uni‑Push2）：实际负责把推送请求转为厂商推送（uni-push2 / 小米 / 华为 等），并返回调用结果；云函数应做鉴权、日志与重试上报。
+
+云函数化的目标
+- 把设备下发逻辑从后端移到可托管的云函数，降低后端对第三方 SDK 的依赖，便于横向扩展与运维隔离。
+
+云函数实现要点（示例流程）
+1) 接收：`push-server` 对每个 `cid` 发起 POST 到 `CLOUD_FUNC_URL`，body 包含：`token, push_clientid, title, content, payload`。
+2) 云函数处理：
+   - 兼容各云厂商：若 `event.body` 为字符串，先 JSON.parse；兼容 `event` 直接对象场景。
+   - 鉴权：校验 `event.token` 与环境变量 `PUSH_TOKEN`。
+   - 校验：要求 `push_clientid` 存在，否则返回 4xx。
+   - 调用 uni-push2：用云端可用的 SDK 或 HTTP 接口下发推送（参见示例代码）。
+   - 返回统一响应：HTTP 2xx + JSON { errCode:0, errMsg:'success' } 表示成功。
+
+云函数示例（Node.js，需按云平台调整）
+
+```javascript
+// index.js
+const fetch = require('node-fetch'); // 如果云平台不提供 fetch
+module.exports.main = async (event, context) => {
+  let input = event || {};
+  if (typeof input.body === 'string') {
+    try { input = JSON.parse(input.body); } catch (e) { /* ignore */ }
+  }
+
+  const { token, push_clientid, title, content, payload } = input;
+  if (process.env.PUSH_TOKEN && token !== process.env.PUSH_TOKEN) {
+    return { errCode:401, errMsg:'unauthorized' };
+  }
+  if (!push_clientid) return { errCode:400, errMsg:'push_clientid required' };
+
+  // TODO: 替换为你云函数环境支持的 uni-push2 调用
+  // 示例：调用一个第三方/自托管的推送服务 API
+  const uniPushUrl = process.env.UNI_PUSH_API_URL; // 可选：如果使用自建转发层
+  const body = {
+    appid: process.env.UNI_PUSH_APPID,
+    clientid: push_clientid,
+    title, content, payload
+  };
+
+  try {
+    // 如果你在云函数中安装了 uni-push2 SDK，请在此调用 SDK
+    // 下面为通用 fetch 示例（替换为真实厂商 API）
+    const r = await fetch(uniPushUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body)
+    });
+    const txt = await r.text();
+    if (!r.ok) return { errCode: 500, errMsg: 'push-failed', detail: txt };
+    return { errCode:0, errMsg:'success', data: txt };
+  } catch (e) {
+    return { errCode:500, errMsg:'exception', detail: e && e.message };
+  }
+};
+```
+
+依赖与打包
+- 两种方式：
+  1) 使用仓库已有的 `server/tools/deploy-cloudfunc.js` 自动打包并上传（推荐）：
+     - 在 `server` 目录安装依赖：`npm install archiver node-fetch form-data`（如脚本需要）。
+     - 配置环境变量 `CLOUD_UPLOAD_URL`、`CLOUD_UPLOAD_TOKEN`（按脚本要求），运行：
+       ```powershell
+       cd server
+       node tools/deploy-cloudfunc.js --upload
+       ```
+     - 脚本会把 `uniCloud-alipay/cloudfunctions/testUnipush2` 打包为 ZIP 并上传。
+  2) 手工打包上传：将云函数目录打包为 zip，使用云厂商控制台或 API 上传并发布。
+
+必备环境变量（运行时）
+- `PUSH_TOKEN`：云函数鉴权 token（与 `push-server` 中传出的 token 一致）。
+- `UNI_PUSH_APPID` / `UNI_PUSH_SECRET`（如厂商需要）。
+- `UNI_PUSH_API_URL`：可选；当云函数以 HTTP 方式调用第三方推送代理时使用。
+
+测试方法
+- 本地快速测试（若云函数开放公网可访问）：
+```bash
+curl -X POST https://your-cloudfunc.example/handle \
+  -H "Content-Type: application/json" \
+  -d '{"token":"<PUSH_TOKEN>","push_clientid":"CID_TEST","title":"测试","content":"hello","payload":{}}'
+```
+- PowerShell 注意 UTF-8 编码，避免中文变成问号：
+```powershell
+$json = '{"token":"<PUSH_TOKEN>","push_clientid":"CID_TEST","title":"测试","content":"内容"}'
+$bytes = [System.Text.Encoding]::UTF8.GetBytes($json)
+Invoke-RestMethod -Uri 'https://your-cloudfunc.example/handle' -Method POST -ContentType 'application/json; charset=utf-8' -Body $bytes
+```
+
+运维与监控建议
+- 日志：云函数应把每次调用的 request/response 摘要记录到云日志（包括 `push_clientid`、status、耗时、ret code），便于排查。不要在日志中输出完整敏感 payload。 
+- 重试：`push-server` consumer 应实现指数退避的重试；云函数若返回非 2xx，被视为失败并重试。云函数内部也应对推送通道失败做重试或将错误上报。
+- 鉴权与安全：`PUSH_TOKEN` 放在云函数的环境变量中并由 `push-server` 透传；上传/部署脚本的 `CLOUD_UPLOAD_TOKEN` 等密钥使用 CI Secrets。
+
+常见坑
+- Cloud 函数平台把请求体放在 `event.body`（字符串）——必须解析。示例代码已处理此场景。
+- PowerShell 发送 JSON 时编码问题，导致中文变问号——请用 UTF-8 bytes 或 `curl.exe`。
+- 若云函数调用 uni-push SDK，需要在函数包中包含对应 SDK 并在打包时一并上传。
+
+参考文件
+- push-server 实现：server/push-server.js
+- notify-worker：server/notify-worker.js
+- 云函数目录（示例）：uniCloud-alipay/cloudfunctions/testUnipush2
+- 自动部署脚本：server/tools/deploy-cloudfunc.js
+
+
+---
+作者：自动生成文档（可手动微调）
+日期：2026-03-11