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

**关键配置：**
```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调用成功率
- 监控回调处理情况
- 监控订单状态分布