docs: 支付模块开发文档 + git 域名更新
- 新增 backend/design/支付模块架构概览.md - 新增 backend/design/支付模块数据库设计.md (21张表 DDL) - 新增 backend/design/支付模块接口设计.md - git.dev.vifo.cc → git.vifo.cc 全局替换
This commit is contained in:
@@ -0,0 +1,220 @@
|
||||
# 支付模块架构概览
|
||||
|
||||
> **来源**: `~/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(解析回调) ← 异步通知
|
||||
```
|
||||
|
||||
1. 业务系统调用支付 API 创建订单
|
||||
2. API 调 Core 保存订单
|
||||
3. API 通过 Provider 调三方 SDK，返回支付参数
|
||||
4. 用户完成支付，三方异步通知 Provider
|
||||
5. Provider 验签解析，将结果通过 PayResponse 返回
|
||||
6. Core 更新订单状态、记录流水、处理分账和佣金
|
||||
7. API 异步通知业务系统
|
||||
|
||||
### 4.2 分账流程
|
||||
|
||||
```
|
||||
支付成功 → Core(创建分账订单+明细) → Provider(调渠道分账接口) → Core(更新状态+更新账户余额)
|
||||
```
|
||||
|
||||
### 4.3 对账流程
|
||||
|
||||
```
|
||||
定时任务 → 下载渠道对账文件 → 与本地订单逐笔比对 → 生成差异记录 → 人工/自动处理差异
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、关键设计决策
|
||||
|
||||
| 决策 | 理由 |
|
||||
|------|------|
|
||||
| 订单与流水分离 | 用户可能多次尝试支付（切换渠道、失败重试），每次需要独立追踪 |
|
||||
| 延迟分账（默认 T+7） | 降低退款风险，符合渠道分账规则，给予平台资金沉淀期 |
|
||||
| 三级代理体系 | 满足大部分场景，避免层级过多导致佣金比例过低 |
|
||||
| 独立资金账户 | 清晰的资金追踪，支持冻结/解冻，便于对账审计 |
|
||||
| Provider 不碰 DB | 纯网关设计，解耦三方 SDK 与业务逻辑，可独立测试和替换 |
|
||||
|
||||
---
|
||||
|
||||
## 六、安全设计
|
||||
|
||||
| 领域 | 措施 |
|
||||
|------|------|
|
||||
| 支付安全 | 签名验证、敏感信息加密存储、回调 IP 白名单、金额严格校验、幂等控制 |
|
||||
| 资金安全 | 支付密码 BCrypt 加密、资金操作审计日志、风控拦截、退款保障期资金冻结 |
|
||||
|
||||
---
|
||||
|
||||
## 七、Nacos 配置
|
||||
|
||||
```yaml
|
||||
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%）
|
||||
Reference in New Issue
Block a user