# Kylin Payment 退款管理

## 1. 退款管理概述

Kylin Payment 提供了完善的退款管理功能，支持退款的申请、查询和管理等操作。

## 2. 退款申请

### 2.1 申请退款

使用 `Payment::refund()` 方法申请退款：

```php
use Kylin\Payment\Facades\Payment;

$refund = Payment::refund([
    'order_no' => '202401010001', // 订单号
    'refund_no' => '20240101000101', // 退款单号
    'amount' => 50, // 退款金额
    'reason' => '商品质量问题', // 退款原因
]);
```

### 2.2 退款参数

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| order_no | string | 是 | 订单号 |
| refund_no | string | 是 | 退款单号，唯一标识 |
| amount | decimal | 是 | 退款金额，单位：元 |
| reason | string | 否 | 退款原因 |

### 2.3 退款申请结果

```php
[
    'refund_no' => '20240101000101',
    'order_no' => '202401010001',
    'amount' => 50,
    'status' => 'pending',
    'reason' => '商品质量问题',
    'created_at' => '2024-01-01 00:00:00',
]
```

## 3. 退款查询

### 3.1 查询单个退款

使用 `Payment::queryRefund()` 方法查询单个退款：

```php
use Kylin\Payment\Facades\Payment;

$refund = Payment::queryRefund('20240101000101');
```

### 3.2 查询退款列表

使用 `Payment::queryRefundList()` 方法查询退款列表：

```php
use Kylin\Payment\Facades\Payment;

$refunds = Payment::queryRefundList([
    'order_no' => '202401010001', // 订单号
    'status' => 'success', // 退款状态
    'start_time' => '2024-01-01', // 开始时间
    'end_time' => '2024-01-31', // 结束时间
    'page' => 1, // 页码
    'page_size' => 10, // 每页数量
]);
```

### 3.3 退款状态

| 状态 | 描述 |
|------|------|
| pending | 待处理 |
| processing | 处理中 |
| success | 退款成功 |
| failed | 退款失败 |

## 4. 退款处理

### 4.1 退款处理逻辑

1. **验证退款申请**：验证退款申请的合法性
2. **调用支付平台**：调用支付平台的退款接口
3. **更新退款状态**：根据支付平台的响应更新退款状态
4. **记录退款信息**：记录退款的详细信息
5. **通知用户**：通知用户退款结果

### 4.2 退款通知

当退款状态发生变化时，会触发退款通知：

```php
use Kylin\Payment\Events\RefundUpdated;

Event::listen(RefundUpdated::class, function (RefundUpdated $event) {
    $refund = $event->refund;
    // 处理退款通知
});
```

## 5. 退款限制

### 5.1 微信支付退款限制

- 退款金额不能超过原订单金额
- 退款只能在订单支付成功后发起
- 退款申请时间不能超过订单支付时间的1年
- 部分退款时，退款金额不能超过剩余可退金额

### 5.2 支付宝退款限制

- 退款金额不能超过原订单金额
- 退款只能在订单支付成功后发起
- 退款申请时间不能超过订单支付时间的1年
- 部分退款时，退款金额不能超过剩余可退金额

### 5.3 银联支付退款限制

- 退款金额不能超过原订单金额
- 退款只能在订单支付成功后发起
- 退款申请时间不能超过订单支付时间的180天
- 部分退款时，退款金额不能超过剩余可退金额

## 6. 退款记录

### 6.1 退款记录查询

使用 `Payment::queryRefundRecord()` 方法查询退款记录：

```php
use Kylin\Payment\Facades\Payment;

$records = Payment::queryRefundRecord('20240101000101');
```

### 6.2 退款记录内容

| 字段 | 描述 |
|------|------|
| id | 记录ID |
| refund_no | 退款单号 |
| action | 操作类型 |
| amount | 金额 |
| status | 操作状态 |
| message | 操作信息 |
| data | 操作数据 |
| created_at | 创建时间 |

## 7. 常见问题

### 7.1 退款申请失败

**问题**：退款申请失败
**解决方案**：
1. 检查订单是否已支付
2. 检查退款金额是否正确
3. 检查退款单号是否重复
4. 检查支付平台是否支持退款

### 7.2 退款处理中

**问题**：退款处理中
**解决方案**：
1. 耐心等待支付平台处理
2. 检查支付平台的退款处理时间
3. 联系支付平台客服

### 7.3 退款失败

**问题**：退款失败
**解决方案**：
1. 检查退款原因是否合理
2. 检查支付平台的退款限制
3. 联系支付平台客服

### 7.4 退款到账时间

**问题**：退款到账时间
**解决方案**：
1. 微信支付：1-3个工作日
2. 支付宝支付：1-3个工作日
3. 银联支付：1-7个工作日

### 7.5 部分退款

**问题**：部分退款
**解决方案**：
1. 多次发起部分退款
2. 确保退款总金额不超过原订单金额
3. 记录每次退款的详细信息

## 8. 最佳实践

1. **退款单号生成**：使用唯一的退款单号生成规则，避免重复
2. **退款验证**：在申请退款时验证退款参数的合法性
3. **退款状态管理**：合理管理退款状态，确保状态转换的正确性
4. **退款记录**：记录退款的每一步操作，便于排查问题
5. **退款通知**：及时通知用户退款结果
6. **退款安全**：确保退款数据的安全性，防止篡改
7. **退款策略**：制定合理的退款策略，提高用户满意度

## 9. 总结

Kylin Payment 提供了完善的退款管理功能，支持退款的申请、查询和管理等操作。通过合理的退款管理，可以提高用户满意度，确保交易的公平性和可靠性。
