# 支付模块项目说明

## 项目概述
基于DDD架构的支付模块，支持微信支付Native和支付宝当面付二维码支付。

## 技术栈
- Java 1.8
- Spring Boot 2.5.15
- MyBatis Plus 3.4.3.4
- MySQL
- ZXing (二维码生成)

## 项目结构

```
dryad-payment/
├── src/main/java/com/ruoyi/payment/
│   ├── PaymentApplication.java              # 启动类
│   ├── common/                              # 通用类
│   │   └── AjaxResult.java                 # 统一响应结果
│   ├── domain/                              # 领域层
│   │   ├── enums/                          # 枚举
│   │   │   ├── PayChannel.java             # 支付渠道
│   │   │   ├── OrderStatus.java            # 订单状态
│   │   │   ├── TransactionStatus.java      # 交易状态
│   │   │   └── ClientType.java             # 客户端类型
│   │   └── model/                          # 领域模型
│   │       ├── PaymentOrder.java           # 支付订单(聚合根)
│   │       ├── PaymentTransaction.java     # 支付交易
│   │       ├── NotifyLog.java              # 渠道回调日志
│   │       ├── BizCallbackLog.java         # 业务回调日志
│   │       └── OperationAudit.java         # 操作审计
│   ├── application/                         # 应用层
│   │   └── service/
│   │       └── PaymentService.java         # 支付应用服务
│   ├── infrastructure/                      # 基础设施层
│   │   ├── config/                         # 配置
│   │   │   ├── WechatPayConfig.java        # 微信支付配置
│   │   │   ├── AlipayConfig.java           # 支付宝配置
│   │   │   ├── BusinessCallbackConfig.java # 业务回调配置
│   │   │   └── QrCodeConfig.java           # 二维码配置
│   │   ├── persistence/                    # 持久化
│   │   │   └── mapper/                     # MyBatis Mapper
│   │   │       ├── PaymentOrderMapper.java
│   │   │       ├── PaymentTransactionMapper.java
│   │   │       ├── NotifyLogMapper.java
│   │   │       ├── BizCallbackLogMapper.java
│   │   │       └── OperationAuditMapper.java
│   │   └── util/                           # 工具类
│   │       ├── QrCodeUtil.java             # 二维码生成工具
│   │       └── SignUtil.java               # 签名工具
│   └── interfaces/                          # 接口层
│       ├── controller/                     # 控制器
│       │   ├── PaymentController.java      # 支付接口
│       │   └── PaymentNotifyController.java# 回调接口
│       └── dto/                            # 数据传输对象
│           ├── PaymentRequest.java         # 支付请求
│           └── PaymentResponse.java        # 支付响应
├── src/main/resources/
│   ├── application.yml                     # 配置文件
│   ├── mapper/                             # MyBatis XML
│   │   ├── PaymentOrderMapper.xml
│   │   └── PaymentTransactionMapper.xml
│   └── sql/
│       └── schema.sql                      # 数据库表结构
├── doc/
│   └── 设计方案.md                          # 详细设计文档
└── pom.xml                                  # Maven配置

```

## 已实现功能

### 1. 基础框架 ✅
- DDD分层架构
- Spring Boot项目配置
- MyBatis Plus集成
- 数据库表结构

### 2. 领域模型 ✅
- PaymentOrder (支付订单聚合根)
- PaymentTransaction (支付交易)
- NotifyLog (渠道回调日志)
- BizCallbackLog (业务回调日志)
- OperationAudit (操作审计)

### 3. 核心接口 ✅
- POST /api/pay/wechat/native - 发起微信Native支付
- POST /api/pay/alipay/precreate - 发起支付宝当面付
- GET /api/pay/orders/{orderId} - 查询订单
- GET /api/pay/orders/{orderId}/transactions/latest - 查询最新交易
- POST /api/pay/notify/wechat - 微信回调(框架)
- POST /api/pay/notify/alipay - 支付宝回调(框架)

### 4. 工具类 ✅
- 二维码生成(300×300 PNG Base64)
- MD5签名
- HMAC-SHA256签名

## 待完成功能

### 1. 渠道客户端实现 ⚠️
需要完善以下内容：
- `WxPayV2Client`: 微信v2统一下单、查询、关闭、签名验证
- `AlipayF2FClient`: 支付宝当面付下单、查询、关闭、签名验证

