补充方案

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

@@ -21,6 +21,8 @@
 新增/修改的接口（简要）
 - GET `/health` — 健康检查。
 - POST `/api/v1/push/register` — 注册/更新设备；会写本地 `server/data/push_devices.json`，并尝试 upsert 到 Supabase `push_devices` 表（如果配置了 SUPA_URL + SERVICE_ROLE_KEY）。
+  - 支持字段：`cid`（必填）、`user_id`（可选）、`merchant_id`（可选）、`platform`（可选）、`appid`（可选，默认 `default`）。
+  - 注意：数据库侧 `push_devices` 的唯一约束是 `(appid, cid)`；服务端 upsert 使用 `on_conflict=appid,cid`。
 - POST `/api/v1/push/unregister` — 注销设备（本地并尝试同步 Supabase）。
 - GET `/api/v1/push/devices` — 列出设备（优先从 Supabase 获取）。
 - POST `/api/v1/push/send` — 直接按 `cids` 或 `user_id` 发送推送（仅云函数：对每个 cid POST 到 `CLOUD_FUNC_URL`）。
@@ -76,7 +78,14 @@ curl http://localhost:7301/health
 ```bash
 curl -X POST http://localhost:7301/api/v1/push/register \
   -H 'Content-Type: application/json' \
-  -d '{"cid":"test-cid-1","user_id":"<USER_UUID>","platform":"android"}'
+  -d '{"cid":"test-cid-1","user_id":"<USER_UUID>","platform":"android","appid":"default"}'
+```
+
+商家端注册（写 merchant_id 维度，避免 `send_status=no-targets`）：
+```bash
+curl -X POST http://localhost:7301/api/v1/push/register \
+  -H 'Content-Type: application/json' \
+  -d '{"cid":"test-cid-2","merchant_id":"<MERCHANT_UUID>","platform":"android","appid":"default"}'
 ```
 
 4) 按 user 发通知（写入 express_notifications 并触发推送）：
@@ -396,11 +405,11 @@ Auto-deploy process exited with code=0 signal=null
     ```
 - 关键环境变量：`SUPA_URL`、`SUPA_KEY`（Supabase REST）、`CLOUD_FUNC_URL`（云函数 invoke URL）、`PUSH_TOKEN`（云函数鉴权）。
 - 行为摘要：
-  - 轮询 `express_notifications`（status_code IS NULL）并选取记录；
-  - 通过带过滤的 PATCH 抢占（将 `status_code` 设为 `processing`）以避免并发重复处理；
+  - 轮询 `express_notifications`（`send_status IS NULL` 或 `send_status='retrying'` 且到期）并选取记录；
+  - 通过带过滤的 PATCH 抢占（将 `send_status` 设为 `processing`）以避免并发重复处理；
   - 查询目标设备（`push_devices`），对每个 `cid` 构造 event 并 POST 到 `CLOUD_FUNC_URL`；若未配置 `CLOUD_FUNC_URL` 则本次处理将失败并写入错误原因；
-  - 根据调用结果回写 `express_notifications.status_code` 为 `success` / `failed` / `no-targets`。
-- 限制与扩展点：当前 consumer 依赖 Supabase REST；尚未在 DB 中新增 `retry_count`/`last_error` 字段（建议在迁移中加入以支持指数退避与重试）；为保证高可用建议配合 `FOR UPDATE SKIP LOCKED` 或 Supabase Realtime 优化并发策略。
+  - 根据调用结果回写 `express_notifications.send_status` 为 `success` / `failed` / `no-targets`（失败时会写入 `retry_count/last_error/next_attempt_at` 用于退避重试）。
+- 限制与扩展点：当前 consumer 依赖 Supabase REST；并发控制基于“先查后 claim”的方式实现（适合 MVP）。如需更强一致性/高并发，可进一步改造为 DB 端锁（`FOR UPDATE SKIP LOCKED`）或引入队列系统。
 
 文档实践
 ---------------------------------