MTKJPAY/mt-pay/SERVICE_STRUCTURE.md

# Service层结构说明

## 目录结构

```
service/
├── SignatureService.java          # 签名服务接口
├── PingPongPayService.java        # PingPong支付服务接口
├── PaymentOrderService.java       # 支付订单服务接口
├── CallbackService.java           # 回调处理服务接口
└── impl/                          # 实现类目录
    ├── SignatureServiceImpl.java      # 签名服务实现类
    ├── PingPongPayServiceImpl.java    # PingPong支付服务实现类
    ├── PaymentOrderServiceImpl.java   # 支付订单服务实现类
    └── CallbackServiceImpl.java       # 回调处理服务实现类
```

## 设计原则

### 1. 接口与实现分离
- **service文件夹**：只存放接口文件
- **service/impl文件夹**：存放所有实现类

### 2. 命名规范
- 接口：`XxxService`
- 实现类：`XxxServiceImpl`

### 3. 依赖注入
- Controller层注入接口，不直接依赖实现类
- Spring会自动根据接口找到对应的实现类（通过@Service注解）

## Service接口说明

### SignatureService
**功能**：签名生成和验证服务

**方法**：
- `generateSign(Map<String, Object> params)` - 生成签名
- `generateSign(Map<String, Object> params, String secret, String signType)` - 生成签名（指定密钥和类型）
- `verifySign(Map<String, Object> params)` - 验证签名

### PingPongPayService
**功能**：PingPong支付API调用服务

**方法**：
- `checkout(CheckoutRequestDTO request)` - 创建支付订单

### PaymentOrderService
**功能**：支付订单业务服务

**方法**：
- `createPaymentOrder(CheckoutRequestDTO request)` - 创建支付订单
- `findByMerchantTransactionId(String merchantTransactionId)` - 根据商户订单号查询
- `findByTransactionId(String transactionId)` - 根据PingPong交易流水号查询
- `updateOrderStatus(String merchantTransactionId, String status, String transactionId)` - 更新订单状态

### CallbackService
**功能**：回调处理服务

**方法**：
- `handleCallback(Map<String, Object> callbackData)` - 处理支付回调

## 实现类说明

### SignatureServiceImpl
- 实现签名生成和验证逻辑
- 支持MD5和SHA256签名算法
- 自动筛选参与签名的参数

### PingPongPayServiceImpl
- 实现PingPong API调用
- 自动生成请求签名
- 验证响应签名

### PaymentOrderServiceImpl
- 实现支付订单业务逻辑
- 调用PingPong API创建订单
- 保存订单和支付记录

### CallbackServiceImpl
- 实现回调处理逻辑
- 验证回调签名
- 更新订单状态
- 保存回调记录

## 使用示例

### Controller中使用Service

```java
@RestController
@RequiredArgsConstructor
public class PaymentController {
    // 注入接口，Spring会自动找到对应的实现类
    private final PaymentOrderService paymentOrderService;
    
    @PostMapping("/checkout")
    public ResponseEntity<?> checkout(@RequestBody CheckoutRequestDTO request) {
        PaymentOrder order = paymentOrderService.createPaymentOrder(request);
        return ResponseEntity.ok(order);
    }
}
```

### Service实现类中注入其他Service

```java
@Service
@RequiredArgsConstructor
public class PaymentOrderServiceImpl implements PaymentOrderService {
    // 注入其他Service接口
    private final PingPongPayService pingPongPayService;
    
    // 实现接口方法
    @Override
    public PaymentOrder createPaymentOrder(CheckoutRequestDTO request) {
        // 实现逻辑
    }
}
```

## 优势

1. **解耦**：Controller只依赖接口，不依赖具体实现
2. **扩展性**：可以轻松替换实现类，不影响调用方
3. **测试**：可以方便地创建Mock实现进行单元测试
4. **规范**：统一的代码结构，便于维护

## 注意事项

1. 所有Service实现类必须使用`@Service`注解
2. 实现类必须实现对应的接口
3. Controller中注入的是接口类型，不是实现类
4. 如果接口有多个实现类，需要使用`@Qualifier`指定