Pay模块架构与调用逻辑文档

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(汇付天下)
    /支付宝           /微信            ├── 分账
                                      ├── 充值
                                      ├── 转账
                                      ├── 提现
                                      └── 子商户注册

三、核心服务列表与职责

服务接口实现类职责描述
PayOrderServicePayOrderServiceImpl支付订单的创建、提交、状态同步、过期处理、渠道手续费计算
PayRefundServicePayRefundServiceImpl退款单创建、退款状态同步
PayTransferServicePayTransferServiceImpl转账单创建、转账执行、状态同步、余额转账
PayWithDrawServicePayWithDrawServiceImpl子商户结算/提现管理
PayMallMerchantServicePayMallMerchantServiceImplMallBook子商户管理(注册、绑定、解绑)
MallBookApiServiceMallBookApiServiceImplMallBook三方API对接(分账、充值、转账、提现、查询余额等)
PayChannelServicePayChannelServiceImpl支付渠道配置管理、获取PayClient
PayAppServicePayAppServiceImpl支付应用管理
PayWalletRechargeServicePayWalletRechargeServiceImpl钱包充值记录管理、余额扣减
PayRechargeTransactionServicePayRechargeTransactionServiceImpl充值交易记录
SplitOrderServiceSplitOrderServiceImpl分单服务
PayNotifyServicePayNotifyServiceImpl支付结果通知服务(回调业务方)

四、三方支付对接情况

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/createPOST创建支付订单,返回订单ID
/rpc-api/pay/order/getGET根据ID查询支付订单详情
/rpc-api/pay/order/getRefundOrderGET根据ID查询退款订单详情
/rpc-api/pay/order/update-pricePUT更新支付订单价格
/rpc-api/pay/order/closePUT关闭支付订单
/rpc-api/pay/order/getChannelFeeRatePUT按应用ID+日期计算渠道总手续费
/rpc-api/pay/order/getChannelFeeByPayOrderIdsPUT按订单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/createPOST创建退款单,返回退款ID
/rpc-api/pay/refund/getGET查询退款单详情
/rpc-api/pay/refund/getIdsGET批量查询退款单

5.3 转账 API (PayTransferApi)

接口方法说明
/rpc-api/pay/transfer/createPOST创建转账单(发起余额转账)
/rpc-api/pay/transfer/getGET查询转账单详情

5.4 商户/分账 API (PayMerchantApi)

接口方法说明
/rpc-api/pay/merchant/createPOST创建MallBook子商户
/rpc-api/pay/merchant/updatePOST更新子商户信息
/rpc-api/pay/merchant/getGET获取子商户信息
/rpc-api/pay/merchant/bindPOST商户绑卡
/rpc-api/pay/merchant/unbindPOST商户解绑
/rpc-api/pay/merchant/completePOST分账接口 - 订单完成后分账给子商户
/rpc-api/pay/merchant/receivePOST确认收货接口 - 异步确认收货分账
/rpc-api/pay/merchant/withdrawPOST结算/提现接口 - 子商户提现

调用示例(分账)

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/getGET查询提现单详情

六、支付全流程调用时序

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类数据表功能描述
PayOrderDOpay_order支付订单主表
PayOrderExtensionDOpay_order_extension支付订单扩展(每次支付提交的记录)
PayRefundDOpay_refund退款单表
PayTransferDOpay_transfer转账单表
PayWithDrawDOpay_withdraw提现/结算单表
PayMallMerchantDOpay_mall_merchantMallBook子商户信息表
PayChannelDOpay_channel支付渠道配置表
PayAppDOpay_app支付应用配置表(不同业务场景的应用)
PayWalletRechargeDOpay_wallet_recharge钱包充值记录表
PayRechargeTransactionDOpay_recharge_transaction充值交易明细表
PayNotifyTaskDOpay_notify_task通知任务表
PayNotifyLogDOpay_notify_log通知日志表
SplitOrderDOsplit_order分单表

九、异步通知机制

通知服务PayNotifyService

  • 支付成功/退款成功/转账成功后,创建通知任务
  • 通过定时任务(PayNotifyJob)轮询执行通知
  • 支持重试机制(多次失败则人工处理)
  • 通知地址从各业务方的 PayAppDO 中获取

通知类型枚举PayNotifyTypeEnum

  • ORDER:支付订单通知
  • REFUND:退款通知
  • TRANSFER:转账通知
  • WITHDRAW:提现通知

十、关键配置类汇总

配置类前缀说明
PayPropertieshjy.pay支付核心配置(回调地址、单号前缀)
MallBookMerchantConfighjy.pay.mallbookMallBook商户配置(API地址、密钥等)

十一、对接其他业务模块的建议流程

  1. 接入支付

    • 配置 PayAppDO(分配应用ID、配置通知地址)
    • 配置 PayChannelDO(开通微信/支付宝等渠道)
    • 调用 PayOrderApi.createOrder() 创建订单
    • 前端调用APP接口获取支付参数
    • 监听支付结果通知(或定时查询)
  2. 接入分账

    • 子商户先通过 PayMerchantApi.createMerchant() 注册
    • 订单完成后调用 PayMerchantApi.complete() 发起分账
    • 监听分账结果通知
  3. 接入提现

    • 调用 PayMerchantApi.withdraw() 发起提现
    • 监听提现结果通知
  4. 接入退款

    • 调用 PayRefundApi.createRefund() 发起退款
    • 监听退款结果通知

以上是pay模块的完整架构逻辑和调用逻辑说明,如有具体问题可针对单个服务或接口深入沟通。

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

刘明芳

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值