# 支付宝第三方接口开发总结

## 开发概述

本次开发在支付模块中新增了支付宝当面付第三方接口功能，通过调用旧系统的PHP接口生成支付URL和二维码。

## 新增文件清单

### 1. 核心代码文件

#### AlipayThirdPartyClient.java
**路径**: `dryad-payment/src/main/java/com/ruoyi/payment/infrastructure/channel/alipay/AlipayThirdPartyClient.java`

**功能**: 
- 封装第三方支付宝接口调用
- 使用Apache HttpClient发送multipart/form-data请求
- 解析第三方接口响应，提取支付URL

**核心方法**:
```java
public String createQrCodeUrl(String notifyUrl, String outTradeNo, Integer totalFee, String serviceOrdId)
```

### 2. 服务层修改

#### PaymentService.java
**路径**: `dryad-payment/src/main/java/com/ruoyi/payment/application/service/PaymentService.java`

**新增内容**:
- 注入 `AlipayThirdPartyClient` Bean
- 新增方法 `createAlipayThirdPartyPrecreate()` - 处理第三方支付宝当面付业务逻辑
- 新增方法 `callAlipayThirdPartyPrecreate()` - 调用第三方接口生成支付URL

### 3. 控制器层修改

#### PaymentController.java
**路径**: `dryad-payment/src/main/java/com/ruoyi/payment/interfaces/controller/PaymentController.java`

**新增接口**:
- `POST /api/pay/alipay/thirdparty/precreate` - 发起支付宝当面付（第三方接口）

### 4. 文档文件

#### 支付宝第三方接口使用说明.md
**路径**: `dryad-payment/doc/支付宝第三方接口使用说明.md`

**内容**:
- 功能说明
- 接口参数文档
- 代码实现说明
- 使用示例
- 注意事项

#### 支付宝第三方接口测试文档.md
**路径**: `dryad-payment/doc/支付宝第三方接口测试文档.md`

**内容**:
- Postman测试步骤
- cURL测试命令
- 各种测试场景
- 前端集成示例
- 问题排查指南

## 技术实现要点

### 1. HTTP请求封装
使用Apache HttpClient发送multipart/form-data格式的POST请求：
```java
HttpEntity entity = MultipartEntityBuilder.create()
    .addTextBody("notify_url", notifyUrl)
    .addTextBody("out_trade_no", outTradeNo)
    .addTextBody("total_fee", String.valueOf(totalFee))
    .addTextBody("ServiceOrdID", serviceOrdId)
    .build();
```

### 2. 参数映射
| 业务参数 | 第三方参数 | 说明 |
|---------|-----------|------|
| callbackUrl | notify_url | 回调通知地址 |
| orderId | out_trade_no | 订单ID |
| amount | total_fee | 金额（分） |
| bizOrderId | ServiceOrdID | 业务订单号 |

### 3. URL解析
提供了灵活的URL解析方法，支持：
- 直接返回URL字符串
- JSON格式响应
- 带引号的URL字符串

可根据实际返回格式调整 `parseQrCodeUrl()` 方法。

### 4. 二维码生成
复用现有的 `QrCodeUtil` 工具类，将支付URL转换为Base64格式的二维码图片。

## 接口调用流程

```
前端请求
    ↓
PaymentController.createAlipayThirdPartyPrecreate()
    ↓
PaymentService.createAlipayThirdPartyPrecreate()
    ↓
callAlipayThirdPartyPrecreate()
    ↓
AlipayThirdPartyClient.createQrCodeUrl()
    ↓
HTTP POST → https://sys.966120.com.cn/alipay_pay_QR_NotifyUrl.php
    ↓
解析响应得到支付URL
    ↓
QrCodeUtil.generateQrCodeBase64() - 生成二维码
    ↓
保存订单和交易记录
    ↓
返回支付信息给前端
```

## 与标准接口的对比

| 对比项 | 标准支付宝SDK接口 | 第三方接口 |
|-------|----------------|----------|
| 实现类 | AlipayF2FClient | AlipayThirdPartyClient |
| 调用方式 | 支付宝SDK | HTTP POST |
| 接口地址 | 支付宝官方 | 旧系统PHP接口 |
| 返回内容 | qr_code | 支付URL |
| 接口路径 | /api/pay/alipay/precreate | /api/pay/alipay/thirdparty/precreate |

## 数据库表设计

### 订单表 (pay_order)
- 记录支付订单基本信息
- 支持多渠道（微信、支付宝）
- 2小时自动过期

### 交易表 (pay_transaction)
- 记录每笔交易详情
- 存储支付URL和二维码
- 关联订单ID

## 配置说明

### 默认配置
- 回调地址: `https://dsp.966120.com.cn/alipay/pay_notify`
- 二维码尺寸: 300x300
- 订单过期时间: 2小时

### 可配置项
在 `PaymentService.callAlipayThirdPartyPrecreate()` 方法中可修改：
- 默认回调地址
- 其他业务参数

## 测试要点

### 功能测试
- [x] 正常支付流程
- [x] 重复订单处理
- [x] 参数校验
- [x] 订单过期处理

### 接口测试
- [ ] 第三方接口可用性
- [ ] 网络异常处理
- [ ] 超时处理
- [ ] 返回格式解析

### 集成测试
- [ ] 与主应用集成
- [ ] 支付回调处理
- [ ] 前端展示二维码

## 注意事项

### 1. 响应格式适配
第三方接口的实际返回格式需要根据实际情况调整 `parseQrCodeUrl()` 方法：

```java
private String parseQrCodeUrl(String responseBody) {
    // 根据实际返回格式调整
    // 如果是JSON: JSONObject json = JSON.parseObject(responseBody);
    // 如果是纯文本: return responseBody.trim();
}
```

### 2. 错误处理
建议添加更详细的错误处理和日志记录，便于问题排查。

### 3. 性能优化
考虑添加：
- HTTP连接池
- 超时设置
- 重试机制
- 熔断降级

### 4. 安全性
- 验证回调签名
- HTTPS通信
- 敏感信息加密

## 后续优化建议

### 短期优化
1. 根据实际返回格式完善URL解析逻辑
2. 添加单元测试
3. 完善异常处理
4. 增加接口日志

### 长期优化
1. 引入HTTP连接池管理
2. 实现重试和熔断机制
3. 添加接口监控和告警
4. 性能优化和压测
5. 支持异步处理

## 依赖说明

项目已包含所需依赖，无需额外添加：
- `org.apache.httpcomponents:httpclient:4.5.13`
- `com.google.zxing:core:3.4.1`
- `com.google.zxing:javase:3.4.1`

## 部署说明

### 开发环境
1. 确保数据库配置正确
2. 验证第三方接口可访问
3. 启动服务测试

### 生产环境
1. 配置正确的回调地址
2. 设置合理的超时时间
3. 添加监控和告警
4. 进行压力测试

## 联系方式

如有问题，请查阅：
- 使用说明文档: `doc/支付宝第三方接口使用说明.md`
- 测试文档: `doc/支付宝第三方接口测试文档.md`

## 版本历史

### v1.0.0 (2025-11-24)
- ✅ 新增支付宝第三方接口功能
- ✅ 支持调用旧系统PHP接口
- ✅ 生成支付URL和二维码
- ✅ 完善文档和测试用例