支付系统

MineShop 的支付系统支持多种支付方式，包括微信支付、余额支付等，并提供完善的退款和对账功能。

🎯 系统架构

┌─────────────────────────────────────────────────────────────┐
│                      支付网关层                               │
│                   PaymentGateway                             │
├─────────────────────────────────────────────────────────────┤
│   微信支付        │   余额支付        │   其他支付            │
│   WechatPay      │   BalancePay     │   ...                │
├─────────────────────────────────────────────────────────────┤
│                      支付记录                                 │
│                   PaymentRecord                              │
└─────────────────────────────────────────────────────────────┘

✨ 核心特性

1. 支付方式

方式	说明	配置项
微信支付	微信 JSAPI/Native/H5	wechat_enabled, wechat_config
余额支付	用户账户余额	balance_enabled, balance_config

2. 支付配置

// PaymentSetting 值对象
public function __construct(
    public readonly bool $wechatEnabled,      // 微信支付开关
    public readonly array $wechatConfig,      // 微信支付配置
    public readonly bool $refundReview,       // 退款需审核
    public readonly int $settlementCycleDays, // 结算周期（天）
    public readonly bool $balanceEnabled,     // 余额支付开关
    public readonly array $balanceConfig,     // 余额支付配置
) {}

3. 支付流程

┌──────────┐    创建订单    ┌──────────┐    发起支付    ┌──────────┐
│  选择商品 │ ───────────→ │  待支付   │ ───────────→ │  支付中   │
└──────────┘              └──────────┘              └──────────┘
                                                         │
                               ┌─────────────────────────┤
                               │                         │
                               ↓                         ↓
                         ┌──────────┐             ┌──────────┐
                         │  支付成功 │             │  支付失败 │
                         └──────────┘             └──────────┘

🔄 退款流程

┌──────────┐    申请退款    ┌──────────┐    审核通过    ┌──────────┐
│  已支付   │ ───────────→ │  退款审核 │ ───────────→ │  退款中   │
└──────────┘              └──────────┘              └──────────┘
                                │                        │
                                │ 审核拒绝                │ 退款完成
                                ↓                        ↓
                          ┌──────────┐             ┌──────────┐
                          │  退款拒绝 │             │  已退款   │
                          └──────────┘             └──────────┘

📦 支付回调处理

// 支付成功回调
public function handlePaymentSuccess(string $orderNo, array $paymentData): void
{
    $order = $this->orderRepository->findByOrderNo($orderNo);
    
    if (!$order || $order->isPaid()) {
        return;
    }
    
    // 更新订单状态
    $order->markAsPaid($paymentData);
    
    // 记录支付流水
    $this->paymentRecordRepository->create([
        'order_id' => $order->id,
        'payment_no' => $paymentData['transaction_id'],
        'amount' => $paymentData['amount'],
        'payment_method' => $paymentData['method'],
        'paid_at' => now(),
    ]);
    
    // 触发支付成功事件
    event(new OrderPaidEvent($order));
}

💻 API 接口

后台管理

接口	方法	说明
/admin/payment/records	GET	支付记录列表
/admin/payment/refunds	GET	退款申请列表
/admin/payment/refund/{id}/approve	POST	审核通过
/admin/payment/refund/{id}/reject	POST	审核拒绝
/admin/payment/stats	GET	支付统计

前端 API

接口	方法	说明
/api/payment/create	POST	创建支付
/api/payment/query	GET	查询支付状态
/api/payment/notify	POST	支付回调
/api/refund/apply	POST	申请退款

📊 数据统计

• 支付金额统计
• 支付方式分布
• 退款率分析
• 对账报表

⚠️ 注意事项

1. 幂等性: 支付回调需保证幂等处理
2. 签名验证: 严格验证支付平台签名
3. 超时处理: 支付超时自动关闭订单
4. 退款审核: 可配置是否需要人工审核

📚 相关文档

• 订单系统
• 系统配置