shop-back-end/doc/微信支付集成指南.md

# 微信支付集成指南

## 概述

本项目集成了微信支付功能，支持JSAPI支付、支付回调处理、退款等功能。支付网关采用第三方服务，简化了支付对接流程。

## 功能特性

- ✅ JSAPI支付（微信公众号支付）
- ✅ 支付回调处理
- ✅ 订单状态更新
- ✅ 退款功能
- ✅ 支付日志记录
- ✅ 支付状态查询

## 配置步骤

### 1. 微信支付配置

#### 1.1 获取支付配置

联系支付网关服务商获取以下配置：
- **AppId**: 微信公众号AppId
- **Secret**: 微信公众号Secret
- **BizId**: 支付业务ID
- **AppKey**: 支付密钥
- **PayUrl**: 支付接口地址
- **RefundUrl**: 退款接口地址

#### 1.2 系统配置

修改 `application-dev.yml` 配置文件：

```yaml
wxshop:
  appid: wx9922dfbb0d4cd7bb
  secret: 7c7ef0dbb90b6be2abc8c269357f980a
  pay:
    biz_id: wxshop
    old_biz_id: wxshop_old
    appkey: wxshop202503081132
    pay_url: http://222.218.10.217:7890/open/trade/wx/jsapi/precreate
    refund_url: http://222.218.10.217:7890/open/trade/refund
```

### 2. 数据库准备

#### 2.1 支付日志表

```sql
CREATE TABLE `payment_operation_log` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `order_no` varchar(64) NOT NULL COMMENT '订单号',
  `operation_type` varchar(50) NOT NULL COMMENT '操作类型',
  `request_data` text COMMENT '请求数据',
  `response_data` text COMMENT '响应数据',
  `status` tinyint DEFAULT '1' COMMENT '状态',
  `error_msg` varchar(500) DEFAULT NULL COMMENT '错误信息',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP,
  `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_order_no` (`order_no`)
);
```

## 核心功能

### 1. 创建支付订单

#### 1.1 支付请求

```bash
POST /payment/create
Content-Type: application/json

{
  "orderId": "2025030811320001",
  "amount": 99.99,
  "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
  "payType": "JSAPI",
  "subject": "商品订单",
  "body": "商品描述"
}
```

#### 1.2 支付响应

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "prepayId": "wx20250308113200abc123",
    "paySign": "BDF0099C9FF443C4DC5C5D68C4B97C3F",
    "timestamp": "1657794651",
    "nonceStr": "1657794651",
    "package": "prepay_id=wx20250308113200abc123"
  }
}
```

### 2. 支付回调

#### 2.1 回调接口

```
POST /payment/callback
Content-Type: application/xml
```

#### 2.2 回调数据示例

```xml
<xml>
  <appid><![CDATA[wx9922dfbb0d4cd7bb]]></appid>
  <bank_type><![CDATA[CFT]]></bank_type>
  <cash_fee><![CDATA[1]]></cash_fee>
  <fee_type><![CDATA[CNY]]></fee_type>
  <is_subscribe><![CDATA[N]]></is_subscribe>
  <mch_id><![CDATA[1600000000]]></mch_id>
  <nonce_str><![CDATA[1657794651]]></nonce_str>
  <openid><![CDATA[oUpF8uMuAJO_M2pxb1Q9zNjWeS6o]]></openid>
  <out_trade_no><![CDATA[2025030811320001]]></out_trade_no>
  <result_code><![CDATA[SUCCESS]]></result_code>
  <return_code><![CDATA[SUCCESS]]></return_code>
  <sign><![CDATA[BDF0099C9FF443C4DC5C5D68C4B97C3F]]></sign>
  <time_end><![CDATA[20140903131540]]></time_end>
  <total_fee>1</total_fee>
  <trade_type><![CDATA[JSAPI]]></trade_type>
  <transaction_id><![CDATA[1004400740201409030005092168]]></transaction_id>
</xml>
```

#### 2.3 回调响应

```xml
<xml>
  <return_code><![CDATA[SUCCESS]]></return_code>
  <return_msg><![CDATA[OK]]></return_msg>
</xml>
```

### 3. 退款功能

#### 3.1 退款请求

```bash
POST /payment/refund
Content-Type: application/json

{
  "orderNo": "2025030811320001",
  "refundAmount": 99.99,
  "refundReason": "用户申请退款",
  "refundNo": "REF2025030811320001"
}
```

#### 3.2 退款响应

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "refundId": "REF2025030811320001",
    "status": "PROCESSING",
    "refundTime": "2025-03-08 11:32:00"
  }
}
```

## 代码实现

### 1. 支付服务

```java
@Service
@RequiredArgsConstructor
public class PaymentService {

    private final PaymentGateway paymentGateway;
    private final PaymentOperationLogService logService;

    public WxJsApiPreCreateResponse createPayment(WxJsApiPreCreateRequest request) {
        // 记录请求日志
        PaymentOperationLog log = createRequestLog(request);

        try {
            // 调用支付网关
            WxJsApiPreCreateResponse response = paymentGateway.preCreate(request);

            // 记录响应日志
            updateResponseLog(log, response, true);

            return response;
        } catch (Exception e) {
            // 记录错误日志
            updateErrorLog(log, e.getMessage());
            throw new ApiException("支付创建失败: " + e.getMessage());
        }
    }
}
```

