's'

docs/PAYJSAPI_NOMADVIP_SPEC.md

@@ -0,0 +1,219 @@
+# payjsapi nomadvip 对接规范
+
+**问题**：支付成功后，页面显示账号，但 PocketBase `payments` 表和 Memos 账户均无记录，导致会员验证失败。
+
+**原因**：payjsapi 支付回调未正确写入 PocketBase 及创建 Memos 账号。
+
+---
+
+## 一、nomadvip 调用流程
+
+```
+用户点击「立即加入」
+  → nomadvip POST /api/pay (user_id, site_id: "vip", ...)
+  → nomadvip 调用 payjsapi POST /nomadvip/payh5
+  → payjsapi 返回支付参数，用户完成支付
+  → 支付渠道回调 payjsapi
+  → 【payjsapi 必须】写入 PocketBase payments + site_vip，创建 Memos 账号
+  → nomadvip 轮询 GET /api/pay/status?order_id=xxx
+  → nomadvip 调用 payjsapi GET /nomadvip/order_status?order_id=xxx
+  → payjsapi 返回 { paid: true }
+```
+
+---
+
+## 二、payjsapi 支付回调必须完成
+
+### 2.1 写入 PocketBase `payments` 表
+
+| 字段 | 说明 | 示例 |
+|------|------|------|
+| user_id | 订单中的 user_id（匿名格式 `user1773315608560` 或 PB 用户 ID） | `user1773315608560` |
+| type | 产品类型 | `vip` |
+| order_id | 支付订单号 | 渠道返回的 out_trade_no |
+| total_fee | 金额（分） | 8800 |
+| channel | 支付渠道 | wxpay / alipay |
+| created | 创建时间 | 自动 |
+
+**nomadvip 依赖**：`app/page.tsx` 的 `checkPaymentFromPB` 按 `user_id` 查询 payments 判断是否 VIP。**不写入则会员验证失败**。
+
+### 2.2 写入 PocketBase `site_vip` 表
+
+| 字段 | 说明 | 示例 |
+|------|------|------|
+| user_id | 同 payments.user_id | `user1773315608560` |
+| site_id | 固定 `vip` | `vip` |
+| order_id | 支付订单号 | 可选 |
+| expires_at | 到期时间，null 表示永久 | null |
+
+**nomadvip 依赖**：`/api/vip/check` 按 `user_id` + `site_id = "vip"` 校验 Cookie 登录用户的 VIP 状态。
+
+### 2.3 创建 Memos 账号
+
+- **Memos 地址**：qun.hackrobot.cn
+- **账号格式**：`user` + 时间戳，如 `user1773315608560`
+- **默认密码**：`12345678`
+
+payjsapi 在支付成功后，需调用 Memos API 或内部服务创建账号，账号名与订单中的 `user_id` 一致（匿名用户即为 `user1773315608560` 格式）。
+
+**nomadvip 依赖**：首页「星球登录信息」展示的账号即为此格式，用户需用该账号登录 qun.hackrobot.cn。
+
+---
+
+## 三、payjsapi 接口要求
+
+### 3.1 订单创建 `POST /nomadvip/payh5`
+
+**请求体**（nomadvip 已传递）：
+
+```json
+{
+  "user_id": "user1773315608560",
+  "site_id": "vip",
+  "total_fee": 8800,
+  "type": "vip",
+  "channel": "wxpay",
+  "return_url": "https://vip.hackrobot.cn/paid",
+  "client_ip": "可选"
+}
+```
+
+**要求**：订单存储时需保存 `user_id`、`site_id`，供支付回调使用。
+
+### 3.2 订单状态 `GET /nomadvip/order_status?order_id=xxx`
+
+**响应**：
+
+```json
+{ "paid": true }
+```
+
+或
+
+```json
+{ "paid": false }
+```
+
+**要求**：支付回调完成写入 payments/site_vip 后，此接口应返回 `paid: true`。nomadvip 据此判断支付成功并刷新页面。
+
+---
+
+## 四、order_status 接口（关键）
+
+**nomadvip 依赖**：支付成功后，nomadvip 轮询 `order_status`，若返回 `paid: true` 则调用 `/api/pay/confirm` 写入 PocketBase 和 Memos。**若 order_status 返回 false 或接口不存在，则 confirm 失败，payments/site_vip/Memos 均无记录**。
+
+payjsapi 必须实现：
+
+```
+GET /nomadvip/order_status?order_id=xxx
+响应: { "paid": true } 或 { "paid": false }
+```
+
+- 参数名必须为 `order_id`（与 nomadvip 传递一致）
+- 支付渠道回调完成后，必须返回 `paid: true`
+- 若 payh5/redirect 返回 301-308 重定向，建议响应头带上 `x-pay-order-id`，以便 nomadvip 正确轮询
+
+## 五、已有账号登录（可选，优先于 PocketBase 查询）
+
+nomadvip 会优先调用 payjsapi 验证 VIP，若接口不存在或失败则回退到 PocketBase。
+
+### 5.1 按 user_id 查 VIP `GET /nomadvip/check_vip?user_id=xxx`
+
+**响应**：
+
+```json
+{ "vip": true, "email": "user@example.com" }
+```
+
+或
+
+```json
+{ "vip": false }
+```
+
+**说明**：payjsapi 需查 users/payments/site_vip 关联，返回是否 VIP；若已关联邮箱可返回 `email` 供前端不再显示绑定表单。
+
+### 5.2 按邮箱+密码查 VIP `POST /nomadvip/check_vip_by_email`
+
+**请求体**：
+
+```json
+{ "email": "user@example.com", "password": "xxx" }
+```
+
+**响应**：
+
+```json
+{
+  "vip": true,
+  "token": "PB token",
+  "record": { "id": "xxx", "email": "xxx" },
+  "effectiveUserId": "user1773315608560"
+}
+```
+
+或
+
+```json
+{ "vip": false }
+```
+
+**说明**：payjsapi 需验证邮箱密码（PB users），再查 payments/site_vip 关联，返回 VIP 状态及 PB token/record。
+
+---
+
+## 六、检查清单（payjsapi 侧）
+
+- [ ] 支付回调写入 PocketBase `payments` 表
+- [ ] 支付回调写入 PocketBase `site_vip` 表（site_id = "vip"）
+- [ ] 支付回调创建 Memos 账号（user_id 格式，密码 12345678）
+- [ ] **`order_status` 在支付成功后返回 `paid: true`**（否则 nomadvip confirm 失败）
+- [ ] 订单创建时正确保存 `user_id`、`site_id`
+- [ ] （可选）`GET /nomadvip/check_vip?user_id=xxx` 按 user_id 查 VIP
+- [ ] （可选）`POST /nomadvip/check_vip_by_email` 按邮箱密码查 VIP
+
+---
+
+## 七、PocketBase 配置
+
+payjsapi 需配置：
+
+- `POCKETBASE_URL`：PocketBase 地址（如 https://pocketbase.hackrobot.cn）
+- `POCKETBASE_EMAIL` / `POCKETBASE_PASSWORD`：管理员账号，用于写入 payments、site_vip
+
+---
+
+## 八、日志要求（排查 VIP 登录问题）
+
+payjsapi 需在以下接口打印日志，便于排查「已有账号登录」失败：
+
+| 接口 | 建议日志 |
+|------|----------|
+| `GET /nomadvip/check_vip?user_id=xxx` | 请求 user_id、查询结果 vip |
+| `POST /nomadvip/check_vip_by_email` | 请求 email、PB 登录结果、vip 查询结果 |
+| `GET /nomadvip/order_status?order_id=xxx` | 请求 order_id、返回 paid |
+| 支付回调 | 写入 payments/site_vip 的 user_id、order_id |
+
+示例（Node/Express）：
+```js
+// check_vip
+console.log("[payjsapi] check_vip user_id=%s vip=%s", user_id, vip);
+
+// check_vip_by_email
+console.log("[payjsapi] check_vip_by_email email=%s pbLogin=%s vip=%s", email, !!token, vip);
+
+// order_status
+console.log("[payjsapi] order_status order_id=%s paid=%s", order_id, paid);
+```
+
+---
+
+## 九、Memos 集成
+
+Memos 账号创建方式取决于现有架构，可选：
+
+1. 直接调用 Memos API 创建用户
+2. 通过内部服务/队列异步创建
+3. 与 PocketBase users 表联动（若 Memos 与 PB 共享用户）
+
+账号名必须与 `user_id` 一致，以便 nomadvip 页面展示与登录流程一致。