当前PaymentService中的 `callWechatUnifiedOrder()` 和 `callAlipayPrecreate()` 是模拟实现。

### 2. 回调处理完善 ⚠️
需要完善 PaymentNotifyController 中的TODO部分：
- 微信XML报文解析与签名验证
- 支付宝参数验证与签名验证
- 订单和交易状态更新逻辑
- 触发业务回调逻辑
- 记录NotifyLog实现幂等

### 3. 业务回调服务 📝
需要实现：
- `BizCallbackService`: 外部业务回调触发
- HMAC-SHA256签名生成
- HTTP POST调用
- 重试机制(0/1/5/15/60分钟)
- 记录BizCallbackLog

### 4. 每日对账任务 📝
需要实现：
- `ReconciliationTask`: @Scheduled定时任务
- 调用渠道查询接口对比状态
- 自动修复状态差异
- 生成对账报告

### 5. 订单过期处理 📝
需要实现：
- 定时任务检查过期订单
- 将超过2小时未支付的订单标记为EXPIRED

### 6. 管理端接口 📝
需要实现：
- 订单列表查询
- 交易流水查询
- 回调日志查询
- 手工重发业务回调
- 对账任务查询
- 操作审计记录

## 快速开始

### 1. 环境准备
- JDK 1.8
- MySQL 5.7+
- Maven 3.6+

### 2. 数据库初始化
```bash
# 执行SQL脚本创建数据库和表
mysql -u root -p < src/main/resources/sql/schema.sql
```

### 3. 配置修改
修改 `src/main/resources/application.yml`:
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/dryad_payment?...
    username: your_username
    password: your_password

payment:
  wechat:
    appId: your_wechat_appid
    mchId: your_wechat_mchid
    mchKey: your_wechat_mchkey
  
  alipay:
    appId: your_alipay_appid
    privateKey: your_alipay_private_key
    alipayPublicKey: alipay_public_key
```

### 4. 编译运行
```bash
# 编译
mvn clean package

# 运行
java -jar target/dryad-payment-1.0.0.jar

# 或直接运行
mvn spring-boot:run
```

### 5. 测试接口
```bash
# 发起微信Native支付
curl -X POST http://localhost:8080/api/pay/wechat/native \
  -H "Content-Type: application/json" \
  -d '{
    "bizOrderId": "TEST20251123001",
    "amount": 100,
    "subject": "测试订单",
    "description": "这是一个测试订单",
    "callbackUrl": "http://your-domain.com/callback"
  }'

# 查询订单
curl http://localhost:8080/api/pay/orders/1
```

## 核心业务逻辑

### 同一订单只允许一笔进行中的交易
在 `PaymentService` 中已实现：
```java
// 检查是否存在待支付交易
PaymentTransaction existingTransaction = 
    paymentTransactionMapper.selectPendingByOrderId(order.getId());
if (existingTransaction != null) {
    // 直接返回已有交易
    return buildPaymentResponse(order, existingTransaction);
}
```

### 订单2小时过期
创建订单时设置：
```java
order.setExpireAt(LocalDateTime.now().plusHours(2));
```

### 二维码Base64返回
使用ZXing生成300×300 PNG二维码并转换为Base64。

## 后续开发建议

1. **优先完成渠道客户端**: 这是核心功能，建议参考微信支付和支付宝官方SDK文档实现
2. **完善回调处理**: 实现签名验证和状态更新，确保数据一致性
3. **实现业务回调**: 确保外部系统能及时收到支付结果
4. **添加单元测试**: 对核心业务逻辑编写测试用例
5. **监控与告警**: 添加日志监控和异常告警

## 注意事项

1. 配置文件中的密钥需要妥善保管，不要提交到代码仓库
2. 生产环境需要配置HTTPS
3. 回调URL需要能公网访问
4. 建议使用Redis缓存订单和交易数据
5. 生产环境需要配置分布式锁防止并发创建交易

## 参考文档
- 详细设计方案: `doc/设计方案.md`
- 微信支付v2文档: https://pay.weixin.qq.com/wiki/doc/api/native.php
- 支付宝当面付文档: https://opendocs.alipay.com/open/194/105072

## 许可证
本项目仅供学习使用。