# Kylin Payment 订单管理

## 1. 订单管理概述

Kylin Payment 提供了完善的订单管理功能，支持订单的创建、查询、更新和删除等操作。

## 2. 订单创建

### 2.1 创建订单

使用 `Payment::create()` 方法创建支付订单：

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

$order = Payment::create([
    'order_no' => '202401010001', // 订单号
    'amount' => 100, // 订单金额
    'subject' => '测试商品', // 订单主题
    'body' => '测试商品描述', // 订单描述
    'method' => 'wechat', // 支付方式
    'extra' => [ // 额外信息
        'openid' => 'openid123', // 微信支付需要
        'trade_type' => 'JSAPI', // 支付类型
    ],
]);
```

### 2.2 订单参数

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| order_no | string | 是 | 订单号，唯一标识 |
| amount | decimal | 是 | 订单金额，单位：元 |
| subject | string | 是 | 订单主题 |
| body | string | 是 | 订单描述 |
| method | string | 是 | 支付方式，如：wechat、alipay、unionpay |
| extra | array | 否 | 额外信息，根据支付方式不同而不同 |

### 2.3 订单创建结果

```php
[
    'order_no' => '202401010001',
    'amount' => 100,
    'subject' => '测试商品',
    'body' => '测试商品描述',
    'method' => 'wechat',
    'status' => 'pending',
    'created_at' => '2024-01-01 00:00:00',
    'expired_at' => '2024-01-01 00:30:00',
]
```

## 3. 订单查询

### 3.1 查询单个订单

使用 `Payment::query()` 方法查询单个订单：

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

$order = Payment::query('202401010001');
```

### 3.2 查询订单列表

使用 `Payment::queryList()` 方法查询订单列表：

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

$orders = Payment::queryList([
    'status' => 'success', // 订单状态
    'method' => 'wechat', // 支付方式
    'start_time' => '2024-01-01', // 开始时间
    'end_time' => '2024-01-31', // 结束时间
    'page' => 1, // 页码
    'page_size' => 10, // 每页数量
]);
```

### 3.3 订单状态

| 状态 | 描述 |
|------|------|
| pending | 待支付 |
| processing | 处理中 |
| success | 支付成功 |
| failed | 支付失败 |
| expired | 订单过期 |
| cancelled | 订单取消 |

## 4. 订单更新

### 4.1 更新订单状态

使用 `Payment::update()` 方法更新订单状态：

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

$result = Payment::update('202401010001', [
    'status' => 'success',
    'transaction_id' => 'wechat_transaction_id',
]);
```

### 4.2 更新订单信息

使用 `Payment::update()` 方法更新订单信息：

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

$result = Payment::update('202401010001', [
    'subject' => '更新后的商品',
    'body' => '更新后的商品描述',
]);
```

## 5. 订单删除

使用 `Payment::delete()` 方法删除订单：

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

$result = Payment::delete('202401010001');
```

## 6. 订单过期处理

### 6.1 自动过期

系统会自动将超过过期时间的订单标记为过期状态：

```php
// 在配置文件中设置订单过期时间
'order' => [
    'expire' => 30, // 订单过期时间（分钟）
],
```

### 6.2 手动处理

使用 `Payment::expire()` 方法手动处理过期订单：

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

$result = Payment::expire('202401010001');
```

## 7. 订单取消

使用 `Payment::cancel()` 方法取消订单：

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

$result = Payment::cancel('202401010001');
```

## 8. 订单事件

### 8.1 订单创建事件

当创建订单时，会触发 `PaymentCreated` 事件：

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

Event::listen(PaymentCreated::class, function (PaymentCreated $event) {
    $order = $event->order;
    // 处理订单创建事件
});
```

### 8.2 订单支付成功事件

当订单支付成功时，会触发 `PaymentSuccess` 事件：

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

Event::listen(PaymentSuccess::class, function (PaymentSuccess $event) {
    $order = $event->order;
    // 处理订单支付成功事件
});
```

### 8.3 订单支付失败事件

当订单支付失败时，会触发 `PaymentFailed` 事件：

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

Event::listen(PaymentFailed::class, function (PaymentFailed $event) {
    $order = $event->order;
    $message = $event->message;
    // 处理订单支付失败事件
});
```

## 9. 常见问题

### 9.1 订单创建失败

**问题**：订单创建失败
**解决方案**：
1. 检查订单参数是否正确
2. 检查订单号是否重复
3. 检查支付方式是否配置正确

### 9.2 订单查询失败

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

### 9.3 订单更新失败

**问题**：订单更新失败
**解决方案**：
1. 检查订单是否存在
2. 检查订单状态是否允许更新
3. 检查更新参数是否正确

### 9.4 订单过期

**问题**：订单过期
**解决方案**：
1. 检查订单过期时间设置是否合理
2. 提醒用户及时支付
3. 提供订单重新支付的功能

### 9.5 订单取消

**问题**：订单取消
**解决方案**：
1. 检查订单状态是否允许取消
2. 处理取消后的业务逻辑
3. 通知用户订单已取消

## 10. 最佳实践

1. **订单号生成**：使用唯一的订单号生成规则，避免重复
2. **订单验证**：在创建订单时验证订单参数的合法性
3. **订单状态管理**：合理管理订单状态，确保状态转换的正确性
4. **订单过期处理**：及时处理过期订单，避免数据冗余
5. **订单日志**：记录订单的每一步操作，便于排查问题
6. **订单通知**：及时通知用户订单状态的变化
7. **订单安全**：确保订单数据的安全性，防止篡改

## 11. 总结

Kylin Payment 提供了完善的订单管理功能，支持订单的创建、查询、更新和删除等操作。通过合理的订单管理，可以提高支付的成功率和用户体验，确保交易的安全性和可靠性。
