276 lines
5.9 KiB
Markdown
276 lines
5.9 KiB
Markdown
|
# PingPong支付对接架构设计文档
|
|||
|
|
|
|||
|
|
## 一、整体架构分析
|
|||
|
|
|
|||
|
|
### 1.1 业务流程
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
用户发起支付
|
|||
|
|
↓
|
|||
|
|
创建支付订单（PaymentOrderService）
|
|||
|
|
↓
|
|||
|
|
调用PingPong API（PingPongPayService）
|
|||
|
|
↓
|
|||
|
|
生成签名（SignatureService）
|
|||
|
|
↓
|
|||
|
|
返回token和收银台地址
|
|||
|
|
↓
|
|||
|
|
用户跳转到收银台完成支付
|
|||
|
|
↓
|
|||
|
|
PingPong回调通知（CallbackService）
|
|||
|
|
↓
|
|||
|
|
更新订单状态
|
|||
|
|
↓
|
|||
|
|
业务系统处理
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 1.2 技术架构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
Controller层（API接口）
|
|||
|
|
↓
|
|||
|
|
Service层（业务逻辑）
|
|||
|
|
↓
|
|||
|
|
Repository层（数据访问）
|
|||
|
|
↓
|
|||
|
|
Entity层（数据模型）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 二、核心模块设计
|
|||
|
|
|
|||
|
|
### 2.1 数据库模型设计
|
|||
|
|
|
|||
|
|
#### PaymentOrder（支付订单表）
|
|||
|
|
**设计思路：**
|
|||
|
|
- 存储支付订单的完整信息
|
|||
|
|
- 支持订单状态跟踪
|
|||
|
|
- 通过merchantTransactionId保证唯一性
|
|||
|
|
|
|||
|
|
**关键字段：**
|
|||
|
|
- `merchantTransactionId`：商户订单号（唯一索引）
|
|||
|
|
- `transactionId`：PingPong交易流水号（回调时更新）
|
|||
|
|
- `status`：订单状态（PENDING/SUCCESS/FAILED/REVIEW/CANCELLED）
|
|||
|
|
- `token`：收银台token
|
|||
|
|
- `paymentUrl`：收银台地址
|
|||
|
|
|
|||
|
|
#### PaymentRecord（支付记录表）
|
|||
|
|
**设计思路：**
|
|||
|
|
- 记录所有支付相关操作
|
|||
|
|
- 用于对账和问题排查
|
|||
|
|
- 支持多种记录类型（CHECKOUT/CALLBACK/QUERY等）
|
|||
|
|
|
|||
|
|
**关键字段：**
|
|||
|
|
- `recordType`：记录类型
|
|||
|
|
- `requestData`：原始请求数据（JSON）
|
|||
|
|
- `responseData`：原始响应数据（JSON）
|
|||
|
|
|
|||
|
|
### 2.2 配置管理
|
|||
|
|
|
|||
|
|
#### PingPongProperties
|
|||
|
|
**设计思路：**
|
|||
|
|
- 使用Spring Boot的@ConfigurationProperties
|
|||
|
|
- 支持多环境配置（dev/prod）
|
|||
|
|
- 配置项包括：商户号、密钥、网关地址、环境模式等
|
|||
|
|
|
|||
|
|
**关键配置：**
|
|||
|
|
```properties
|
|||
|
|
pingpong.client-id=商户号
|
|||
|
|
pingpong.acc-id=店铺编号
|
|||
|
|
pingpong.secret=签名密钥
|
|||
|
|
pingpong.gateway=API网关地址
|
|||
|
|
pingpong.mode=环境模式（sandbox/test/build）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.3 签名服务（SignatureService）
|
|||
|
|
|
|||
|
|
#### 设计思路
|
|||
|
|
- 实现PingPong的签名算法
|
|||
|
|
- 支持MD5和SHA256
|
|||
|
|
- 自动筛选参与签名的参数
|
|||
|
|
- 提供签名生成和验证功能
|
|||
|
|
|
|||
|
|
#### 签名流程
|
|||
|
|
1. 筛选加签参数（根据SIGN_SCOPE）
|
|||
|
|
2. 按字典序排序
|
|||
|
|
3. 构建签名串：{secret}key1=val1&key2=val2...
|
|||
|
|
4. MD5/SHA256运算并转大写
|
|||
|
|
|
|||
|
|
#### 关键方法
|
|||
|
|
- `generateSign()`：生成签名
|
|||
|
|
- `verifySign()`：验证签名
|
|||
|
|
- `filterSignParams()`：筛选签名参数
|
|||
|
|
|
|||
|
|
### 2.4 支付服务（PingPongPayService）
|
|||
|
|
|
|||
|
|
#### 设计思路
|
|||
|
|
- 封装PingPong API调用
|
|||
|
|
- 自动处理签名生成
|
|||
|
|
- 验证响应签名
|
|||
|
|
- 使用RestClient进行HTTP请求
|
|||
|
|
|
|||
|
|
#### 关键方法
|
|||
|
|
- `checkout()`：创建支付订单
|
|||
|
|
- `buildRequestMap()`：构建请求参数
|
|||
|
|
|
|||
|
|
### 2.5 订单服务（PaymentOrderService）
|
|||
|
|
|
|||
|
|
#### 设计思路
|
|||
|
|
- 管理支付订单生命周期
|
|||
|
|
- 调用PingPong API
|
|||
|
|
- 保存订单和记录
|
|||
|
|
- 提供订单查询功能
|
|||
|
|
|
|||
|
|
#### 关键方法
|
|||
|
|
- `createPaymentOrder()`：创建支付订单
|
|||
|
|
- `findByMerchantTransactionId()`：查询订单
|
|||
|
|
- `updateOrderStatus()`：更新订单状态
|
|||
|
|
|
|||
|
|
### 2.6 回调服务（CallbackService）
|
|||
|
|
|
|||
|
|
#### 设计思路
|
|||
|
|
- 处理PingPong异步回调
|
|||
|
|
- 验证回调签名
|
|||
|
|
- 更新订单状态
|
|||
|
|
- 触发业务逻辑处理
|
|||
|
|
|
|||
|
|
#### 关键方法
|
|||
|
|
- `handleCallback()`：处理回调
|
|||
|
|
- `mapCallbackStatusToOrderStatus()`：状态映射
|
|||
|
|
- `handleBusinessLogic()`：业务逻辑处理
|
|||
|
|
|
|||
|
|
## 三、API接口设计
|
|||
|
|
|
|||
|
|
### 3.1 支付接口
|
|||
|
|
|
|||
|
|
#### POST /api/payment/checkout
|
|||
|
|
**功能：** 创建支付订单
|
|||
|
|
|
|||
|
|
**请求体：** CheckoutRequestDTO
|
|||
|
|
**响应：** 包含token和paymentUrl
|
|||
|
|
|
|||
|
|
#### GET /api/payment/order/{merchantTransactionId}
|
|||
|
|
**功能：** 查询订单状态
|
|||
|
|
|
|||
|
|
**响应：** 订单详细信息
|
|||
|
|
|
|||
|
|
#### GET /api/payment/checkout/page?token={token}
|
|||
|
|
**功能：** 获取收银台页面
|
|||
|
|
|
|||
|
|
**响应：** HTML页面（包含SDK初始化）
|
|||
|
|
|
|||
|
|
### 3.2 回调接口
|
|||
|
|
|
|||
|
|
#### POST /api/callback/pingpong
|
|||
|
|
**功能：** 接收PingPong回调通知
|
|||
|
|
|
|||
|
|
**请求体：** Map<String, Object>
|
|||
|
|
**响应：** 处理结果
|
|||
|
|
|
|||
|
|
#### GET /api/callback/result
|
|||
|
|
**功能：** 支付结果页面（用户重定向）
|
|||
|
|
|
|||
|
|
**参数：** merchantTransactionId, status, message
|
|||
|
|
|
|||
|
|
## 四、DTO设计
|
|||
|
|
|
|||
|
|
### 4.1 请求DTO
|
|||
|
|
|
|||
|
|
#### CheckoutRequestDTO
|
|||
|
|
- 包含所有checkout接口必需参数
|
|||
|
|
- 使用Jakarta Validation进行参数校验
|
|||
|
|
- 嵌套RiskInfoDTO
|
|||
|
|
|
|||
|
|
#### RiskInfoDTO
|
|||
|
|
- 包含风控相关信息
|
|||
|
|
- 嵌套多个子DTO（CustomerDTO、GoodsDTO等）
|
|||
|
|
|
|||
|
|
### 4.2 响应DTO
|
|||
|
|
|
|||
|
|
#### CheckoutResponseDTO
|
|||
|
|
- 对应PingPong API响应
|
|||
|
|
- 包含token、paymentUrl等
|
|||
|
|
|
|||
|
|
## 五、异常处理
|
|||
|
|
|
|||
|
|
### 5.1 GlobalExceptionHandler
|
|||
|
|
- 统一异常处理
|
|||
|
|
- 参数验证异常处理
|
|||
|
|
- 运行时异常处理
|
|||
|
|
- 返回统一错误格式
|
|||
|
|
|
|||
|
|
## 六、安全考虑
|
|||
|
|
|
|||
|
|
### 6.1 签名验证
|
|||
|
|
- 所有回调都进行签名验证
|
|||
|
|
- 防止数据篡改
|
|||
|
|
|
|||
|
|
### 6.2 订单号唯一性
|
|||
|
|
- 数据库唯一索引保证
|
|||
|
|
- 业务层检查重复
|
|||
|
|
|
|||
|
|
### 6.3 敏感信息
|
|||
|
|
- 密钥存储在配置文件中
|
|||
|
|
- 生产环境使用环境变量
|
|||
|
|
|
|||
|
|
## 七、扩展性设计
|
|||
|
|
|
|||
|
|
### 7.1 多支付平台支持
|
|||
|
|
- 可以扩展为支付平台抽象接口
|
|||
|
|
- 每个平台实现独立服务
|
|||
|
|
|
|||
|
|
### 7.2 预授权功能
|
|||
|
|
- 支持AUTH/CAPTURE/VOID
|
|||
|
|
- 通过paymentType区分
|
|||
|
|
|
|||
|
|
### 7.3 订单状态机
|
|||
|
|
- 可扩展为状态机模式
|
|||
|
|
- 支持更复杂的状态流转
|
|||
|
|
|
|||
|
|
## 八、最佳实践
|
|||
|
|
|
|||
|
|
### 8.1 日志记录
|
|||
|
|
- 关键操作记录日志
|
|||
|
|
- 包含订单号、状态等信息
|
|||
|
|
|
|||
|
|
### 8.2 事务管理
|
|||
|
|
- 订单创建和更新使用事务
|
|||
|
|
- 保证数据一致性
|
|||
|
|
|
|||
|
|
### 8.3 错误处理
|
|||
|
|
- 友好的错误提示
|
|||
|
|
- 详细的错误日志
|
|||
|
|
|
|||
|
|
### 8.4 配置管理
|
|||
|
|
- 多环境配置分离
|
|||
|
|
- 敏感信息加密
|
|||
|
|
|
|||
|
|
## 九、测试建议
|
|||
|
|
|
|||
|
|
### 9.1 单元测试
|
|||
|
|
- 签名服务测试
|
|||
|
|
- 服务层逻辑测试
|
|||
|
|
|
|||
|
|
### 9.2 集成测试
|
|||
|
|
- API接口测试
|
|||
|
|
- 回调处理测试
|
|||
|
|
|
|||
|
|
### 9.3 沙箱测试
|
|||
|
|
- 使用PingPong沙箱环境
|
|||
|
|
- 测试各种支付场景
|
|||
|
|
|
|||
|
|
## 十、部署注意事项
|
|||
|
|
|
|||
|
|
### 10.1 环境配置
|
|||
|
|
- 开发环境：使用sandbox模式
|
|||
|
|
- 生产环境：必须使用build模式
|
|||
|
|
|
|||
|
|
### 10.2 数据库
|
|||
|
|
- 生产环境使用连接池
|
|||
|
|
- 定期备份订单数据
|
|||
|
|
|
|||
|
|
### 10.3 监控
|
|||
|
|
- 监控API调用成功率
|
|||
|
|
- 监控回调处理情况
|
|||
|
|
- 监控订单状态分布
|
|||
|
|
|