Files

T

vifo 7b2f3d77ca docs: 支付模块开发文档 + git 域名更新

- 新增 backend/design/支付模块架构概览.md
- 新增 backend/design/支付模块数据库设计.md (21张表 DDL)
- 新增 backend/design/支付模块接口设计.md
- git.dev.vifo.cc → git.vifo.cc 全局替换

2026-06-09 01:54:29 +08:00

6.8 KiB

Raw Blame History

支付模块架构概览

来源: ~/rui/支付模块架构设计.md v1.0 创建日期: 2026-06-08 模块: rui-payment

一、定位

rui-payment 是一个聚合支付平台，为上层业务提供统一、安全、高效的支付能力。

核心能力

能力	说明
聚合支付	支持支付宝、微信支付、银联云闪付等多渠道
智能路由	根据费率、成功率、渠道状态自动选择最优通道
分账体系	平台、商户、代理商多级分账，支持实时/延迟/手动分账
代理商体系	三级代理、佣金计算、代理结算
资金账户	余额、冻结、可用资金管理和流水记录
商户进件	商户入驻、资质上传、审核管理、渠道子商户配置
对账结算	自动对账、差错处理、结算单生成

二、模块结构

rui-payment/
├── rui-payment-common/       # DTO、枚举、常量、工具
├── rui-payment-core/         # Mapper、Entity、Service（数据库层）
├── rui-payment-provider/     # 第三方支付 SDK 封装（纯网关，不碰 DB）
├── rui-payment-api/          # REST API 服务（可部署）
└── rui-payment-task/         # MQ 监听器 + 定时任务

依赖关系

rui-payment-common
    ↑
rui-payment-core ──→ rui-payment-provider
    ↑                    ↑
rui-payment-api ←───────┘
    ↑
rui-payment-task

关键边界: rui-payment-provider 不依赖 rui-payment-core，只做三方 SDK 调用。

各模块职责

模块	核心职责	典型类
common	DTO、VO、枚举、常量	`PayRequest`, `PayResponse`, `PayStatus`
core	业务逻辑、数据访问	`PayOrderService`, `PayOrderMapper`, `PayOrder`
provider	第三方 SDK 封装	`AlipayPayHandler`, `WechatPayJsapiHandler`
api	REST API、启动类	`PaymentTradeController`, `PaymentNotifyController`
task	定时任务、MQ 监听	`ReconcileJob`, `SettlementJob`, `PayTimeoutListener`

三、核心业务概念

3.1 支付核心

PayOrder (支付订单) ──→ PayRecord (支付流水) ──→ PayChannelConfig (渠道配置)
       │
       ↓
PayRefund (退款单)

PayOrder: 业务侧发起的支付请求，含金额、商品信息、买卖双方
PayRecord: 单次支付尝试记录，含渠道信息、三方流水号。一个 Order 可对应多次 Record
PayRefund: 对已成功支付的订单退款，支持部分退款和多次退款

3.2 分账

SplitOrder (分账订单) ──→ SplitDetail (分账明细) ──→ SplitReceiver (分账接收方)

分账模式:

实时分账: 支付成功后立即调用渠道分账接口
延迟分账: 支付成功后冻结资金，延迟期（默认 T+7）后自动分账
手动分账: 运营人员在后台手动触发

3.3 代理商

Agent (代理商) ──→ AgentRelation (代理关系) ──→ AgentMerchant (代理商户)
       │
       ↓
AgentCommission (代理佣金) ──→ AgentSettlement (代理结算)

三级代理体系，每级独立计算佣金。

3.4 资金账户

Account (资金账户) ──→ AccountLog (账户流水)
       │
       ↓
AccountFreeze (资金冻结)

为每个商户/用户/代理创建独立资金账户，支持冻结、解冻。

3.5 商户进件

Merchant (商户) ──→ MerchantQualification (资质) ──→ MerchantAuditRecord (审核)
       │
       ↓
MerchantChannelConfig (渠道配置) ──→ SubMerchantInfo (子商户)

四、核心流程

4.1 支付流程

业务系统 → 支付API → 支付Core(保存订单) → 支付Provider(调SDK) → 第三方支付
                                                                      ↓
业务系统 ← 支付API(通知) ← Core(更新状态+分账+佣金) ← Provider(解析回调) ← 异步通知

业务系统调用支付 API 创建订单
API 调 Core 保存订单
API 通过 Provider 调三方 SDK，返回支付参数
用户完成支付，三方异步通知 Provider
Provider 验签解析，将结果通过 PayResponse 返回
Core 更新订单状态、记录流水、处理分账和佣金
API 异步通知业务系统

4.2 分账流程

支付成功 → Core(创建分账订单+明细) → Provider(调渠道分账接口) → Core(更新状态+更新账户余额)

4.3 对账流程

定时任务 → 下载渠道对账文件 → 与本地订单逐笔比对 → 生成差异记录 → 人工/自动处理差异

五、关键设计决策

决策	理由
订单与流水分离	用户可能多次尝试支付（切换渠道、失败重试），每次需要独立追踪
延迟分账（默认 T+7）	降低退款风险，符合渠道分账规则，给予平台资金沉淀期
三级代理体系	满足大部分场景，避免层级过多导致佣金比例过低
独立资金账户	清晰的资金追踪，支持冻结/解冻，便于对账审计
Provider 不碰 DB	纯网关设计，解耦三方 SDK 与业务逻辑，可独立测试和替换

六、安全设计

领域	措施
支付安全	签名验证、敏感信息加密存储、回调 IP 白名单、金额严格校验、幂等控制
资金安全	支付密码 BCrypt 加密、资金操作审计日志、风控拦截、退款保障期资金冻结

七、Nacos 配置

payment:
  order-timeout: 30                    # 订单超时（分钟）
  split-delay-days: 7                  # 分账延迟（天）
  commission-settle-cycle: T+1         # 佣金结算周期
  notify-max-times: 5                  # 通知重试次数
  notify-intervals: 15,30,60,300,900   # 通知间隔（秒）

  channels:
    alipay:
      enabled: true
      sandbox: false
      app-id: ${ALIPAY_APP_ID}
      private-key: ${ALIPAY_PRIVATE_KEY}
      public-key: ${ALIPAY_PUBLIC_KEY}
    wechatpay:
      enabled: true
      sandbox: false
      app-id: ${WXPAY_APP_ID}
      mch-id: ${WXPAY_MCH_ID}
      api-v3-key: ${WXPAY_API_V3_KEY}

security:
  oauth2:
    ignore-urls:
      - /payment/entry/**
      - /payment/notify/**

八、待开发功能清单

支付核心流程（下单、支付、回调、查询、关闭）
退款功能（申请、查询、回调）
分账功能（创建、执行、回退、查询）
商户进件（入驻、资质、审核、渠道配置）
代理商体系（多级代理、佣金计算、结算）
资金账户（开户、流水、冻结）
对账（下载、比对、差异处理）
结算（商户结算、代理结算）
银联渠道接入
单元测试（核心逻辑覆盖率 ≥80%）

6.8 KiB Raw Blame History Unescape Escape