MTKJPAY/mt-pay/ARCHITECTURE.md

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）
• 配置项包括：商户号、密钥、网关地址、环境模式等

关键配置：

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调用成功率
• 监控回调处理情况
• 监控订单状态分布