# Kylin Payment 支付记录

## 1. 支付记录概述

Kylin Payment 提供了完善的支付记录功能，记录支付的详细信息和状态，便于后续的查询和分析。

## 2. 记录创建

### 2.1 自动创建

当发生支付相关操作时，系统会自动创建支付记录：

- **订单创建**：创建订单时，生成订单创建记录
- **支付发起**：发起支付时，生成支付发起记录
- **支付成功**：支付成功时，生成支付成功记录
- **支付失败**：支付失败时，生成支付失败记录
- **退款申请**：申请退款时，生成退款申请记录
- **退款成功**：退款成功时，生成退款成功记录
- **退款失败**：退款失败时，生成退款失败记录

### 2.2 手动创建

使用 `Payment::record()` 方法手动创建支付记录：

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

$result = Payment::record([
    'order_no' => '202401010001', // 订单号
    'action' => 'custom', // 操作类型
    'amount' => 100, // 金额
    'status' => 'success', // 操作状态
    'message' => '自定义操作', // 操作信息
    'data' => ['key' => 'value'], // 操作数据
]);
```

## 3. 记录查询

### 3.1 查询单个记录

使用 `Payment::queryRecord()` 方法查询单个支付记录：

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

$record = Payment::queryRecord(1);
```

### 3.2 查询记录列表

使用 `Payment::queryRecordList()` 方法查询支付记录列表：

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

$records = Payment::queryRecordList([
    'order_no' => '202401010001', // 订单号
    'action' => 'pay', // 操作类型
    'status' => 'success', // 操作状态
    'start_time' => '2024-01-01', // 开始时间
    'end_time' => '2024-01-31', // 结束时间
    'page' => 1, // 页码
    'page_size' => 10, // 每页数量
]);
```

### 3.3 操作类型

| 操作类型 | 描述 |
|---------|------|
| create | 订单创建 |
| pay | 支付发起 |
| pay_success | 支付成功 |
| pay_failed | 支付失败 |
| refund | 退款申请 |
| refund_success | 退款成功 |
| refund_failed | 退款失败 |
| custom | 自定义操作 |

### 3.4 操作状态

| 操作状态 | 描述 |
|---------|------|
| success | 操作成功 |
| failed | 操作失败 |
| processing | 处理中 |

## 4. 记录分析

### 4.1 支付统计

使用 `Payment::stats()` 方法获取支付统计信息：

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

$stats = Payment::stats([
    'start_time' => '2024-01-01', // 开始时间
    'end_time' => '2024-01-31', // 结束时间
    'method' => 'wechat', // 支付方式
]);
```

### 4.2 统计结果

```php
[
    'total_orders' => 100, // 总订单数
    'total_amount' => 10000, // 总金额
    'success_orders' => 90, // 成功订单数
    'success_amount' => 9000, // 成功金额
    'failed_orders' => 10, // 失败订单数
    'failed_amount' => 1000, // 失败金额
    'refund_orders' => 5, // 退款订单数
    'refund_amount' => 500, // 退款金额
    'success_rate' => 90, // 成功率
    'average_amount' => 100, // 平均金额
]
```

### 4.3 支付趋势

使用 `Payment::trend()` 方法获取支付趋势信息：

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

$trend = Payment::trend([
    'start_time' => '2024-01-01', // 开始时间
    'end_time' => '2024-01-31', // 结束时间
    'interval' => 'day', // 时间间隔：day、week、month
    'method' => 'wechat', // 支付方式
]);
```

### 4.4 趋势结果

```php
[
    'labels' => ['2024-01-01', '2024-01-02', '2024-01-03'], // 时间标签
    'datasets' => [
        [
            'label' => '订单数',
            'data' => [10, 15, 20], // 订单数据
        ],
        [
            'label' => '金额',
            'data' => [1000, 1500, 2000], // 金额数据
        ],
    ],
]
```

## 5. 记录导出

### 5.1 导出 CSV

使用 `Payment::exportCsv()` 方法导出支付记录为 CSV 文件：

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

$filePath = Payment::exportCsv([
    'start_time' => '2024-01-01', // 开始时间
    'end_time' => '2024-01-31', // 结束时间
    'method' => 'wechat', // 支付方式
]);
```

### 5.2 导出 Excel

使用 `Payment::exportExcel()` 方法导出支付记录为 Excel 文件：

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

$filePath = Payment::exportExcel([
    'start_time' => '2024-01-01', // 开始时间
    'end_time' => '2024-01-31', // 结束时间
    'method' => 'wechat', // 支付方式
]);
```

## 6. 记录清理

### 6.1 自动清理

系统会自动清理过期的支付记录：

```php
// 在配置文件中设置记录保留时间
'record' => [
    'keep_days' => 90, // 记录保留时间（天）
],
```

### 6.2 手动清理

使用 `Payment::cleanRecords()` 方法手动清理支付记录：

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

$result = Payment::cleanRecords(90); // 清理90天前的记录
```

## 7. 常见问题

### 7.1 记录创建失败

**问题**：记录创建失败
**解决方案**：
1. 检查记录参数是否正确
2. 检查数据库连接是否正常
3. 检查数据库表结构是否正确

### 7.2 记录查询失败

**问题**：记录查询失败
**解决方案**：
1. 检查查询条件是否正确
2. 检查数据库连接是否正常
3. 检查记录是否存在

### 7.3 记录统计错误

**问题**：记录统计错误
**解决方案**：
1. 检查统计条件是否正确
2. 检查数据库连接是否正常
3. 检查记录数据是否完整

### 7.4 记录导出失败

**问题**：记录导出失败
**解决方案**：
1. 检查导出条件是否正确
2. 检查文件权限是否正确
3. 检查磁盘空间是否足够

### 7.5 记录清理失败

**问题**：记录清理失败
**解决方案**：
1. 检查清理条件是否正确
2. 检查数据库连接是否正常
3. 检查数据库权限是否正确

## 8. 最佳实践

1. **记录完整性**：确保支付记录的完整性，记录每一步操作
2. **记录准确性**：确保支付记录的准确性，避免记录错误
3. **记录安全性**：确保支付记录的安全性，防止记录被篡改
4. **记录分析**：定期分析支付记录，优化支付策略
5. **记录导出**：定期导出支付记录，备份数据
6. **记录清理**：定期清理过期的支付记录，提高系统性能
7. **记录监控**：监控支付记录的异常情况，及时处理问题

## 9. 总结

Kylin Payment 提供了完善的支付记录功能，记录支付的详细信息和状态，便于后续的查询和分析。通过合理的支付记录管理，可以提高支付的安全性和可靠性，优化支付策略，提高用户满意度。
