fix: pay

docs/新增支付宝支付.md

@@ -0,0 +1,307 @@
+# 支付宝支付链接前端对接说明
+
+## 1. 对接范围
+
+本次新增的是 **C 端支付宝支付链接能力**。前端无需接入支付宝 SDK，后端会返回已签名的支付宝 WAP 支付链接。
+
+覆盖场景：
+
+1. 套餐订单支付
+2. 钱包充值
+3. 强制充值购包场景
+
+微信支付原逻辑保持不变：微信返回 `pay_config`，支付宝返回 `payment_link`。
+
+具体接口路径、完整请求字段、响应结构、错误码请以前端接口文档 / OpenAPI 文档为准。
+
+## 2. 支付方式取值
+
+前端统一使用 `payment_method` 区分支付方式：
+
+| 值 | 含义 | 前端处理 |
+| --- | --- | --- |
+| `wallet` | 钱包支付 | 仅订单支付支持，无第三方跳转 |
+| `wechat` | 微信支付 | 使用返回的 `pay_config` 调起微信支付 |
+| `alipay` | 支付宝支付 | 使用返回的 `payment_link` 打开或展示支付链接 |
+
+注意事项：
+
+- `app_type` 只在微信支付时需要。
+- 支付宝支付时不需要传 `app_type`。
+- 支付宝支付返回的是支付链接，不是 JSAPI 参数。
+
+## 3. 前端需要关注的响应字段
+
+当选择支付宝支付时，接口响应中会返回 `payment_link`：
+
+```json
+{
+  "payment_link": {
+    "payment_no": "支付单号",
+    "qr_link": "支付宝支付链接，可用于生成二维码",
+    "copy_link": "支付宝支付链接，可复制或直接打开",
+    "pay_expire_at": "支付链接过期时间，RFC3339 格式"
+  }
+}
+```
+
+字段说明：
+
+| 字段 | 用途 |
+| --- | --- |
+| `payment_no` | 支付单号，问题排查 / 客服查询使用 |
+| `qr_link` | 前端可用该链接生成二维码 |
+| `copy_link` | 用户复制或浏览器打开的支付链接，当前与 `qr_link` 一致 |
+| `pay_expire_at` | 支付链接过期时间，前端可用于倒计时展示 |
+
+## 4. 推荐交互流程
+
+### 4.1 支付宝支付流程
+
+前端拿到 `payment_link` 后：
+
+1. H5 / 浏览器场景：直接跳转 `copy_link`。
+
+支付成功后：
+
+- 不要只依赖支付宝返回页判断支付成功。
+- 最终支付状态以服务端订单 / 充值记录状态为准。
+- 用户返回页面后，前端应轮询订单详情、订单列表或充值记录接口。
+
+## 5. 各业务场景说明
+
+### 5.1 套餐订单支付
+
+普通套餐下单后，如果需要支付，前端调用订单支付接口，并传：
+
+```json
+{
+  "payment_method": "alipay"
+}
+```
+
+支付宝支付响应示例：
+
+```json
+{
+  "payment_method": "alipay",
+  "payment_link": {
+    "payment_no": "...",
+    "qr_link": "...",
+    "copy_link": "...",
+    "pay_expire_at": "..."
+  }
+}
+```
+
+前端根据 `payment_link` 发起支付宝支付。
+
+### 5.2 钱包充值
+
+创建钱包充值单时传：
+
+```json
+{
+  "payment_method": "alipay"
+}
+```
+
+支付宝场景返回 `payment_link`；微信场景返回 `pay_config`。
+
+### 5.3 强制充值购包
+
+创建订单时，如果后端判断需要强制充值，前端可指定：
+
+```json
+{
+  "payment_method": "alipay"
+}
+```
+
+如果是支付宝强充，响应中会返回：
+
+```json
+{
+  "order_type": "recharge",
+  "recharge": {},
+  "payment_link": {}
+}
+```
+
+前端按支付宝支付链接流程处理。
+
+## 6. 前端展示建议
+
+支付宝支付页面建议展示：
+
+- 支付金额
+- 支付宝二维码或“去支付宝支付”按钮
+- 支付链接过期倒计时
+- “我已完成支付”按钮
+- “重新获取支付链接”按钮
+
+点击“我已完成支付”时，不直接判定成功，应查询服务端状态。
+
+## 7. 注意事项
+
+1. 金额单位仍然是 **分**。
+2. 支付宝支付不需要 `app_type`。
+3. `pay_config` 只用于微信支付。
+4. `payment_link` 只用于支付宝支付。
+5. 支付状态以服务端为准，不以前端跳转结果为准。
+6. 支付链接过期后，前端应重新调用对应支付 / 充值接口获取新链接。
+7. 具体接口路径、完整字段、错误码请以前端接口文档 / OpenAPI 文档为准。
+
+# 支付宝支付链接前端对接说明
+
+## 1. 对接范围
+
+本次新增的是 **C 端支付宝支付链接能力**。前端无需接入支付宝 SDK，后端会返回已签名的支付宝 WAP 支付链接。
+
+覆盖场景：
+
+1. 套餐订单支付
+2. 钱包充值
+3. 强制充值购包场景
+
+微信支付原逻辑保持不变：微信返回 `pay_config`，支付宝返回 `payment_link`。
+
+具体接口路径、完整请求字段、响应结构、错误码请以前端接口文档 / OpenAPI 文档为准。
+
+## 2. 支付方式取值
+
+前端统一使用 `payment_method` 区分支付方式：
+
+| 值 | 含义 | 前端处理 |
+| --- | --- | --- |
+| `wallet` | 钱包支付 | 仅订单支付支持，无第三方跳转 |
+| `wechat` | 微信支付 | 使用返回的 `pay_config` 调起微信支付 |
+| `alipay` | 支付宝支付 | 使用返回的 `payment_link` 打开或展示支付链接 |
+
+注意事项：
+
+- `app_type` 只在微信支付时需要。
+- 支付宝支付时不需要传 `app_type`。
+- 支付宝支付返回的是支付链接，不是 JSAPI 参数。
+
+## 3. 前端需要关注的响应字段
+
+当选择支付宝支付时，接口响应中会返回 `payment_link`：
+
+```json
+{
+  "payment_link": {
+    "payment_no": "支付单号",
+    "qr_link": "支付宝支付链接，可用于生成二维码",
+    "copy_link": "支付宝支付链接，可复制或直接打开",
+    "pay_expire_at": "支付链接过期时间，RFC3339 格式"
+  }
+}
+```
+
+字段说明：
+
+| 字段 | 用途 |
+| --- | --- |
+| `payment_no` | 支付单号，问题排查 / 客服查询使用 |
+| `qr_link` | 前端可用该链接生成二维码 |
+| `copy_link` | 用户复制或浏览器打开的支付链接，当前与 `qr_link` 一致 |
+| `pay_expire_at` | 支付链接过期时间，前端可用于倒计时展示 |
+
+## 4. 推荐交互流程
+
+### 4.1 支付宝支付流程
+
+前端拿到 `payment_link` 后：
+
+1. H5 / 浏览器场景：直接跳转 `copy_link`。
+
+支付成功后：
+
+- 不要只依赖支付宝返回页判断支付成功。
+- 最终支付状态以服务端订单 / 充值记录状态为准。
+- 用户返回页面后，前端应轮询订单详情、订单列表或充值记录接口。
+
+## 5. 各业务场景说明
+
+### 5.1 套餐订单支付
+
+普通套餐下单后，如果需要支付，前端调用订单支付接口，并传：
+
+```json
+{
+  "payment_method": "alipay"
+}
+```
+
+支付宝支付响应示例：
+
+```json
+{
+  "payment_method": "alipay",
+  "payment_link": {
+    "payment_no": "...",
+    "qr_link": "...",
+    "copy_link": "...",
+    "pay_expire_at": "..."
+  }
+}
+```
+
+前端根据 `payment_link` 发起支付宝支付。
+
+### 5.2 钱包充值
+
+创建钱包充值单时传：
+
+```json
+{
+  "payment_method": "alipay"
+}
+```
+
+支付宝场景返回 `payment_link`；微信场景返回 `pay_config`。
+
+### 5.3 强制充值购包
+
+创建订单时，如果后端判断需要强制充值，前端可指定：
+
+```json
+{
+  "payment_method": "alipay"
+}
+```
+
+如果是支付宝强充，响应中会返回：
+
+```json
+{
+  "order_type": "recharge",
+  "recharge": {},
+  "payment_link": {}
+}
+```
+
+前端按支付宝支付链接流程处理。
+
+## 6. 前端展示建议
+
+支付宝支付页面建议展示：
+
+- 支付金额
+- 支付宝二维码或“去支付宝支付”按钮
+- 支付链接过期倒计时
+- “我已完成支付”按钮
+- “重新获取支付链接”按钮
+
+点击“我已完成支付”时，不直接判定成功，应查询服务端状态。
+
+## 7. 注意事项
+
+1. 金额单位仍然是 **分**。
+2. 支付宝支付不需要 `app_type`。
+3. `pay_config` 只用于微信支付。
+4. `payment_link` 只用于支付宝支付。
+5. 支付状态以服务端为准，不以前端跳转结果为准。
+6. 支付链接过期后，前端应重新调用对应支付 / 充值接口获取新链接。
+7. 具体接口路径、完整字段、错误码请以前端接口文档 / OpenAPI 文档为准。