# 支付系统

**Repository Path**: xbcode-plugin/xbPay

## Basic Information

- **Project Name**: 支付系统
- **Description**: 通用的支付基础系统，所有支付都需要依赖该插件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-18
- **Last Updated**: 2026-05-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xbPay 支付引擎

基于模块化设计的通用支付引擎，采用驱动模式实现多种支付方式的统一管理。

## 架构设计

本插件采用主插件 + 子插件的架构模式，参考 xbSms 短信引擎的设计理念：

- **xbPay**: 主插件，提供支付引擎核心功能和统一接口
- **xbPayAlipay**: 支付宝支付子插件
- **xbPayWechat**: 微信支付子插件
- **xbPayBalance**: 余额支付子插件

## 核心组件

### 1. 服务抽象类 (service/Server.php)

定义支付驱动的标准接口，所有子插件必须实现以下方法：

- `pay()`: 创建支付订单
- `notify()`: 支付回调处理
- `query($orderNo)`: 查询订单状态
- `refund($orderNo, $amount, $refundNo)`: 退款处理

### 2. 驱动管理类 (service/Driver.php)

负责支付引擎的加载和实例化，支持动态切换不同的支付方式。

### 3. 支付引擎模型 (app/model/PayEngine.php)

用于管理和存储支付引擎的配置信息。

## 使用示例

### 基础用法

```php
use plugin\xbPay\service\Driver;

// 获取支付宝支付实例
$payment = Driver::instance('alipay');

// 设置支付参数
$result = $payment->setOrderNo('20240101000001')
    ->setAmount(99.99)
    ->setDescription('商品购买')
    ->setPlatform('h5')
    ->setNotifyUrl('https://example.com/notify')
    ->setReturnUrl('https://example.com/return')
    ->pay();

// 返回结果
// [
//     'pay_type' => 'redirect',
//     'pay_url' => 'https://...',
//     'order_no' => '20240101000001'
// ]
```

### 微信支付示例

```php
// 微信小程序支付
$payment = Driver::instance('wechat');

$result = $payment->setOrderNo('20240101000002')
    ->setAmount(88.88)
    ->setDescription('会员充值')
    ->setPlatform('weapp')
    ->setNotifyUrl('https://example.com/notify')
    ->setExtra(['openid' => 'oXXXXXXXXXXXXXXXX'])
    ->pay();

// 返回小程序支付参数
// [
//     'pay_type' => 'jsapi',
//     'pay_params' => [
//         'timeStamp' => '1234567890',
//         'nonceStr' => 'xxx',
//         'package' => 'prepay_id=xxx',
//         'signType' => 'MD5',
//         'paySign' => 'xxx'
//     ]
// ]
```

### 余额支付示例

```php
// 余额支付
$payment = Driver::instance('balance');

$result = $payment->setOrderNo('20240101000003')
    ->setAmount(50.00)
    ->setDescription('订单支付')
    ->setPlatform('h5')
    ->setExtra([
        'user_id' => 10001,
        'pay_password' => '123456'
    ])
    ->pay();

// 返回结果
// [
//     'pay_type' => 'balance',
//     'order_no' => '20240101000003',
//     'status' => 'success',
//     'balance' => 150.00
// ]
```

### 支付回调处理

```php
// 支付宝回调
$payment = Driver::instance('alipay');
try {
    $result = $payment->notify();
    // 处理业务逻辑
    // $result = [
    //     'order_no' => '20240101000001',
    //     'trade_no' => 'xxx',
    //     'total_amount' => '99.99',
    //     'trade_status' => 'TRADE_SUCCESS'
    // ]
    echo 'success';
} catch (\Exception $e) {
    echo 'fail';
}
```

### 订单查询

```php
$payment = Driver::instance('alipay');
$result = $payment->query('20240101000001');

// 返回结果
// [
//     'order_no' => '20240101000001',
//     'trade_no' => 'xxx',
//     'trade_status' => 'TRADE_SUCCESS',
//     'total_amount' => '99.99'
// ]
```

### 退款处理

```php
$payment = Driver::instance('wechat');
$result = $payment->refund(
    '20240101000002',  // 订单号
    88.88,             // 退款金额
    'R20240101000001'  // 退款单号
);

// 返回结果
// [
//     'order_no' => '20240101000002',
//     'refund_no' => 'R20240101000001',
//     'refund_amount' => 88.88,
//     'status' => 'success'
// ]
```

## 支付平台类型

系统支持以下支付平台类型：

- `weapp`: 微信小程序
- `wechat`: 微信公众号
- `h5`: 手机H5页面
- `pc_web`: 电脑网页支付
- `pc_scan`: 电脑扫码支付

不同的支付方式支持不同的平台：

| 支付方式 | weapp | wechat | h5 | pc_web | pc_scan |
|---------|-------|--------|-----|--------|---------|
| 支付宝  | ✓     | ✓      | ✓   | ✓      | ✓       |
| 微信    | ✓     | ✓      | ✓   | -      | ✓       |
| 余额    | ✓     | ✓      | ✓   | ✓      | ✓       |

## 配置说明

### 支付宝配置

- `app_id`: 支付宝应用ID
- `private_key`: 应用私钥（RSA2格式）
- `public_key`: 支付宝公钥（RSA2格式）
- `sandbox`: 是否使用沙箱环境

### 微信支付配置

- `app_id`: 微信应用ID
- `mch_id`: 微信商户号
- `api_key`: 微信支付API密钥
- `cert_path`: 证书路径（退款时需要）
- `key_path`: 证书密钥路径（退款时需要）

### 余额支付配置

- `enable`: 是否启用余额支付
- `need_pay_password`: 是否需要支付密码
- `min_amount`: 最小支付金额
- `max_amount`: 最大支付金额

## 扩展开发

如需添加新的支付方式，请按以下步骤操作：

1. 创建新的子插件，如 `xbPayXxx`
2. 在子插件中创建 `engine/Driver.php`，继承 `plugin\xbPay\service\Server`
3. 实现 `pay()`, `notify()`, `query()`, `refund()` 方法
4. 在 `config/payment.php` 中定义配置模板
5. 在 `plugins.json` 中声明对 `xbPay` 的依赖

## 设计原则

1. **模块化设计**: 每个支付方式独立成插件，互不干扰
2. **统一接口**: 所有支付方式实现相同的接口规范
3. **低耦合**: 主插件与子插件通过接口解耦
4. **易扩展**: 可随时添加新的支付方式
5. **配置分离**: 支付配置独立管理，便于维护

## 数据库表

### xb_pay_engine (支付引擎表)

存储已安装的支付引擎信息

| 字段 | 类型 | 说明 |
|-----|------|-----|
| id | int | 主键 |
| title | varchar(50) | 驱动名称 |
| plugin | varchar(50) | 插件标识 |
| engine | varchar(50) | 驱动标识 |
| sort | int | 排序 |

### xb_payment_config (支付配置表)

存储支付方式的配置信息

### xb_payment (支付方式表)

存储各平台启用的支付方式

## 版本信息

- 版本: 1.0.0
- 作者: 积木云
- 协议: Apache License 2.0