模拟第三方信息存入数据库并进行消息推送

server/README.md

@@ -29,7 +29,9 @@
 }
 ```
 
-- 成功判定：云函数应返回 HTTP 2xx（服务会把非 2xx 或网络错误视为失败并按重试策略重试或标记失败）。
+- 成功判定：
+	- HTTP 层面：云函数应返回 HTTP 2xx（服务会把非 2xx 或网络错误视为失败并按重试策略重试或标记失败）。
+	- 业务层面（推荐约定）：若云函数返回 JSON 且包含 `ok:false` 或 `errCode!=0`，push-server 会视为失败并写入 `last_error`。
 
 - 快速启用示例（PowerShell）：
 
@@ -94,6 +96,53 @@ limit 10;
 - 常见现象解释：
 	- push-server 日志里 `supaFetch response preview: []`：表示当前没有 pending/retrying 且到期的记录可处理（队列为空）。
 
+## 常见问题：手机没通知/显示 ????
+
+### 1) `/api/v1/push/send` 返回 `errCode: 400, errMsg: "push_clientid required"`
+
+含义：云函数没有拿到 `push_clientid`，因此没有真正调用 uni-push 下发。
+
+常见原因：`CLOUD_FUNC_URL` 指向的是“HTTP 触发”云函数（例如 cloudbasefunction.cn）。这类云函数往往把 JSON 请求体放在 `event.body`（字符串）里，而不是直接放在 `event.push_clientid`。
+
+云函数侧的最小兼容写法（示例）：
+
+```js
+let input = event || {}
+if (input && typeof input.body === 'string') {
+	try { input = JSON.parse(input.body) } catch (e) { input = {} }
+} else if (input && input.body && typeof input.body === 'object') {
+	input = input.body
+}
+const { token, push_clientid, title, content, payload } = input
+```
+
+### 2) 手机通知标题/内容变成 `????`
+
+含义：中文在“发出请求前”已被错误编码成问号（常见于 Windows PowerShell 5.1 发送 JSON）。
+
+推荐做法：用 UTF-8 字节发送请求体（并带上 charset）：
+
+```powershell
+$bodyObj = @{
+	cids = @('YOUR_DEVICE_CID')
+	notification = @{ title = '测试标题'; body = '测试内容' }
+	payload = @{ order_id = '123' }
+}
+
+$json  = $bodyObj | ConvertTo-Json -Depth 10
+$bytes = [System.Text.Encoding]::UTF8.GetBytes($json)
+
+Invoke-RestMethod -Method Post -Uri 'http://127.0.0.1:7301/api/v1/push/send' `
+	-ContentType 'application/json; charset=utf-8' `
+	-Body $bytes | ConvertTo-Json -Depth 20
+```
+
+也可以使用 `curl.exe`（更接近 Linux curl 行为）来避免 PowerShell 的编码坑。
+
+### 3) 云函数“回显 recv”后反而收不到消息
+
+如果你为了排查乱码在云函数里加了 `return { recv: ... }` 之类的提前返回，云函数会在执行 `uniPush.sendMessage()` 之前就退出，自然不会真的推送。排查完成后请移除/注释该提前 return。
+
 - 注意：如果你需要“插入时立即触发云函数”的实时行为，可考虑将轮询改为 Supabase Realtime 订阅或使用 Supabase 的 Edge Function / webhook 触发器；我可以协助把轮询替换为实时订阅的示例实现。
 
 ---