feat(pay): 集成PingPong支付功能并完善配置体系

- 添加MyBatis-Plus和Druid数据源依赖 - 配置多环境数据库连接（dev/test/prod） - 实现PingPong支付核心功能模块 - 添加支付订单和记录表结构设计 - 集成MD5/SHA256签名算法及验证机制 - 支持支付回调处理和状态更新 - 添加预授权支付类型支持（AUTH/CAPTURE/VOID） - 实现收银台页面集成和跳转逻辑 - 添加完整的API接口文档和使用说明 - 配置Druid监控和安全管理 - 实现多环境配置文件分离管理 - 添加详细的架构设计和开发文档
2025-12-18 17:40:15 +08:00
parent 7b9045a813
commit 57062efd2d
10 changed files with 1075 additions and 1 deletions
--- a/mt-pay/ARCHITECTURE.md
+++ b/mt-pay/ARCHITECTURE.md
@@ -0,0 +1,275 @@
+# 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调用成功率
+- 监控回调处理情况
+- 监控订单状态分布
+