### 2. 支付网关

```java
@Component
public class PaymentGateway {

    @Value("${wxshop.pay.pay-url}")
    private String payUrl;

    @Value("${wxshop.pay.appkey}")
    private String appKey;

    public WxJsApiPreCreateResponse preCreate(WxJsApiPreCreateRequest request) {
        // 构建请求参数
        Map<String, String> params = buildParams(request);

        // 生成签名
        String sign = SignUtils.generateSign(params, appKey);
        params.put("sign", sign);

        // 发送请求
        String response = HttpUtil.post(payUrl, params);

        // 解析响应
        return parseResponse(response);
    }
}
```

### 3. 签名工具

```java
public class SignUtils {

    public static String generateSign(Map<String, String> params, String appKey) {
        // 参数排序
        List<String> keys = new ArrayList<>(params.keySet());
        Collections.sort(keys);

        // 拼接参数
        StringBuilder sb = new StringBuilder();
        for (String key : keys) {
            String value = params.get(key);
            if (value != null && !value.isEmpty()) {
                sb.append(key).append("=").append(value).append("&");
            }
        }
        sb.append("key=").append(appKey);

        // MD5加密
        return DigestUtils.md5Hex(sb.toString()).toUpperCase();
    }
}
```

## 支付流程

### 1. 支付创建流程

```mermaid
sequenceDiagram
    participant Client
    participant Backend
    participant PaymentGateway
    participant WeChat

    Client->>Backend: 创建支付订单
    Backend->>PaymentGateway: 预支付请求
    PaymentGateway->>WeChat: 统一下单
    WeChat-->>PaymentGateway: 返回预支付ID
    PaymentGateway-->>Backend: 返回支付参数
    Backend-->>Client: 返回前端支付参数
```

### 2. 支付回调流程

```mermaid
sequenceDiagram
    participant WeChat
    participant Backend
    participant Database

    WeChat->>Backend: 支付结果通知
    Backend->>Backend: 验证签名
    Backend->>Database: 更新订单状态
    Backend-->>WeChat: 返回成功响应
```

## 错误处理

### 1. 支付错误码

| 错误码 | 说明 | 处理建议 |
|-------|------|----------|
| `SYSTEMERROR` | 系统错误 | 重试操作 |
| `ORDERPAID` | 订单已支付 | 检查订单状态 |
| `OUT_TRADE_NO_USED` | 商户订单号重复 | 使用新订单号 |
| `NOTENOUGH` | 余额不足 | 提示用户 |
| `APPID_NOT_EXIST` | AppID不存在 | 检查配置 |

### 2. 异常处理

```java
@RestControllerAdvice
public class PaymentExceptionHandler {

    @ExceptionHandler(PaymentException.class)
    public ResponseDTO<Void> handlePaymentException(PaymentException e) {
        log.error("支付异常: {}", e.getMessage(), e);
        return ResponseDTO.fail(e.getCode(), e.getMessage());
    }

    @ExceptionHandler(Exception.class)
    public ResponseDTO<Void> handleException(Exception e) {
        log.error("系统异常: {}", e.getMessage(), e);
        return ResponseDTO.fail(500, "系统繁忙，请稍后重试");
    }
}
```

## 安全注意事项

### 1. 数据安全
- 支付密钥妥善保管
- 敏感数据传输使用HTTPS
- 支付回调验证签名
- 防止重复支付

### 2. 业务安全
- 订单金额校验
- 用户身份验证
- 防止SQL注入
- 日志记录完整

## 监控和日志

### 1. 监控指标
- 支付成功率
- 支付平均耗时
- 退款成功率
- 回调处理成功率

### 2. 日志记录
- 支付请求/响应日志
- 回调处理日志
- 错误日志
- 性能日志

## 测试建议

### 1. 单元测试
```java
@SpringBootTest
class PaymentServiceTest {

    @Autowired
    private PaymentService paymentService;

    @Test
    void testCreatePayment() {
        WxJsApiPreCreateRequest request = new WxJsApiPreCreateRequest();
        request.setOrderNo("TEST001");
        request.setAmount(new BigDecimal("0.01"));
        request.setOpenid("test_openid");

        WxJsApiPreCreateResponse response = paymentService.createPayment(request);

        assertNotNull(response);
        assertNotNull(response.getPrepayId());
    }
}
```

### 2. 集成测试
- 支付流程完整测试
- 回调处理测试
- 退款流程测试
- 异常场景测试

## 性能优化

### 1. 缓存优化
- 支付配置缓存
- 订单状态缓存
- 用户信息缓存

### 2. 异步处理
- 支付日志异步记录
- 通知消息异步发送
- 统计报表异步生成

### 3. 数据库优化
- 支付日志表分表
- 订单表索引优化
- 定期清理历史数据