--- url: /blog/hxr0219q/index.md --- # ShopXO 支付系统技术方案文档 > **文档版本**: v1.0 > **创建时间**: 2026-01-30 > **适用系统**: ShopXO v6.7.0 > **文档类型**: 技术架构方案 *** ## 目录 1. [系统概览与架构图](payment-system-architecture.md#1-系统概览与架构图) 2. [核心设计与模式](payment-system-architecture.md#2-核心设计与模式) 3. [支付流程详解](payment-system-architecture.md#3-支付流程详解) 4. [扩展机制](payment-system-architecture.md#4-扩展机制) 5. [安全与幂等性](payment-system-architecture.md#5-安全与幂等性) *** ## 1. 系统概览与架构图 ### 1.1 系统定位 ShopXO 支付系统是整个电商系统的核心资金流转模块，负责处理所有涉及资金交易的业务场景： | 业务类型 | 说明 | 业务标识 | |---------|------|---------| | 订单支付 | 商品订单支付 | `order` | | 钱包充值 | 用户钱包余额充值 | `wallet_recharge` | | 会员购买 | 会员等级购买 | `membership_level_vip` | | 自定义业务 | 插件扩展的其他支付业务 | 自定义标识 | ### 1.2 整体架构 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 应用层 (Application) │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Index模块 │ │ Api模块 │ │ Admin模块 │ │ │ │ (PC/H5) │ │ (小程序/APP) │ │ (后台管理) │ │ │ │ │ │ │ │ │ │ │ │ Buy.php │ │ Buy.php │ │ Payment.php │ │ │ │ Order.php │ │ Ordernotify │ │ (配置管理) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ └───────────┼──────────────────┼──────────────────────────────────────┘ │ │ ┌───────────┼──────────────────┼──────────────────────────────────────┐ │ ▼ ▼ 服务层 (Service Layer) │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ PaymentService │ │ │ │ (支付方式服务层) │ │ │ │ • 插件列表管理 • 配置管理 • 安装/卸载 │ │ │ │ • 入口文件生成 • 权限校验 • 合法性验证 │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ │ ┌───────────────────────┘ └────────────────────────┐ │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────────────────┐ ┌─────────────────────────────────────┐ │ │ │ │ PayLogService │ │ 业务Service层 │ │ │ │ │ │ (支付日志服务) │ │ • OrderService │ │ │ │ │ │ • 日志创建 │ │ • WalletService │ │ │ │ │ │ • 状态更新 │ │ • MembershipService │ │ │ │ │ │ • 幂等性控制 │ │ • 插件扩展Service │ │ │ │ │ └─────────────────────┘ └─────────────────────────────────────┘ │ │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ ┌───────────┼──────────────────────────────────────────────────────────┐ │ ▼ 支付扩展层 (Payment Extensions) │ ├──────────────────────────────────────────────────────────────────────┤ │ │ │ extend/payment/ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Weixin │ │ Alipay │ │ PayPal │ │ QQ │ ... 60+ │ │ │ (微信) │ │ (支付宝) │ │ (贝宝) │ │ (QQ钱包) │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ │ │ │ │ └────────────┴────────────┴────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────┐ │ │ │ 统一接口规范 │ │ │ │ • Config() │ │ │ │ • Pay() │ │ │ │ • Respond() │ │ │ │ • Notify() │ │ │ └─────────────────────┘ │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ ┌───────────┼──────────────────────────────────────────────────────────┐ │ ▼ 第三方支付平台 │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │微信支付 │ │支付宝 │ │PayPal │ │其他平台 │ │ │ │平台 │ │平台 │ │平台 │ │ │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` ### 1.3 核心组件关系 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 核心组件依赖关系 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ PaymentService │ │ │ │ │ ├──► PayLogService (支付日志管理) │ │ │ ├──► PayLog (支付日志主表) │ │ │ └──► PayLogValue (业务关联表) │ │ │ │ │ ├──► 支付扩展 (extend/payment/*.php) │ │ │ ├──► Config() (配置信息) │ │ │ ├──► Pay() (发起支付) │ │ │ ├──► Respond() (同步回调) │ │ │ └──► Notify() (异步通知) │ │ │ │ │ ├──► ResourcesService (附件服务) │ │ ├──► StoreService (应用市场服务) │ │ └──► SystemService (系统服务) │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 1.4 数据库设计 #### 支付日志表 (sxo\_pay\_log) | 字段 | 类型 | 说明 | |-----|------|------| | id | bigint | 主键ID | | log\_no | varchar(64) | 支付日志单号 (唯一) | | user\_id | int | 用户ID | | system\_type | varchar(32) | 系统类型 | | client\_type | varchar(16) | 客户端类型 (pc/h5/ios/android/weixin...) | | total\_price | decimal(10,2) | 订单总金额 | | business\_type | varchar(64) | 业务类型 (order/wallet\_recharge/...) | | subject | varchar(255) | 订单名称/备注 | | payment | varchar(64) | 支付方式标识 | | payment\_name | varchar(128) | 支付方式名称 | | trade\_no | varchar(128) | 第三方交易号 | | buyer\_user | varchar(128) | 支付方账号 | | status | tinyint | 状态 (0待支付/1已支付/2已关闭) | | pay\_time | int | 支付成功时间 | | add\_time | int | 创建时间 | | close\_time | int | 关闭时间 | #### 业务关联表 (sxo\_pay\_log\_value) | 字段 | 类型 | 说明 | |-----|------|------| | id | bigint | 主键ID | | pay\_log\_id | bigint | 支付日志ID | | business\_id | bigint | 业务订单ID | | business\_no | varchar(64) | 业务订单号 | *** ## 2. 核心设计与模式 ### 2.1 统一抽象接口设计 支付系统采用**策略模式** + **模板方法模式**，通过统一抽象接口实现多支付方式的解耦： ```php // 支付插件必须实现的接口 interface PaymentInterface { // 配置信息 public function Config(): array; // 发起支付 public function Pay(array $params): array; // 同步回调处理 public function Respond(array $params): array; // 异步通知处理 public function Notify(array $params): array; } ``` #### 设计原则 | 原则 | 实现方式 | |-----|---------| | **开闭原则 (OCP)** | 新增支付方式无需修改核心代码，仅添加扩展文件 | | **单一职责 (SRP)** | PaymentService 负责管理，支付插件负责具体实现 | | **依赖倒置 (DIP)** | 依赖抽象接口而非具体支付实现 | | **里氏替换 (LSP)** | 所有支付插件可互相替换使用 | ### 2.2 配置驱动设计 #### 支付插件配置结构 ```php // 支付插件配置返回结构 [ 'base' => [ 'name' => '支付方式名称', 'version' => '版本号', 'apply_version' => '适用系统版本', 'apply_terminal' => ['pc', 'h5', 'ios', 'android', ...], 'desc' => '描述信息', 'author' => '开发者', 'author_url' => '开发者主页', ], 'element' => [ // 配置表单项（动态生成后台配置界面） [ 'element' => 'input|select|textarea', 'type' => 'text|password|number', 'name' => '配置项键名', 'title' => '配置项标题', 'placeholder' => '占位符', 'default' => '默认值', 'is_required' => 0|1, 'message' => '验证提示', 'element_data' => [...] // select选项数据 ], // ... 更多配置项 ] ] ``` #### 配置存储 ``` 数据库表: sxo_payment ├── payment: 支付方式标识 (如 Weixin, Alipay) ├── name: 支付方式显示名称 ├── logo: 支付方式图标 ├── config: JSON格式的插件配置参数 ├── apply_terminal: JSON格式的适用终端 ├── element: JSON格式的配置表单定义 ├── is_enable: 是否启用 └── is_open_user: 是否对用户开放 ``` ### 2.3 多终端自适应设计 系统根据 `APPLICATION_CLIENT_TYPE` 常量自动选择合适的支付实现： ``` ┌─────────────────────────────────────────────────────────────┐ │ 终端类型判断 │ ├─────────────────────────────────────────────────────────────┤ │ │ │ APPLICATION_CLIENT_TYPE │ │ │ │ │ ├──► pc → PC Web支付 (扫码/跳转) │ │ ├──► h5 → 移动Web支付 (H5支付) │ │ ├──► ios → iOS APP支付 (SDK调起) │ │ ├──► android → Android APP支付 (SDK调起) │ │ ├──► weixin → 微信内支付 (JSAPI) │ │ ├──► alipay → 支付宝内支付 │ │ └──► ... → 其他终端 │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### 2.4 钩子扩展机制 系统在关键节点预留钩子，支持业务扩展： | 钩子名称 | 触发时机 | 用途 | |---------|---------|------| | `plugins_service_payment_all_list` | 获取支付方式列表 | 插件自定义支付方式 | | `plugins_service_payment_buy_list` | 获取下单支付列表 | 过滤/增加支付选项 | | `plugins_service_payment_data` | 获取支付方式数据 | 动态修改支付配置 | | `plugins_service_paylog_insert_success` | 支付日志创建成功 | 关联业务处理 | | `plugins_service_paylog_pages_list_data` | 支付订单页面列表 | 自定义页面入口 | *** ## 3. 支付流程详解 ### 3.1 发起支付流程 ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 发起支付时序图 │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ 用户/系统 Controller Service 支付插件 第三方 │ │ │ │ │ │ │ │ │ 1.选择支付方式 │ │ │ │ │ │─────────────────►│ │ │ │ │ │ │ │ │ │ │ │ │ 2.获取支付列表 │ │ │ │ │ │──────────────►│ │ │ │ │ │ │ │ │ │ │ │ 3.返回可用方式 │ │ │ │ │ │◄──────────────│ │ │ │ │ │ │ │ │ │ │ 4.确认支付 │ │ │ │ │ │─────────────────►│ │ │ │ │ │ │ │ │ │ │ │ │ 5.创建支付日志 │ │ │ │ │ │──────────────►│ │ │ │ │ │ │ │ │ │ │ │ 6.返回log_no │ │ │ │ │ │◄──────────────│ │ │ │ │ │ │ │ │ │ │ │ 7.调用Pay() │ │ │ │ │ │──────────────────────────────►│ │ │ │ │ │ │ │ │ │ │ │ │ 8.发起支付请求 │ │ │ │ │ │──────────────►│ │ │ │ │ │ │ │ │ │ │ │ 9.返回支付参数 │ │ │ │ │ │◄──────────────│ │ │ │ │ │ │ │ │ 10.返回支付结果 │ │ │ │ │ │◄─────────────────│ │ │ │ │ │ │ │ │ │ │ │ 11.调起支付/跳转 │ │ │ │ │ │─────────────────►│ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` #### 关键步骤说明 1. **支付方式筛选**: 根据 `apply_terminal` 配置过滤当前终端可用的支付方式 2. **支付日志创建**: 生成唯一 `log_no`，记录业务关联信息 3. **构建支付参数**: 支付插件根据终端类型构建对应支付参数 4. **记录请求日志**: 将支付请求参数记录到 `request_params` 字段 ### 3.2 支付回调处理 #### 同步回调 (Respond) ``` ┌─────────────────────────────────────────────────────────────────┐ │ 同步回调处理流程 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 第三方支付平台 入口文件 Controller 业务处理 │ │ │ │ │ │ │ │ │ 1.用户操作完成 │ │ │ │ │ │──────────────►│ │ │ │ │ │ │ │ │ │ │ │ │ 2.GET请求 │ │ │ │ │ │───────────────►│ │ │ │ │ │ │ │ │ │ │ │ │ 3.调用Respond()│ │ │ │ │ │──────────────►│ │ │ │ │ │ │ │ │ │ │ │ 4.验证签名 │ │ │ │ │ │──────────────►│ │ │ │ │ │ │ │ │ │ │ │ 5.查询支付状态│ │ │ │ │ │──────────────►│ │ │ │ │ │ │ │ │ │ │ │ 6.跳转结果页 │ │ │ │ │ │◄──────────────│ │ │ │ │ │ │ │ │ │ │ 7.展示结果 │ │ │ │ │ │◄───────────────│ │ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` **特点**: * 用户可见的回调 * 用于前端展示支付结果 * **不作为最终支付确认依据** #### 异步通知 (Notify) - 核心流程 ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 异步通知处理流程（核心） │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ 第三方支付平台 入口文件 Controller Service层 数据库 │ │ │ │ │ │ │ │ │ │ 1.支付成功 │ │ │ │ │ │ │─────────────►│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ 2.POST请求 │ │ │ │ │ │ │──────────────►│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ 3.记录请求日志 │ │ │ │ │ │ │──────────────►│ │ │ │ │ │ │ │ │ │ │ │ │ │ 4.调用Notify() │ │ │ │ │ │ │──────────────────────────────►│ │ │ │ │ │ │ │ │ │ │ │ │ │ 5.验证签名 │ │ │ │ │ │ │───────────────►│ │ │ │ │ │ │ │ │ │ │ │ │ │ 6.查询支付日志 │ │ │ │ │ │ │───────────────►│ │ │ │ │ │ │ │ │ │ │ │ │ │ 7.幂等性检查 │ │ │ │ │ │ │───────────────►│ │ │ │ │ │ │ │ │ │ │ │ │ │ 8.更新支付日志 │ │ │ │ │ │ │───────────────►│ │ │ │ │ │ │ │ │ │ │ │ │ │ 9.触发业务处理 │ │ │ │ │ │ │───┐ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │◄──┘ (订单/钱包等)│ │ │ │ │ │ │ │ │ │ │ │ │ 10.记录响应日志│ │ │ │ │ │ │◄──────────────│ │ │ │ │ │ │ │ │ │ │ │ │ 11.返回success│ │ │ │ │ │ │◄──────────────│ │ │ │ │ │ │ │ │ │ │ │ │ 12.确认收到 │ │ │ │ │ │ │◄─────────────│ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` **异步通知特点**: * 服务器间通信 * **支付成功的唯一确认依据** * 需要验证签名防篡改 * 必须返回特定格式的成功响应 * 支持重试机制 ### 3.3 入口文件生成机制 系统为每个支付方式在每个业务类型下生成独立的入口文件： #### 入口文件命名规则 ``` payment_{system_type}_{business_type}_{payment}_{type}.php 示例: ├── payment_default_order_weixin_notify.php # 订单微信支付异步通知 ├── payment_default_order_weixin_respond.php # 订单微信支付同步回调 ├── payment_default_wallet_alipay_notify.php # 钱包支付宝支付异步通知 └── ... ``` #### 入口文件作用 1. **支付方式标识**: 通过 `PAYMENT_TYPE` 常量标识 2. **系统类型隔离**: 支持多系统独立部署 3. **路由映射**: 将请求映射到统一控制器 4. **安全隔离**: 独立入口降低安全风险 ### 3.4 状态流转 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 支付日志状态流转图 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────┐ │ │ │ 创建 │ log_no生成, 业务关联 │ │ │ status=0 │ ──────────────────────┐ │ │ └──────────┘ │ │ │ │ │ │ │ │ ▼ │ │ │ ┌──────────────┐ │ │ │ │ 用户取消/超时 │ │ │ │ │ status=2 │ │ │ │ │ (已关闭) │ │ │ │ └──────────────┘ │ │ │ │ │ │ 支付成功 │ │ ▼ │ │ ┌─────────────┐ │ │ │ 异步通知处理 │ │ │ │ (核心) │ │ │ └─────────────┘ │ │ │ │ │ │ 验证通过 │ │ ▼ │ │ ┌──────────┐ │ │ │ status=1│ 更新trade_no, buyer_user, pay_time │ │ │ (已支付) │ 触发业务处理(订单/钱包/会员) │ │ └──────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` *** ## 4. 扩展机制 ### 4.1 插件化架构 支付系统完全插件化，新增支付方式无需修改核心代码： #### 插件开发步骤 1. **创建插件文件**: `extend/payment/XxxPayment.php` 2. **实现标准接口**: Config(), Pay(), Respond(), Notify() 3. **后台上传安装**: 通过ZIP包上传或直接放置文件 4. **配置参数**: 填写支付平台提供的配置参数 5. **生成入口文件**: 系统自动生成回调入口 #### 插件合法性验证 ```php // 验证流程 插件上传 ↓ 文件内容校验 (无eval等危险代码) ↓ 接口完整性检查 (Config, Pay, Respond, Notify) ↓ 配置信息获取 ↓ 应用市场授权验证 (可选) ↓ 安装成功 ``` ### 4.2 支付方式分类 #### 按平台类型 | 类型 | 代表支付方式 | 特点 | |-----|------------|------| | 国内主流 | 微信、支付宝、QQ钱包 | 覆盖最广，接入复杂 | | 银行渠道 | 建行、银联、各种银联通道 | 适合特定场景 | | 国际支付 | PayPal、OceanPayment | 跨境支付 | | 聚合支付 | 拉卡拉、通联、汇付 | 一码多付 | | 线下支付 | 货到付款、线下转账 | 无需接口 | #### 按接入方式 | 接入方式 | 文件特征 | 适用场景 | |---------|---------|---------| | SDK接入 | 包含证书文件、私钥 | APP支付、小程序支付 | | API接入 | 纯代码实现 | PC网站、H5支付 | | 跳转支付 | 仅返回跳转URL | 简单支付场景 | | 扫码支付 | 返回二维码 | PC扫码支付 | ### 4.3 扩展点设计 #### 当前支持的扩展点 | 扩展点 | 触发位置 | 扩展能力 | |-------|---------|---------| | 支付方式列表 | 获取可用支付方式时 | 动态添加/过滤支付选项 | | 支付配置 | 获取支付配置时 | 动态修改配置参数 | | 支付日志 | 支付日志创建后 | 关联业务数据 | | 支付完成 | 支付成功后 | 触发后续业务流程 | | 入口文件 | 入口创建/删除时 | 自定义文件生成逻辑 | #### 扩展示例 ```php // 通过钩子扩展支付方式 MyEventTrigger('plugins_service_payment_buy_list', [ 'hook_name' => 'plugins_service_payment_buy_list', 'is_backend' => true, 'params' => $params, 'data' => &$payment_list, // 引用传递，可直接修改 ]); ``` ### 4.4 热插拔支持 系统支持支付方式的热插拔操作： ``` ┌─────────────────────────────────────────────────────────────┐ │ 支付方式生命周期 │ ├─────────────────────────────────────────────────────────────┤ │ │ │ 未安装 │ │ │ │ │ │ 上传插件文件 │ │ ▼ │ │ ┌──────────┐ │ │ │ 待安装 │ 读取插件Config信息 │ │ └──────────┘ │ │ │ │ │ │ 安装操作 │ │ ▼ │ │ ┌──────────┐ │ │ │ 已安装 │ 写入数据库配置 │ │ │ (禁用) │ 生成入口文件 │ │ └──────────┘ │ │ │ │ │ │ 启用操作 │ │ ▼ │ │ ┌──────────┐ │ │ │ 已启用 │ is_enable=1, is_open_user=1 │ │ │ (可用) │ 用户可见可选 │ │ └──────────┘ │ │ │ │ │ │ 卸载操作 │ │ ▼ │ │ ┌──────────┐ │ │ │ 卸载 │ 删除数据库记录 │ │ └──────────┘ 删除入口文件 │ │ │ │ │ ▼ │ │ 未安装 │ │ │ └─────────────────────────────────────────────────────────────┘ ``` *** ## 5. 安全与幂等性 ### 5.1 安全保障机制 #### 签名验证 所有支付回调必须验证签名，防止数据篡改： ``` ┌─────────────────────────────────────────────────────────────────┐ │ 签名验证流程 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 第三方平台回调 │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ 获取回调数据 │ │ │ └─────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ 获取签名数据 │ (去除sign/sign_type字段) │ │ └─────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ 按字典序排序 │ │ │ └─────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ 拼接成字符串 │ │ │ └─────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ 进行加密运算 │ (RSA/MD5/HMAC-SHA256等) │ │ └─────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ 与传入签名 │ ──► 一致 ──► 验证通过 │ │ │ 对比验证 │ │ │ │ └─────────────┘ └──► 不一致 ──► 验证失败 │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` #### 请求日志记录 所有支付相关请求都会被记录，便于问题追踪： | 日志类型 | 存储位置 | 记录内容 | |---------|---------|---------| | 发起请求 | `pay_log.request_params` | 请求参数JSON | | 异步通知 | `pay_request_log` | 完整通知数据 | | 响应结果 | `pay_request_log.response_data` | 处理结果 | ### 5.2 幂等性保障 #### 支付日志幂等性 通过数据库状态字段实现： ```sql -- 更新支付状态时带条件，防止重复处理 UPDATE sxo_pay_log SET status = 1, trade_no = ?, pay_time = ? WHERE id = ? AND status = 0; -- 仅当状态为待支付时更新 -- 影响行数为0时表示已处理过 ``` #### 业务订单幂等性 业务订单在支付成功前有唯一支付日志关联： ``` 订单表 (sxo_order) ├── pay_log_id: 支付日志ID (唯一) └── pay_status: 支付状态 支付成功更新时: WHERE id = ? AND pay_status = 0 ``` #### 防重令牌机制 发起支付时生成唯一令牌： ```php // 生成支付令牌 $pay_cashier_cache_key = 'payment_cashier_key_' . $log_no; // 设置缓存，有效期30分钟 MyCache($pay_cashier_cache_key, $params, 1800); ``` ### 5.3 异常处理 #### 支付超时处理 ``` 订单创建 → 设置自动关闭时间 → 超时未支付 → 自动关闭 │ ▼ 各支付方式不同超时时间 • 微信: 2小时 • 支付宝: 可配置 (默认90分钟) • PayPal: 3天 ``` #### 回调重试机制 ``` 第三方支付平台重试策略: ┌───────────────────────────────────────────────────────────┐ │ │ │ 首次通知失败 │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────┐ │ │ │ 重试间隔 (各平台不同) │ │ │ ├──────────────────────────────────────────┤ │ │ │ 微信: 15s, 15s, 30s, 3m, 10m, 20m, ... │ │ │ │ 支付宝: 2m, 10m, 10m, ... (最多7次) │ │ │ │ PayPal: 持续重试，最多4天 │ │ │ └──────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ 返回 success → 停止重试 │ │ 返回 error/超时 → 继续重试 │ │ │ └───────────────────────────────────────────────────────────┘ ``` #### 记录异常日志 ``` ┌─────────────────────────────────────────────────────────────┐ │ 异常日志记录 │ ├─────────────────────────────────────────────────────────────┤ │ │ │ 日志文件: runtime/log/ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ error_YYYYMMDD.log │ │ │ │ ├── 支付插件调用失败 │ │ │ │ ├── 签名验证失败 │ │ │ │ ├── 支付日志查询失败 │ │ │ │ └── 业务处理异常 │ │ │ └──────────────────────────────────────────────────┘ │ │ │ │ 支付请求日志: sxo_pay_request_log │ │ ├── request_data: 请求数据 │ │ ├── response_data: 响应数据 │ │ ├── status: 处理状态 │ │ └── add_time: 记录时间 │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### 5.4 配置安全 #### 敏感信息保护 ```php // 配置项类型 支付插件配置: ├── 应用ID (appid) - 公开信息 ├── 商户号 (mch_id) - 公开信息 ├── 公钥 (rsa_public) - 公开信息 ├── 私钥 (rsa_private) - 敏感信息，仅限配置 ├── 密钥 (key) - 敏感信息，仅限配置 └── 证书文件 - 敏感信息，文件存储 ``` #### 权限校验 ``` 支付操作权限矩阵: ┌─────────────────────────────────────────────────────────────┐ │ │ │ 操作类型 用户 管理员 支付平台 │ │ ───────────────────────────────────────────────── │ │ 查看支付方式 ✓ ✓ ✗ │ │ 选择支付方式 ✓ ✗ ✗ │ │ 发起支付 ✓ ✗ ✗ │ │ 配置支付方式 ✗ ✓ ✗ │ │ 安装/卸载插件 ✗ ✓ ✗ │ │ 启用/禁用支付 ✗ ✓ ✗ │ │ 回调处理 ✗ ✗ ✓ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` *** ## 附录 ### A. 支持的支付方式列表 ``` extend/payment/ ├── Alipay.php # 支付宝 (PC/H5/APP) ├── AlipayCert.php # 支付宝证书版 ├── Weixin.php # 微信支付 (公众号/PC/H5/APP) ├── QQ.php # QQ钱包 ├── PayPal.php # PayPal国际支付 ├── Toutiao.php # 抖音支付 ├── BaiduMini.php # 百度小程序支付 ├── Kuaishou.php # 快手支付 ├── WalletPay.php # 钱包支付 ├── Xendit.php # Xendit (东南亚) ├── UniPayment.php # 虚拟货币支付 ├── OceanPayment.php # OceanPayment └── ... (60+ 支付方式) ``` ### B. 数据库表结构 #### sxo\_payment (支付方式配置表) ```sql CREATE TABLE `sxo_payment` ( `id` bigint(20) NOT NULL AUTO_INCREMENT, `payment` varchar(64) NOT NULL COMMENT '支付方式标识', `name` varchar(128) NOT NULL COMMENT '支付方式名称', `logo` varchar(255) DEFAULT '' COMMENT '支付方式图标', `config` text COMMENT '支付配置JSON', `element` text COMMENT '配置表单JSON', `apply_terminal` varchar(512) DEFAULT '' COMMENT '适用终端JSON', `sort` int(11) DEFAULT '0' COMMENT '排序', `is_enable` tinyint(1) DEFAULT '0' COMMENT '是否启用', `is_open_user` tinyint(1) DEFAULT '0' COMMENT '是否对用户开放', `add_time` int(11) DEFAULT NULL, `upd_time` int(11) DEFAULT NULL, PRIMARY KEY (`id`), UNIQUE KEY `payment` (`payment`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; ``` #### sxo\_pay\_log (支付日志表) ```sql CREATE TABLE `sxo_pay_log` ( `id` bigint(20) NOT NULL AUTO_INCREMENT, `log_no` varchar(64) NOT NULL COMMENT '支付日志单号', `user_id` int(11) DEFAULT '0', `system_type` varchar(32) DEFAULT '', `client_type` varchar(16) DEFAULT '', `total_price` decimal(10,2) DEFAULT '0.00', `business_type` varchar(64) DEFAULT '' COMMENT '业务类型', `subject` varchar(255) DEFAULT '', `payment` varchar(64) DEFAULT '', `payment_name` varchar(128) DEFAULT '', `trade_no` varchar(128) DEFAULT '' COMMENT '第三方交易号', `buyer_user` varchar(128) DEFAULT '', `status` tinyint(1) DEFAULT '0' COMMENT '0待支付/1已支付/2已关闭', `pay_time` int(11) DEFAULT NULL, `add_time` int(11) DEFAULT NULL, `close_time` int(11) DEFAULT NULL, `request_params` text COMMENT '支付请求参数JSON', PRIMARY KEY (`id`), UNIQUE KEY `log_no` (`log_no`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; ``` #### sxo\_pay\_log\_value (业务关联表) ```sql CREATE TABLE `sxo_pay_log_value` ( `id` bigint(20) NOT NULL AUTO_INCREMENT, `pay_log_id` bigint(20) NOT NULL, `business_id` bigint(20) NOT NULL COMMENT '业务订单ID', `business_no` varchar(64) DEFAULT '' COMMENT '业务订单号', `add_time` int(11) DEFAULT NULL, PRIMARY KEY (`id`), KEY `pay_log_id` (`pay_log_id`), KEY `business_id` (`business_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; ``` ### C. 关键常量定义 | 常量 | 说明 | 可能值 | |-----|------|-------| | `PAYMENT_TYPE` | 当前支付方式标识 | Weixin, Alipay, ... | | `SYSTEM_TYPE` | 系统类型标识 | default, ... | | `APPLICATION_CLIENT_TYPE` | 客户端类型 | pc, h5, ios, android, weixin, alipay, ... | ### D. 核心服务方法速查 #### PaymentService | 方法 | 说明 | 返回值 | |-----|------|-------| | `PluginsPaymentList($type)` | 获取支付插件列表 | 支付方式数组 | | `PaymentList($params)` | 获取已安装支付方式 | 支付方式数组 | | `BuyPaymentList($params)` | 获取可用支付方式 | 过滤后的支付列表 | | `PaymentSave($params)` | 保存支付配置 | 操作结果 | | `Install($params)` | 安装支付方式 | 操作结果 | | `Uninstall($params)` | 卸载支付方式 | 操作结果 | | `Delete($params)` | 删除支付插件 | 操作结果 | #### PayLogService | 方法 | 说明 | 返回值 | |-----|------|-------| | `PayLogInsert($params)` | 创建支付日志 | 支付日志数据 | | `PayLogSuccess($params)` | 更新为支付成功 | 操作结果 | | `PayLogClose($params)` | 关闭支付日志 | 操作结果 | | `PayLogData($log_no)` | 获取支付日志 | 日志详情 | | `BusinessOrderPayLogData($params)` | 获取业务订单支付日志 | 关联日志 | *** ## 文档变更记录 | 版本 | 日期 | 修改内容 | 作者 | |-----|------|---------|------| | v1.0 | 2026-01-30 | 初始版本 | System | *** **文档结束**