feat(payment): implement coffee tip plans and update payment flow

2026-07-14 11:48:46 +08:00
parent f9c15bd91f
commit 3a4f24cb06
30 changed files with 632 additions and 56 deletions
@@ -0,0 +1,132 @@
+# Cozsweet 咖啡打赏接口
+
+## 1. 用途
+
+前端展示三个一次性咖啡打赏档位，并复用现有支付建单、支付跳转和订单轮询流程。
+
+## 2. 接口地址
+
+| 功能 | 方法 | 路径 | 鉴权 |
+| --- | --- | --- | --- |
+| 查询打赏品类 | GET | `/api/payment/tip-plans` | 不需要 |
+| 创建打赏订单 | POST | `/api/payment/create-order` | Bearer Token |
+| 查询订单状态 | GET | `/api/payment/order-status?order_id=...` | Bearer Token |
+
+## 3. 查询打赏品类
+
+```bash
+curl 'https://api.banlv-ai.com/api/payment/tip-plans'
+```
+
+成功响应：
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "success": true,
+  "data": {
+    "plans": [
+      {
+        "planId": "tip_coffee_usd_4_99",
+        "planName": "Small Coffee",
+        "orderType": "tip",
+        "tipType": "coffee_small",
+        "description": "Buy Elio a small coffee",
+        "amountCents": 499,
+        "currency": "USD",
+        "autoRenew": false,
+        "isFirstRechargeOffer": false,
+        "firstRechargeDiscountPercent": 0
+      },
+      {
+        "planId": "tip_coffee_usd_9_99",
+        "planName": "Medium Coffee",
+        "orderType": "tip",
+        "tipType": "coffee_medium",
+        "description": "Buy Elio a medium coffee",
+        "amountCents": 999,
+        "currency": "USD",
+        "autoRenew": false,
+        "isFirstRechargeOffer": false,
+        "firstRechargeDiscountPercent": 0
+      },
+      {
+        "planId": "tip_coffee_usd_19_99",
+        "planName": "Large Coffee",
+        "orderType": "tip",
+        "tipType": "coffee_large",
+        "description": "Buy Elio a large coffee",
+        "amountCents": 1999,
+        "currency": "USD",
+        "autoRenew": false,
+        "isFirstRechargeOffer": false,
+        "firstRechargeDiscountPercent": 0
+      }
+    ]
+  }
+}
+```
+
+当前三个档位如下，顺序就是接口返回顺序：
+
+| `planId` | `tipType` | 价格 |
+| --- | --- | ---: |
+| `tip_coffee_usd_4_99` | `coffee_small` | USD 4.99 |
+| `tip_coffee_usd_9_99` | `coffee_medium` | USD 9.99 |
+| `tip_coffee_usd_19_99` | `coffee_large` | USD 19.99 |
+
+三个档位都不按国家换币、不参与首充半价，也不发会员或积分。前端必须使用接口返回的 `planId`，不要根据价格自行拼接。
+
+## 4. 创建打赏订单
+
+```bash
+curl -X POST 'https://api.banlv-ai.com/api/payment/create-order' \
+  -H 'Authorization: Bearer <TOKEN>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "planId": "tip_coffee_usd_9_99",
+    "payChannel": "stripe",
+    "autoRenew": false
+  }'
+```
+
+| 字段 | 类型 | 必填 | 固定/可选值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `planId` | string | 是 | 上表三个 ID 之一 | 咖啡打赏产品 ID。 |
+| `payChannel` | string | 是 | `stripe` / `ezpay` | 支付渠道。 |
+| `autoRenew` | boolean | 是 | `false` | 打赏是一次性支付，必须传 false。 |
+
+成功响应与现有充值相同：
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "success": true,
+  "data": {
+    "orderId": "pay_xxx",
+    "payParams": {
+      "url": "https://checkout.example/..."
+    },
+    "expiresAt": "2026-07-14T10:30:00+00:00",
+    "expiresInSeconds": 1800
+  }
+}
+```
+
+前端必须打开 `payParams` 中的支付 URL，并每 3-5 秒轮询订单状态。
+
+## 5. 订单状态与 WebSocket
+
+支付完成后：
+
+```json
+{
+  "orderId": "pay_xxx",
+  "status": "paid",
+  "orderType": "tip",
+  "planId": "tip_coffee_usd_9_99",
+  "creditsAdded": 0
+}
+```
@@ -57,9 +57,9 @@ https://<APP_HOST>/external-entry?target=private-room

 | `coffee_type` | 展示名称 | 价格 | 后端套餐 `planId` |
 | --- | --- | --- | --- |
-| `small` | Small Coffee | US$4.99 | `tip_coffee_small` |
-| `medium` | Medium Coffee | US$9.99 | `tip_coffee_medium` |
-| `large` | Large Coffee | US$19.99 | `tip_coffee_large` |
+| `small` | Small Coffee | US$4.99 | `tip_coffee_usd_4_99` |
+| `medium` | Medium Coffee | US$9.99 | `tip_coffee_usd_9_99` |
+| `large` | Large Coffee | US$19.99 | `tip_coffee_usd_19_99` |

 分别进入三种咖啡打赏页面：

@@ -71,7 +71,7 @@ https://<APP_HOST>/external-entry?target=tip&coffee_type=large

 外部入口会将它们规范化为 `/tip?coffee_type=<type>`。`coffee_type` 会在登录、Stripe 回跳和 Ezpay 回跳期间保留，确保支付流程始终使用最初选择的咖啡档位。

-实际创建订单时，前端只使用对应 `planId` 的后端套餐；Small 额外兼容旧套餐 `tip_coffee`。最终支付金额以后端返回的套餐数据为准，若找不到对应套餐，页面会禁止下单，避免使用错误档位。
+实际创建订单时，前端通过 `/api/payment/tip-plans` 获取套餐，并只使用接口返回的对应 `planId`。最终支付金额以后端返回的套餐数据为准，若找不到对应套餐，页面会禁止下单，避免使用错误档位。

 ## 促销入口