# 支付模块架构概览

> **来源**: `~/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%）