概述

EBAOZU 系统支持多种线上与线下支付渠道，包括微信支付（JSAPI、小程序、H5、APP、Native 扫码）、支付宝支付（APP、H5、扫码、付款码）、余额支付以及线下核销支付。本文档详细说明支付系统的架构、发起流程、异步通知处理及状态同步机制。

---

支付方式与标识

支付方式	标识 (pay_type)	适用场景
微信支付	weixin	微信公众号、微信小程序、微信 APP
微信 H5 支付	weixinh5	外部手机浏览器 H5 网页
支付宝支付	alipay	支付宝生活号、小程序、APP、手机网页 H5
余额支付	yue	用户账户余额扣减
线下支付	offline	门店自提或现场线下结算

---

支付架构与核心文件

app/services/pay/
├── PayServices.php          # 统一支付网关入口（根据 pay_type 分发渠道）
├── OrderPayServices.php     # 订单业务支付封装（参数组装与状态校验）
├── PayNotifyServices.php    # 支付异步回调业务处理
├── YuePayServices.php       # 用户余额支付逻辑
└── ...

app/listener/pay/
├── PayNotifyListener.php    # 支付异步回调事件监听器
└── ...

crmeb/services/
├── AliPayService.php        # 支付宝底层服务（基于 Alipay EasySDK）
└── wechat/
    └── Payment.php          # 微信支付底层服务（V2/V3 适配）

app/controller/api/v1/Pay.php # 外部支付平台异步通知统一接收控制器

---

支付处理核心链路

发起支付流程

前端发起支付请求 → Controller → OrderPayServices (校验订单/金额) → PayServices::pay() → 调用第三方渠道 SDK → 返回支付参数给前端调起收银台

• 统一入口 (PayServices.php)：根据前端传递的 pay_type 及客户端环境（微信内、小程序、独立 APP、浏览器），调用对应渠道生成预支付交易单或跳转链接。

余额支付处理 (YuePayServices.php)

余额支付在本地数据库事务内执行：

1. 校验用户余额是否充足；
2. 原子扣减用户 now_money，记录余额变动日志（eb_user_money）；
3. 直接调用 StoreOrderSuccessServices::paySuccess() 标记订单支付成功并派发订单支付后事件。

外部渠道异步回调处理

外部支付平台 (微信/支付宝) 
     │ POST 异步通知
     ▼
Pay 控制器 (/api/pay/notify/:type)
     │ 验证签名 (验签防伪造)
     ▼
触发 pay.notify 事件
     │
     ▼
PayNotifyListener 监听器
     │
     ▼
PayNotifyServices 对应渠道处理方法 (wechatProduct / aliyunProduct)
     │ 校验订单金额与 paid 状态
     ▼
StoreOrderSuccessServices::paySuccess()
     │
     ▼
派发 order.pay.success 事件 (处理佣金、积分、升级等后续任务)

---

支付安全性规范

1. 严格验签：所有来自外部的异步通知必须通过官方公钥完整验签，严禁直接读取回调参数修改订单。
2. 幂等性保障：在处理支付成功业务前，先通过数据库行级排他锁或状态检查确认 paid == 0，防止网络重复通知导致重复发货或赠送积分。
3. 金额一致性：回调中的实际支付金额（total_amount / total_fee）必须与系统订单的 pay_price 进行二次比对校验。