# Kylin Payment 文档索引

## 1. 模块介绍

Kylin Payment 是一个基于 Laravel 框架的支付模块，支持多种支付方式，如微信支付、支付宝支付、银联支付等，提供了统一的支付接口和管理功能。

## 2. 文档目录

### 2.1 基础文档

- [模块介绍](introduction.md) - Kylin Payment 模块的概述和核心功能
- [安装配置](installation.md) - Kylin Payment 的安装和配置方法

### 2.2 核心功能

- [支付方式](payment_methods.md) - 支持的支付方式及其使用方法
- [订单管理](order_management.md) - 支付订单的创建、查询、更新和删除
- [退款管理](refund_management.md) - 支付退款的申请、查询和管理
- [支付记录](payment_records.md) - 支付记录的创建、查询和分析
- [支付通知](payment_notifications.md) - 支付通知的处理和管理

## 3. 快速开始

### 3.1 安装

```bash
composer require kylin/payment
```

### 3.2 发布配置

```bash
php artisan vendor:publish --provider="Kylin\Payment\Providers\PaymentServiceProvider"
```

### 3.3 运行迁移

```bash
php artisan migrate
```

### 3.4 配置环境变量

在 `.env` 文件中配置支付相关环境变量：

```env
# 支付配置
PAYMENT_DEFAULT=wechat

# 微信支付配置
WECHAT_PAYMENT_APPID=your_wechat_appid
WECHAT_PAYMENT_MCH_ID=your_wechat_mch_id
WECHAT_PAYMENT_KEY=your_wechat_key
WECHAT_PAYMENT_CERT_PATH=path/to/cert.pem
WECHAT_PAYMENT_KEY_PATH=path/to/key.pem
WECHAT_PAYMENT_NOTIFY_URL=http://your-domain.com/payment/wechat/notify
WECHAT_PAYMENT_REFUND_NOTIFY_URL=http://your-domain.com/payment/wechat/refund-notify

# 支付宝支付配置
ALIPAY_APPID=your_alipay_appid
ALIPAY_PRIVATE_KEY=your_alipay_private_key
ALIPAY_PUBLIC_KEY=your_alipay_public_key
ALIPAY_NOTIFY_URL=http://your-domain.com/payment/alipay/notify
ALIPAY_RETURN_URL=http://your-domain.com/payment/alipay/return
ALIPAY_SANDBOX=false

# 银联支付配置
UNIONPAY_MER_ID=your_unionpay_mer_id
UNIONPAY_CERT_PATH=path/to/cert.pfx
UNIONPAY_CERT_PWD=your_cert_password
UNIONPAY_NOTIFY_URL=http://your-domain.com/payment/unionpay/notify
UNIONPAY_RETURN_URL=http://your-domain.com/payment/unionpay/return
UNIONPAY_SANDBOX=false
```

### 3.5 使用示例

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

// 创建支付订单
$order = Payment::create([
    'order_no' => '202401010001',
    'amount' => 100,
    'subject' => '测试商品',
    'body' => '测试商品描述',
    'method' => 'wechat',
    'extra' => [
        'openid' => 'openid123',
    ],
]);

// 发起支付
$paymentParams = Payment::pay($order['order_no']);

// 处理支付通知
$notification = Payment::handleNotification(function ($data) {
    // 处理支付通知
    return true;
});

// 申请退款
$refund = Payment::refund([
    'order_no' => '202401010001',
    'refund_no' => '20240101000101',
    'amount' => 50,
    'reason' => '商品质量问题',
]);
```

## 4. 核心功能

### 4.1 支付管理

- **多种支付方式**：支持微信支付、支付宝支付、银联支付等
- **统一接口**：提供统一的支付接口，简化支付集成
- **灵活配置**：支持支付方式的灵活配置

### 4.2 订单管理

- **订单创建**：创建支付订单
- **订单查询**：查询单个订单和订单列表
- **订单更新**：更新订单状态和信息
- **订单删除**：删除订单
- **订单过期处理**：自动处理过期订单
- **订单取消**：取消订单

### 4.3 退款管理

- **退款申请**：申请退款
- **退款查询**：查询单个退款和退款列表
- **退款处理**：处理退款申请
- **退款通知**：处理退款通知

### 4.4 支付记录

- **记录创建**：自动创建支付记录
- **记录查询**：查询单个记录和记录列表
- **记录分析**：统计支付数据和趋势
- **记录导出**：导出支付记录为 CSV 或 Excel 文件
- **记录清理**：清理过期的支付记录

### 4.5 支付通知

- **通知处理**：处理支付平台的异步通知
- **通知验证**：验证通知的签名和数据
- **通知响应**：返回正确的通知响应
- **通知重试**：处理通知重试

## 5. 常见问题

### 5.1 安装问题

- **配置文件不存在**：运行 `php artisan vendor:publish --provider="Kylin\Payment\Providers\PaymentServiceProvider"` 发布配置文件
- **数据库表不存在**：运行 `php artisan migrate` 运行数据库迁移
- **支付方式配置错误**：检查支付方式的配置信息是否正确

### 5.2 支付问题

- **支付失败**：检查支付方式配置是否正确，检查订单信息是否正确
- **支付通知未收到**：检查通知地址是否正确，检查服务器是否可以被访问
- **支付记录创建失败**：检查数据库连接是否正常，检查数据库表结构是否正确

### 5.3 退款问题

- **退款申请失败**：检查订单是否已支付，检查退款金额是否正确
- **退款处理中**：耐心等待支付平台处理
- **退款失败**：检查退款原因是否合理，检查支付平台的退款限制

### 5.4 通知问题

- **通知未收到**：检查通知地址是否正确，检查服务器是否可以被访问
- **通知验证失败**：检查签名验证逻辑是否正确，检查支付方式配置是否正确
- **通知处理失败**：检查业务逻辑是否正确，检查数据库操作是否成功

## 6. 最佳实践

1. **配置管理**：使用环境变量管理敏感配置，避免硬编码
2. **证书管理**：妥善保管支付证书，避免泄露
3. **日志记录**：记录支付相关的操作，便于排查问题
4. **错误处理**：捕获支付相关的异常，确保服务稳定
5. **安全验证**：验证支付通知的签名，确保通知的真实性
6. **订单管理**：定期清理过期订单，避免数据冗余
7. **退款管理**：妥善处理退款请求，确保资金安全
8. **通知处理**：实现通知的幂等性处理，避免重复处理
9. **数据统计**：定期分析支付数据，优化支付策略
10. **监控**：监控支付系统的运行状态，及时发现问题

## 7. 参考资源

- [Laravel 文档](https://laravel.com/docs)
- [微信支付文档](https://pay.weixin.qq.com/wiki/doc/api/index.html)
- [支付宝支付文档](https://opendocs.alipay.com/open/)
- [银联支付文档](https://open.unionpay.com/tjweb/apidoc)
- [Kylin Payment 文档](https://github.com/kylin-framework/payment)
