Pay模块架构与调用逻辑文档
一、模块整体架构
1.1 模块组成
hjy-module-pay/
├── hjy-module-pay-api/ # API定义模块(RPC接口、DTO、枚举)
│ └── src/main/java/cn/hjy/pay/
│ ├── api/ # Feign RPC接口定义
│ ├── enums/ # 枚举定义(ApiConstants等)
│ └── dto/ # 接口DTO定义
│
└── hjy-module-pay-biz/ # 业务实现模块
└── src/main/java/cn/hjy/pay/
├── PayServerApplication.java # 启动类(SpringBoot应用,服务名: pay-server)
├── api/ # RPC接口实现
├── controller/ # Admin/App 控制层
├── service/ # 核心业务服务
├── dal/ # 数据访问层
├── framework/ # 框架配置(支付、安全、RPC、Job)
├── config/ # 配置类(MallBook配置等)
├── convert/ # 对象转换
├── util/ # 工具类
├── mq/ # 消息队列消费者
└── job/ # 定时任务
1.2 RPC服务名称与前缀
- 服务名:
pay-server - API前缀:
/rpc-api/pay - 各API子路径:
- 订单:
/rpc-api/pay/order - 退款:
/rpc-api/pay/refund - 转账:
/rpc-api/pay/transfer - 商户:
/rpc-api/pay/merchant - 提现:
/rpc-api/pay/withdraw
- 订单:
二、核心服务架构图
业务服务(团购、外卖等)
│
Feign RPC
│
┌──────▼──────┐
│ PayModule │
│ (pay-server)│
└──┬──┬──┬──┬─┘
│ │ │ │
┌──────────────┘ │ │ └──────────────┐
│ │ │ │
支付订单 退款服务 转账服务 商户管理
(PayOrder) (PayRefund) (PayTransfer) (PayMallMerchant)
│ │ │ │
└─────────────────┬──┴─────────────────┘
│
┌─────▼─────┐
│ 支付渠道 │
│ PayChannel│
└─────┬─────┘
│
┌─────────────────┼─────────────────┐
│ │ │
微信支付 支付宝支付 MallBook(汇付天下)
/支付宝 /微信 ├── 分账
├── 充值
├── 转账
├── 提现
└── 子商户注册
三、核心服务列表与职责
| 服务接口 | 实现类 | 职责描述 |
|---|---|---|
PayOrderService | PayOrderServiceImpl | 支付订单的创建、提交、状态同步、过期处理、渠道手续费计算 |
PayRefundService | PayRefundServiceImpl | 退款单创建、退款状态同步 |
PayTransferService | PayTransferServiceImpl | 转账单创建、转账执行、状态同步、余额转账 |
PayWithDrawService | PayWithDrawServiceImpl | 子商户结算/提现管理 |
PayMallMerchantService | PayMallMerchantServiceImpl | MallBook子商户管理(注册、绑定、解绑) |
MallBookApiService | MallBookApiServiceImpl | MallBook三方API对接(分账、充值、转账、提现、查询余额等) |
PayChannelService | PayChannelServiceImpl | 支付渠道配置管理、获取PayClient |
PayAppService | PayAppServiceImpl | 支付应用管理 |
PayWalletRechargeService | PayWalletRechargeServiceImpl | 钱包充值记录管理、余额扣减 |
PayRechargeTransactionService | PayRechargeTransactionServiceImpl | 充值交易记录 |
SplitOrderService | SplitOrderServiceImpl | 分单服务 |
PayNotifyService | PayNotifyServiceImpl | 支付结果通知服务(回调业务方) |
四、三方支付对接情况
4.1 主要三方渠道:MallBook(汇付天下)
配置文件位置:MallBookMerchantConfig.java
配置前缀:hjy.pay.mallbook
配置参数:
hjy:
pay:
mallbook:
api-base: # API基础地址
merchant-no: # 商户号
merchant-private-key: # 商户私钥路径
mallbook-public-key: # MallBook公钥路径
version: "1.0.0" # 接口版本
split-notify-url: # 分账回调地址
draw-notify-url: # 提现回调地址
create-notify-url: # 子商户创建回调地址
prod-environment: false # 是否生产环境
MallBook支持的能力(见 MallBookApiService.java):
| 方法名 | 功能描述 |
|---|---|
registerSubMerchant() | 注册新的子商户 |
queryUser() | 查询用户是否已注册子商户 |
complete() | 分账接口 - 按比例将资金分配给各子商户 |
asyncReceive() | 确认收货接口 - 异步确认收货分账 |
withdraw() | 提现接口 - 子商户余额提现 |
queryBalance() | 查询子商户可提现余额 |
recharge() | 商户充值 - 通过MallBook发起充值 |
transfer() | 商户转账 - 子商户间资金转账 |
queryRechargeStatus() | 查询充值订单状态 |
核心客户端:MallBookMerchantClient.java
- 负责初始化MallBook配置
- 提供商户号、API基础地址、密钥等访问方法
4.2 常规支付渠道(微信、支付宝等)
管理服务:PayChannelService
- 通过
PayChannelDO存储每个渠道的配置 - 每个渠道对应一个
PayClient(如WxPayClient) - 配置信息存储在
PayChannelDO.config字段中(包含商户号、密钥、证书等)
支付配置:PayProperties.java
hjy:
pay:
order-notify-url: # 支付成功回调地址
refund-notify-url: # 退款回调地址
transfer-notify-url: # 转账回调地址
charge-notify-url: # 充值回调地址
order-no-prefix: "P" # 支付订单号前缀
refund-no-prefix: "R" # 退款单号前缀
五、RPC API接口调用说明
5.1 支付订单 API (PayOrderApi)
| 接口 | 方法 | 说明 |
|---|---|---|
/rpc-api/pay/order/create | POST | 创建支付订单,返回订单ID |
/rpc-api/pay/order/get | GET | 根据ID查询支付订单详情 |
/rpc-api/pay/order/getRefundOrder | GET | 根据ID查询退款订单详情 |
/rpc-api/pay/order/update-price | PUT | 更新支付订单价格 |
/rpc-api/pay/order/close | PUT | 关闭支付订单 |
/rpc-api/pay/order/getChannelFeeRate | PUT | 按应用ID+日期计算渠道总手续费 |
/rpc-api/pay/order/getChannelFeeByPayOrderIds | PUT | 按订单ID集合计算渠道总手续费 |
调用示例(创建订单):
// 其他业务模块通过Feign调用
PayOrderApi payOrderApi = ...;
PayOrderCreateReqDTO req = PayOrderCreateReqDTO.builder()
.appId(appId)
.merchantOrderId("业务单号")
.subject("订单标题")
.body("订单详情")
.price(1000) // 金额:单位分
.userIp("用户IP")
.build();
Long payOrderId = payOrderApi.createOrder(req).getData();
5.2 退款 API (PayRefundApi)
| 接口 | 方法 | 说明 |
|---|---|---|
/rpc-api/pay/refund/create | POST | 创建退款单,返回退款ID |
/rpc-api/pay/refund/get | GET | 查询退款单详情 |
/rpc-api/pay/refund/getIds | GET | 批量查询退款单 |
5.3 转账 API (PayTransferApi)
| 接口 | 方法 | 说明 |
|---|---|---|
/rpc-api/pay/transfer/create | POST | 创建转账单(发起余额转账) |
/rpc-api/pay/transfer/get | GET | 查询转账单详情 |
5.4 商户/分账 API (PayMerchantApi)
| 接口 | 方法 | 说明 |
|---|---|---|
/rpc-api/pay/merchant/create | POST | 创建MallBook子商户 |
/rpc-api/pay/merchant/update | POST | 更新子商户信息 |
/rpc-api/pay/merchant/get | GET | 获取子商户信息 |
/rpc-api/pay/merchant/bind | POST | 商户绑卡 |
/rpc-api/pay/merchant/unbind | POST | 商户解绑 |
/rpc-api/pay/merchant/complete | POST | 分账接口 - 订单完成后分账给子商户 |
/rpc-api/pay/merchant/receive | POST | 确认收货接口 - 异步确认收货分账 |
/rpc-api/pay/merchant/withdraw | POST | 结算/提现接口 - 子商户提现 |
调用示例(分账):
PayMerchantApi payMerchantApi = ...;
PayMerchantCompleteReqDTO req = PayMerchantCompleteReqDTO.builder()
.payOrderId(payOrderId) // 支付订单ID
.merchantOrderId("业务单号") // 业务订单号
.splitList(splitUsers) // 分账列表(用户ID+金额)
.notifyUrl("业务回调地址")
.build();
String result = payMerchantApi.complete(req).getData();
5.5 提现 API (PayWithDrawApi)
| 接口 | 方法 | 说明 |
|---|---|---|
/rpc-api/pay/withdraw/get | GET | 查询提现单详情 |
六、支付全流程调用时序
6.1 支付订单创建与提交流程
【业务模块】 【PayModule】 【三方支付】
│ │ │
│ 1. 创建支付订单 │ │
├───────────────────►│ createOrder() │
│ │ ├── PayOrderDO 入库 │
│ │ │
│◄────────────────────┤ return payOrderId │
│ │ │
│ 2. 提交支付(APP) │ │
├───────────────────►│ submitOrder() │
│ │ ├── 验证订单状态 │
│ │ ├── 选择支付渠道 │
│ │ ├── PayOrderExtensionDO 入库
│ │ │
│ │ 3. 调用三方支付接口 │
│ │──────────────────────►│ 统一收单
│ │ │
│ │◄──────────────────────┤ 支付参数/二维码
│◄────────────────────┤ return payParams │
│ │ │
│ 4. 用户完成支付 │ │
│ │ │
│ 5. 支付结果异步通知 │ │
│ │◄──────────────────────┤ 支付回调
│ │ notifyOrder() │
│ │ ├── 更新订单状态 │
│ │ ├── PayNotifyService │
│ │ │
│ │───────MQ通知─────────►│ 业务模块
│ │ │
│ │ │
│ 6. 定时同步状态 │ │
│ │ syncOrder() │
│ │──────────────────────►│ 查询订单状态
│ │◄──────────────────────┤
6.2 分账流程(MallBook)
【业务模块】 【PayModule】 【MallBook】
│ │ │
│ 1. 订单完成触发分账 │ │
├───────────────────►│ complete() │
│ │ ├── 参数组装 │
│ │ ├── MallBookApiService
│ │ │
│ │ 2. 调用分账接口 │
│ │──────────────────────►│ CompleteClient
│ │ │
│ │◄──────────────────────┤ 分账结果
│ │ │
│ 3. 异步分账回调 │ │
│ │◄──────────────────────┤
│ │ notify() │
│ │ ├── 更新分账状态 │
│ │ ├── 通知业务模块 │
│◄────────────────────┤ │
支付模块设计模式详解
七、关键定时任务(Job)
| Job类 | 功能 | 执行时机 |
|---|---|---|
PayOrderSyncJob | 同步支付订单状态 | 定时查询未完成订单的三方状态 |
PayOrderExpireJob | 订单过期处理 | 将超时未支付的订单标记为已关闭 |
PayRefundSyncJob | 同步退款订单状态 | 定时查询未完成退款的三方状态 |
PayNotifyJob | 通知重试 | 异步通知失败时重试通知业务模块 |
八、数据持久化(主要DO)
| DO类 | 数据表 | 功能描述 |
|---|---|---|
PayOrderDO | pay_order | 支付订单主表 |
PayOrderExtensionDO | pay_order_extension | 支付订单扩展(每次支付提交的记录) |
PayRefundDO | pay_refund | 退款单表 |
PayTransferDO | pay_transfer | 转账单表 |
PayWithDrawDO | pay_withdraw | 提现/结算单表 |
PayMallMerchantDO | pay_mall_merchant | MallBook子商户信息表 |
PayChannelDO | pay_channel | 支付渠道配置表 |
PayAppDO | pay_app | 支付应用配置表(不同业务场景的应用) |
PayWalletRechargeDO | pay_wallet_recharge | 钱包充值记录表 |
PayRechargeTransactionDO | pay_recharge_transaction | 充值交易明细表 |
PayNotifyTaskDO | pay_notify_task | 通知任务表 |
PayNotifyLogDO | pay_notify_log | 通知日志表 |
SplitOrderDO | split_order | 分单表 |
九、异步通知机制
通知服务:PayNotifyService
- 支付成功/退款成功/转账成功后,创建通知任务
- 通过定时任务(
PayNotifyJob)轮询执行通知 - 支持重试机制(多次失败则人工处理)
- 通知地址从各业务方的 PayAppDO 中获取
通知类型枚举:PayNotifyTypeEnum
- ORDER:支付订单通知
- REFUND:退款通知
- TRANSFER:转账通知
- WITHDRAW:提现通知
十、关键配置类汇总
| 配置类 | 前缀 | 说明 |
|---|---|---|
PayProperties | hjy.pay | 支付核心配置(回调地址、单号前缀) |
MallBookMerchantConfig | hjy.pay.mallbook | MallBook商户配置(API地址、密钥等) |
十一、对接其他业务模块的建议流程
-
接入支付:
- 配置
PayAppDO(分配应用ID、配置通知地址) - 配置
PayChannelDO(开通微信/支付宝等渠道) - 调用
PayOrderApi.createOrder()创建订单 - 前端调用APP接口获取支付参数
- 监听支付结果通知(或定时查询)
- 配置
-
接入分账:
- 子商户先通过
PayMerchantApi.createMerchant()注册 - 订单完成后调用
PayMerchantApi.complete()发起分账 - 监听分账结果通知
- 子商户先通过
-
接入提现:
- 调用
PayMerchantApi.withdraw()发起提现 - 监听提现结果通知
- 调用
-
接入退款:
- 调用
PayRefundApi.createRefund()发起退款 - 监听退款结果通知
- 调用
以上是pay模块的完整架构逻辑和调用逻辑说明,如有具体问题可针对单个服务或接口深入沟通。

2390

被折叠的 条评论
为什么被折叠?



