fix:阿里适配

2026-01-19 09:16:53 +08:00
parent 76bdcd1aba
commit 2a7c6c8e03
13 changed files with 272 additions and 70 deletions
@@ -0,0 +1,207 @@
+# 支付宝支付接口文档
+
+## 接口概述
+本文档描述支付宝支付相关的API接口，包括创建支付订单和查询支付状态。
+
+---
+
+## 1. 创建支付宝支付订单
+
+### 接口描述
+创建支付宝支付订单，用于扫码预下单并返回二维码。
+
+### 请求信息
+
+#### 请求URL
+```
+GET /app/ali-payment/create/{orderNo}
+```
+
+#### 请求方式
+`GET`
+
+#### 请求参数
+
+| 参数名 | 参数类型 | 是否必填 | 参数位置 | 参数说明 |
+|--------|----------|----------|----------|----------|
+| orderNo | String | 是 | Path | 订单号 |
+
+#### 请求示例
+```http
+GET /app/ali-payment/create/ORD20231223001
+```
+
+### 响应信息
+
+#### 响应参数
+
+| 参数名 | 参数类型 | 参数说明 |
+|--------|----------|----------|
+| code | Integer | 响应状态码，200表示成功 |
+| msg | String | 响应消息 |
+| data | Object | 返回数据，包含支付宝支付相关信息 |
+
+#### 响应示例
+
+成功响应：
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "qrCode": "https://qr.alipay.com/xxx",
+    "outTradeNo": "ORD20231223001",
+    "totalAmount": "99.00"
+  }
+}
+```
+
+失败响应：
+```json
+{
+  "code": 500,
+  "msg": "订单不存在或已支付"
+}
+```
+
+### 错误码说明
+
+| 错误码 | 说明 |
+|--------|------|
+| 200 | 创建成功 |
+| 400 | 参数错误，订单号不能为空 |
+| 500 | 系统错误或订单状态异常 |
+
+---
+
+## 2. 查询订单支付状态
+
+### 接口描述
+查询指定订单的支付状态。
+
+### 请求信息
+
+#### 请求URL
+```
+GET /app/ali-payment/status/{orderNo}
+```
+
+#### 请求方式
+`GET`
+
+#### 请求参数
+
+| 参数名 | 参数类型 | 是否必填 | 参数位置 | 参数说明 |
+|--------|----------|----------|----------|----------|
+| orderNo | String | 是 | Path | 订单号 |
+
+#### 请求示例
+```http
+GET /app/ali-payment/status/ORD20231223001
+```
+
+### 响应信息
+
+#### 响应参数
+
+| 参数名 | 参数类型 | 参数说明 |
+|--------|----------|----------|
+| code | Integer | 响应状态码，200表示成功 |
+| msg | String | 响应消息 |
+| data | Object | 订单支付状态信息 |
+| data.tradeStatus | String | 交易状态（WAIT_BUYER_PAY-等待支付，TRADE_SUCCESS-支付成功，TRADE_CLOSED-交易关闭） |
+| data.tradeNo | String | 支付宝交易号 |
+| data.totalAmount | String | 订单金额 |
+| data.buyerPayAmount | String | 买家实付金额 |
+
+#### 响应示例
+
+支付成功响应：
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "tradeStatus": "TRADE_SUCCESS",
+    "tradeNo": "2023122322001234567890",
+    "outTradeNo": "ORD20231223001",
+    "totalAmount": "99.00",
+    "buyerPayAmount": "99.00",
+    "buyerLogonId": "158****5620"
+  }
+}
+```
+
+等待支付响应：
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "tradeStatus": "WAIT_BUYER_PAY",
+    "outTradeNo": "ORD20231223001",
+    "totalAmount": "99.00"
+  }
+}
+```
+
+失败响应：
+```json
+{
+  "code": 500,
+  "msg": "订单不存在"
+}
+```
+
+### 支付状态说明
+
+| 状态码 | 说明 |
+|--------|------|
+| WAIT_BUYER_PAY | 交易创建，等待买家付款 |
+| TRADE_CLOSED | 未付款交易超时关闭，或支付完成后全额退款 |
+| TRADE_SUCCESS | 交易支付成功 |
+| TRADE_FINISHED | 交易结束，不可退款 |
+
+---
+
+## 公共说明
+
+### 基础路径
+```
+http://your-domain.com/app/ali-payment
+```
+
+### 请求头
+```
+Content-Type: application/json
+```
+
+### 注意事项
+
+1. **订单号格式**：订单号必须唯一，建议使用系统生成的订单编号
+2. **幂等性**：同一订单号多次调用创建接口，返回相同的支付信息
+3. **超时处理**：支付订单创建后，建议在15分钟内完成支付
+4. **状态查询**：建议在支付完成后通过回调通知处理业务逻辑，状态查询接口用于补充查询
+5. **安全性**：生产环境建议添加签名验证和请求频率限制
+
+### 业务流程
+
+```
+1. 用户发起租借 → 系统创建订单
+2. 调用创建支付接口 → 返回支付二维码
+3. 用户扫码支付 → 支付宝处理支付
+4. 支付宝回调通知 → 系统更新订单状态
+5. 前端轮询状态接口 → 确认支付结果
+6. 支付成功 → 触发开锁逻辑
+```
+
+---
+
+## 联系方式
+
+如有问题，请联系技术支持团队。
+
+**文档版本**：v1.0  
+**最后更新**：2025-12-23  
+**维护人员**：开发团队
+