pet-admin/ruoyi-catdog/README_REFUND.md

# 微信退款功能使用说明

## 功能概述

本项目已集成微信支付退款功能，当用户取消订单时，系统会自动申请微信退款。

## 主要组件

### 1. 微信退款工具类
- **文件位置**: `ruoyi-catdog/src/main/java/com/ruoyi/applet/utils/WechatRefundUtil.java`
- **功能**: 封装微信支付V3退款API，提供退款申请功能
- **主要方法**: `applyRefund(RefundRequest request)`

### 2. 取消订单接口（已集成退款功能）
- **文件位置**: `ruoyi-catdog/src/main/java/com/ruoyi/applet/contoller/ApiMallOrderController.java`
- **接口路径**: `POST /applet/mall/order/orderCancel`
- **功能**: 取消订单并自动申请退款

### 3. 退款回调接口
- **文件位置**: `ruoyi-catdog/src/main/java/com/ruoyi/applet/contoller/WechatRefundNotifyController.java`
- **接口路径**: `POST /no-auth/wechat/refund`
- **功能**: 处理微信退款通知

## 配置要求

### 1. 微信支付配置
确保在 `application.yml` 中正确配置了微信支付参数：

```yaml
wechat:
  enabled: true
  appId: your_app_id
  merchantId: your_merchant_id
  privateKeyPath: path/to/your/private_key.pem
  merchantSerialNumber: your_merchant_serial_number
  apiV3key: your_api_v3_key
  notifyUrl: https://your-domain.com/prod-api/no-auth/wechat/notify
```

### 2. 退款通知地址
在微信商户平台配置退款通知地址：
```
https://your-domain.com/prod-api/no-auth/wechat/refund
```

## 使用流程

### 1. 取消订单并申请退款
```http
POST /applet/mall/order/orderCancel
Content-Type: application/json

{
  "id": 123456,
  "remark": "用户取消订单"
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "订单取消成功，退款申请已提交：退款申请成功，退款单号：REFUND_1234567890"
}
```

### 2. 退款流程
1. 用户调用取消订单接口
2. 系统取消订单状态
3. 检查订单是否已支付
4. 如果已支付，自动申请微信退款
5. 记录退款历史
6. 微信异步通知退款结果

## 退款状态说明

- **SUCCESS**: 退款成功
- **CLOSED**: 退款关闭
- **PROCESSING**: 退款处理中
- **ABNORMAL**: 退款异常

## 注意事项

### 1. 签名验证
- 退款工具类使用项目中已有的 `WechatPayUtil` 进行签名
- 确保私钥文件路径正确且可访问

### 2. 金额单位
- 微信支付API使用分为单位
- 系统自动将元转换为分

### 3. 退款限制
- 只能对已支付的订单申请退款
- 退款金额不能超过原订单金额
- 部分退款需要特殊处理

### 4. 错误处理
- 网络异常会自动重试
- 签名失败会记录详细日志
- 退款失败会返回具体错误信息

## 扩展功能

### 1. 部分退款
如需支持部分退款，可以修改 `applyWechatRefund` 方法：

```java
// 设置部分退款金额
amountReq.refund = partialRefundAmount.multiply(new BigDecimal(100)).longValue();
```

### 2. 退款查询
可以添加退款查询接口：

```java
@GetMapping("/refund/query/{refundNo}")
public AjaxResult queryRefund(@PathVariable String refundNo) {
    // 实现退款查询逻辑
}
```

### 3. 退款统计
可以添加退款统计功能：

```java
@GetMapping("/refund/statistics")
public AjaxResult getRefundStatistics() {
    // 实现退款统计逻辑
}
```

## 测试建议

### 1. 沙箱环境测试
- 使用微信支付沙箱环境进行测试
- 验证退款申请和回调功能

### 2. 日志监控
- 监控退款申请日志
- 监控退款回调日志
- 设置告警机制

### 3. 异常测试
- 测试网络异常情况
- 测试签名失败情况
- 测试金额超限情况

## 常见问题

### Q1: 退款申请失败怎么办？
A1: 检查以下几点：
- 微信支付配置是否正确
- 私钥文件是否存在且可读
- 订单状态是否为已支付
- 网络连接是否正常

### Q2: 退款回调没有收到怎么办？
A2: 检查以下几点：
- 退款通知地址是否正确配置
- 服务器防火墙是否开放相应端口
- 回调接口是否正常响应

### Q3: 如何查看退款历史？
A3: 退款历史记录在 `oms_wechat_payment_history` 表中，可以通过以下方式查询：
- 通过订单ID查询
- 通过退款单号查询
- 通过交易类型（opType=3）查询

## 技术支持

如有问题，请联系开发团队或查看相关日志文件。