# 支付宝第三方接口 - 快速开始指南

## 📋 功能概述

新增支付宝当面付第三方接口，通过调用旧系统PHP接口生成支付URL和二维码。

## 🚀 快速开始

### 1. 接口地址
```
POST /api/pay/alipay/thirdparty/precreate
```

### 2. 请求示例
```bash
curl --location --request POST 'http://localhost:8080/api/pay/alipay/thirdparty/precreate' \
--header 'Content-Type: application/json' \
--data-raw '{
  "bizOrderId": "BF20250012-1",
  "amount": 10000,
  "subject": "急救转运服务费",
  "description": "急救转运任务支付",
  "callbackUrl": "https://dsp.966120.com.cn/alipay/pay_notify"
}'
```

### 3. 响应示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "orderId": 1234567890123456789,
    "transactionId": 9876543210987654321,
    "status": "PENDING",
    "qrBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "expireAt": "2025-11-24T18:00:00"
  }
}
```

## 📁 新增文件清单

### 核心代码
- ✅ `AlipayThirdPartyClient.java` - 第三方接口调用客户端
- ✅ `PaymentService.java` - 新增第三方支付方法
- ✅ `PaymentController.java` - 新增第三方支付接口

### 文档
- ✅ `支付宝第三方接口使用说明.md` - 详细使用文档
- ✅ `支付宝第三方接口测试文档.md` - 测试指南
- ✅ `支付宝第三方接口开发总结.md` - 开发总结

## 🔑 核心参数说明

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| bizOrderId | String | 是 | 业务订单号 |
| amount | Integer | 是 | 金额（单位：分） |
| subject | String | 是 | 订单标题 |
| description | String | 否 | 订单描述 |
| callbackUrl | String | 是 | 支付回调地址 |

## ⚙️ 配置说明

已在 `application.yml` 中添加第三方接口配置：

```yaml
payment:
  alipay:
    thirdParty:
      enabled: true
      url: https://sys.966120.com.cn/alipay_pay_QR_NotifyUrl.php
      defaultNotifyUrl: https://dsp.966120.com.cn/alipay/pay_notify
      timeout: 30000
```

## 🧪 快速测试

### Postman测试
1. 创建POST请求：`http://localhost:8080/api/pay/alipay/thirdparty/precreate`
2. 设置Header：`Content-Type: application/json`
3. 设置Body（JSON格式）：
```json
{
  "bizOrderId": "TEST001",
  "amount": 100,
  "subject": "测试订单",
  "callbackUrl": "https://dsp.966120.com.cn/alipay/pay_notify"
}
```
4. 发送请求，获取二维码

### 前端展示二维码
```javascript
const qrImage = document.getElementById('qrImage');
qrImage.src = result.data.qrBase64;
```

## 🔄 调用流程

```
前端 → PaymentController 
     → PaymentService 
     → AlipayThirdPartyClient 
     → 第三方PHP接口
     → 返回支付URL 
     → 生成二维码 
     → 返回给前端
```

## 📊 与标准接口对比

| 接口类型 | 接口路径 | 调用方式 |
|---------|---------|---------|
| 标准接口 | `/api/pay/alipay/precreate` | 支付宝SDK |
| 第三方接口 | `/api/pay/alipay/thirdparty/precreate` | HTTP POST |

## ⚠️ 注意事项

1. **金额单位**：所有金额参数单位为**分**（1元 = 100分）
2. **订单过期**：订单默认**2小时**后过期
3. **重复调用**：相同业务订单号返回已存在记录
4. **回调地址**：必须配置正确的回调地址

## 🐛 问题排查

### 第三方接口调用失败
```bash
# 检查网络连接
ping sys.966120.com.cn

# 直接测试第三方接口
curl --location --request POST 'https://sys.966120.com.cn/alipay_pay_QR_NotifyUrl.php' \
--header 'Cookie: CAMEName=' \
--form 'notify_url="https://dsp.966120.com.cn/alipay/pay_notify"' \
--form 'out_trade_no="TEST001"' \
--form 'total_fee="100"' \
--form 'ServiceOrdID="TEST001"'
```

### 查看日志
```bash
# 查看服务日志
tail -f logs/dryad-payment.log

# 关键日志
- "调用第三方支付宝当面付接口"
- "第三方接口响应"
- "支付宝当面付（第三方接口）创建成功"
```

## 📞 技术支持

详细文档参考：
- `doc/支付宝第三方接口使用说明.md`
- `doc/支付宝第三方接口测试文档.md`
- `doc/支付宝第三方接口开发总结.md`

## 🎯 下一步

- [ ] 测试第三方接口可用性
- [ ] 验证返回URL格式并调整解析逻辑
- [ ] 集成到主应用
- [ ] 配置生产环境回调地址
- [ ] 进行完整流程测试

---

**开发完成时间**: 2025-11-24  
**版本**: v1.0.0