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
+}
+```