972 lines
54 KiB
Markdown
972 lines
54 KiB
Markdown
# 产品需求文档 (PRD)
|
||
|
||
| 字段 | 内容 |
|
||
|-----|------|
|
||
| 产品名称 | pay-bridge |
|
||
| 文档版本 | v1.0 |
|
||
| 创建日期 | 2026-02-11 |
|
||
| 最后更新 | 2026-02-12 |
|
||
| 文档负责人 | |
|
||
| 状态 | 草稿 |
|
||
|
||
---
|
||
|
||
## 修订历史
|
||
|
||
| 版本 | 日期 | 修改人 | 修改内容 |
|
||
|-----|------|-------|---------|
|
||
| v1.0 | 2026-02-11 | 海清 | 初始版本 |
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
### 1.1 背景与问题
|
||
|
||
**现状**：
|
||
公司旗下有多套业务系统（电商平台、SaaS 产品、多商户平台），各系统均有支付收款需求。当前各系统独立对接第三方支付渠道，存在重复建设、维护分散的问题。
|
||
|
||
**问题**：
|
||
- 各业务系统各自对接支付渠道，开发成本高、协议理解门槛高
|
||
- 支付渠道升级或切换时，所有业务系统均需改动，影响范围大
|
||
- 缺乏统一的交易记录和对账机制，资金安全难以保障
|
||
- 无法快速响应新支付渠道或新支付方式的接入需求
|
||
|
||
**机会**：
|
||
构建统一的聚合支付网关中间层（pay-bridge），集中管理上游支付渠道，对下游业务系统提供标准化 API，一次对接、多处复用。
|
||
|
||
### 1.2 产品愿景
|
||
|
||
为企业内部多业务系统提供统一、安全、可扩展的聚合支付网关，屏蔽上游支付渠道差异，让业务系统专注业务逻辑而非支付对接。
|
||
|
||
**产品特色**：
|
||
1. **统一网关，一次对接**：屏蔽上游渠道协议差异，下游系统只需对接一套标准 API，即可接入微信、支付宝、银行卡等全渠道支付
|
||
2. **订单级分润，全链路资金闭环**：支持订单维度的分润配置，打通「支付 → 收款 → 分润 → 开票」全流程，一笔交易自动完成收款确认与利润分配
|
||
3. **多商户资金管理**：子商户固定收款账户、应用级分润比例、差异化服务费率，覆盖平台型业务的核心资金链路
|
||
4. **智能收款匹配**：固定银行账户收款后，根据金额、转账备注和付款方名称三维度自动匹配订单，大幅减少人工核对
|
||
5. **灵活服务费体系**：按应用和支付方式（扫码/对公/余额）独立配置费率，交易完成后自动扣收至指定子商户
|
||
6. **Go 轻量高性能**：Go 语言实现，资源占用低、并发能力强，对比 Java 方案部署更轻量
|
||
7. **自建自控，数据安全**：数据完全自主掌控，无第三方托管风险，无按量收费
|
||
|
||
### 1.3 目标与成功指标
|
||
|
||
| 目标类型 | 指标 | 当前值 | 目标值 | 衡量方式 |
|
||
|---------|-----|-------|-------|---------|
|
||
| 业务目标 | 下游系统支付接入周期 | 2-4 周/系统 | < 3 天/系统 | 从开始对接到完成联调的时间 |
|
||
| 业务目标 | 支持的支付渠道数 | 0 | ≥ 1（汇元支付） | 已上线渠道数量 |
|
||
| 用户目标 | 支付成功率 | - | ≥ 99.5% | 成功支付笔数 / 发起支付笔数 |
|
||
| 用户目标 | 对账覆盖率 | 0% | 100% | 已对账交易数 / 总交易数 |
|
||
| 技术目标 | 新渠道接入周期 | - | < 5 天 | 实现适配器到上线的时间 |
|
||
| 技术目标 | API 平均响应时间 | - | < 200ms（P95） | 监控系统统计 |
|
||
|
||
### 1.4 范围定义
|
||
|
||
**包含（In Scope）**：
|
||
- 聚合支付网关核心服务（统一下单、查询、退款、关单）
|
||
- 汇元支付（HePay）开放平台全渠道对接（微信、支付宝、银行卡快捷支付）
|
||
- 对下游系统的统一 RESTful 支付 API
|
||
- 异步通知机制（接收上游回调 + 通知下游系统）
|
||
- 自动对账（T+1 账单拉取、逐笔核对、差异报告）
|
||
- 分润能力（应用级配置分润接收方，下单时指定分润金额，订单完成后自动分账，最大比例限制）
|
||
- 订单编码服务按应用隔离（不同应用独立的订单号序列，互不干扰）
|
||
- 分润流水记录与对账（分润操作产生独立流水，纳入对账体系）
|
||
- 开票能力（若上游渠道提供开票接口，分润完成后支持调用开票）
|
||
- 子商户固定收款账户（上游渠道为子商户开通的专属银行账号，客户可直接转账付款）
|
||
- 订单自动匹配（根据入账金额和转账备注自动匹配待支付订单，完成收款确认）
|
||
- 服务费能力（按应用和支付方式配置服务费比例，指定收款子商户，交易完成后自动扣收）
|
||
- 渠道适配器框架（支持扩展新渠道）
|
||
- 渠道配置管理（密钥、证书、回调地址等）
|
||
- 交易日志与审计
|
||
- 商户进件（通过 API 在上游支付平台注册开通商户，提交资质材料）
|
||
- 商户信息管理（商户信息更新同步、商户状态异常检测与告警）
|
||
- 微信消息通知（商户绑定微信后推送到账通知、异常告警等消息）
|
||
|
||
**不包含（Out of Scope）**：
|
||
- 前端收银台 UI（由下游业务系统自行实现，pay-bridge 仅返回支付凭证）
|
||
- 用户账户体系（不管理用户余额、积分等）
|
||
- 资金清算与结算（由上游支付平台完成）
|
||
- 财务报表（仅提供对账差异数据，财务系统独立建设）
|
||
- 微信/支付宝直连渠道（MVP 阶段通过汇元聚合，后续版本可扩展）
|
||
|
||
---
|
||
|
||
## 2. 用户研究
|
||
|
||
### 2.1 目标用户
|
||
|
||
| 用户角色 | 用户特征 | 使用场景 | 核心痛点 | 期望收益 |
|
||
|---------|---------|---------|---------|---------|
|
||
| 下游业务系统开发者 | 后端开发人员，负责业务系统支付功能对接 | 通过 API 集成支付能力到电商/SaaS/平台系统 | 每对接一个支付渠道都要理解不同协议，签名方式各异，开发周期长 | 统一 API 一次对接，快速集成多种支付方式 |
|
||
| 运营/财务人员 | 负责订单管理和资金核对 | 查看交易状态、处理退款、日常对账 | 各系统交易数据分散，人工对账效率低、易出错 | 统一交易视图，自动对账，差异报告自动生成 |
|
||
| 平台管理员 | 技术运维人员，负责支付系统配置和监控 | 配置支付渠道参数、监控支付系统健康状态 | 渠道配置散落在各系统，变更困难 | 集中管理渠道配置，统一监控 |
|
||
|
||
### 2.2 用户旅程
|
||
|
||
**下游系统开发者接入支付：**
|
||
|
||
```
|
||
[注册接入] → [API 对接] → [联调测试] → [上线运行]
|
||
↓ ↓ ↓ ↓
|
||
获取凭证 阅读文档 沙箱环境 正式环境
|
||
(appId) 调用统一API 模拟支付 真实交易
|
||
↓ ↓ ↓ ↓
|
||
简单快速 清晰易懂 快速验证 稳定可靠
|
||
```
|
||
|
||
**运营人员日常对账：**
|
||
|
||
```
|
||
[查看交易] → [自动对账] → [差异处理] → [确认结果]
|
||
↓ ↓ ↓ ↓
|
||
交易列表 系统自动执行 差异报告 人工确认
|
||
状态查询 T+1 比对 长短款明细 处理闭环
|
||
↓ ↓ ↓ ↓
|
||
一目了然 无需人工 定位精准 安心放心
|
||
```
|
||
|
||
### 2.3 竞品分析
|
||
|
||
| 竞品 | 优势 | 劣势 | 我们的差异化 |
|
||
|-----|-----|-----|-------------|
|
||
| Jeepay（开源聚合支付） | 开源免费，功能完善，社区活跃 | Java 技术栈，部署较重，定制成本高 | Go 实现，轻量高性能，贴合自身业务 |
|
||
| Ping++ | 产品成熟，SDK 丰富，文档完善 | 商业收费，按交易量计价，数据托管于第三方 | 自建自控，无额外费用，数据安全 |
|
||
| 自研直连 | 无中间层开销 | 每套系统重复对接，维护成本高 | 统一网关一次建设多处复用 |
|
||
|
||
---
|
||
|
||
## 3. 功能需求
|
||
|
||
### 3.1 功能概览
|
||
|
||
| 优先级 | 功能模块 | 功能描述 | 用户价值 | MVP |
|
||
|-------|---------|---------|---------|-----|
|
||
| P0 | 统一下单 | 接收支付请求，路由到渠道，返回支付凭证 | 一个 API 发起所有支付方式的交易 | 是 |
|
||
| P0 | 异步通知 | 接收上游回调并通知下游，支持重试 | 业务系统实时获取支付结果 | 是 |
|
||
| P0 | 支付查询 | 按商户订单号或交易号查询状态 | 确认交易结果，处理异常情况 | 是 |
|
||
| P0 | 汇元渠道适配 | 对接汇元支付全渠道（微信/支付宝/快捷） | 首个渠道上线，支持主流支付方式 | 是 |
|
||
| P0 | 签名与加解密 | RSA/MD5 签名 + RSA+3DES 加密 | 保障交易数据安全 | 是 |
|
||
| P1 | 退款 | 全额/部分退款，退款查询 | 支持售后退款业务 | 是 |
|
||
| P1 | 关闭订单 | 超时或主动关闭未支付订单 | 释放渠道资源，保持数据一致 | 是 |
|
||
| P1 | 渠道适配器框架 | 统一渠道接口定义，插件化架构 | 新渠道快速接入 | 是 |
|
||
| P1 | 渠道配置管理 | 商户渠道参数可配置化 | 集中管理，变更便捷 | 是 |
|
||
| P1 | 交易日志 | 完整记录请求/响应/状态变更 | 问题排查，审计追溯 | 是 |
|
||
| P2 | 自动对账 | T+1 拉取账单，自动核对，差异报告 | 降低人工对账成本，保障资金安全 | 否 |
|
||
| P1 | 分润 | 按应用配置分润接收方，订单完成后自动将收款金额分给平台或子商户，支持最大比例限制 | 支持多商户平台分润场景 | 是 |
|
||
| P2 | 开票 | 分润完成后调用上游开票接口（如上游支持） | 合规开票，简化财税流程 | 否 |
|
||
| P1 | 固定账户收款匹配 | 子商户绑定上游开通的固定银行账号，入账时根据金额和备注自动匹配订单 | 支持线下转账场景，自动确认收款 | 是 |
|
||
| P1 | 服务费 | 按应用和支付方式（扫码/对公/余额）配置服务费比例，交易完成后自动扣收至指定子商户 | 灵活收费，支持差异化定价 | 是 |
|
||
| P1 | 商户进件与管理 | 通过 API 在上游平台注册商户、更新信息、监控状态异常 | 自动化商户开通，降低人工成本 | 是 |
|
||
| P1 | 微信消息通知 | 商户绑定微信后推送到账通知、异常告警等消息 | 商户实时掌握经营动态 | 是 |
|
||
| P2 | 渠道路由 | 按规则自动选择最优渠道 | 提升支付成功率，降低成本 | 否 |
|
||
|
||
### 3.2 功能详情
|
||
|
||
#### 3.2.1 统一下单
|
||
|
||
**功能描述**：
|
||
接收下游系统的支付请求，根据支付方式路由到对应支付渠道，调用渠道下单接口，将支付凭证（预支付参数/支付 URL/二维码链接）返回给下游系统。
|
||
|
||
**用户故事**：
|
||
> 作为下游系统开发者，我希望调用一个统一的下单接口并传入支付方式，就能获得对应的支付凭证，以便快速集成支付功能而无需了解底层渠道协议。
|
||
|
||
**功能流程**：
|
||
```
|
||
1. 下游系统发送 POST /api/v1/pay/unified-order（订单号、金额、支付方式、回调地址...）
|
||
2. pay-bridge 校验参数、检查幂等 → 创建本地交易记录
|
||
3. 根据支付方式选择渠道适配器 → 调用汇元支付下单 API
|
||
4. 将渠道返回的支付凭证转换为统一格式 → 返回下游系统
|
||
```
|
||
|
||
**业务规则**：
|
||
- 同一商户订单号重复请求返回已有支付凭证（幂等）
|
||
- 金额以分为单位传入，最小值 1 分
|
||
- 必须指定合法的支付方式（WECHAT_JSAPI/WECHAT_H5/WECHAT_NATIVE/WECHAT_MINI/ALIPAY/QUICK_PAY 等）
|
||
- 订单号由 pay-bridge 按应用维度生成，每个应用独立编码序列，确保唯一且互不干扰
|
||
- 若需分润，下单时必须传入分润金额（profit_sharing_amount），不传则不分润
|
||
- 分润金额不得超过订单金额 × 应用配置的最大分润比例，超出则拒绝下单
|
||
|
||
**验收标准**：
|
||
- [ ] 微信 JSAPI 支付下单成功，返回正确的 prepay_id 等参数
|
||
- [ ] 微信 H5 支付下单成功，返回支付跳转 URL
|
||
- [ ] 微信 Native 支付下单成功，返回二维码链接
|
||
- [ ] 支付宝下单成功，返回支付 URL
|
||
- [ ] 银行卡快捷支付下单成功，返回支付页面 URL
|
||
- [ ] 同一订单号重复请求返回一致结果
|
||
- [ ] 参数校验不通过返回明确错误码和错误信息
|
||
|
||
**边界情况**：
|
||
|
||
| 场景 | 处理方式 |
|
||
|----------------------|--------------------------------------------------|
|
||
| 订单号已存在且已支付 | 返回错误：订单已支付 |
|
||
| 订单号已存在且未支付 | 返回原有支付凭证（幂等） |
|
||
| 渠道下单超时 | 返回系统繁忙，本地记录状态为「下单中」，后续可查询 |
|
||
| 渠道下单失败 | 返回渠道错误信息，本地记录状态为「下单失败」 |
|
||
| 不支持的支付方式 | 返回错误：不支持的支付方式 |
|
||
|
||
#### 3.2.2 异步通知
|
||
|
||
**功能描述**：
|
||
接收上游支付渠道的异步回调通知（支付结果、退款结果），验签后更新本地交易状态，并以统一格式通知下游业务系统。下游通知失败时按策略自动重试。
|
||
|
||
**用户故事**：
|
||
> 作为下游系统开发者，我希望支付完成后自动收到标准格式的通知，以便及时更新业务订单状态，而不需要轮询查询。
|
||
|
||
**功能流程**：
|
||
```
|
||
1. 上游渠道回调 POST /api/v1/notify/payment/:channelCode
|
||
2. pay-bridge 根据渠道类型选择对应验签逻辑 → 验签通过
|
||
3. 解析回调数据，更新本地交易状态（待支付 → 已支付）
|
||
4. 组装统一格式通知 → POST 下游系统回调地址
|
||
5. 下游返回成功 → 标记通知完成；下游失败 → 放入重试队列
|
||
```
|
||
|
||
**业务规则**：
|
||
- 验签失败直接拒绝，返回 fail，记录告警日志
|
||
- 重复回调幂等处理：已处理的交易直接返回 success，不重复通知下游
|
||
- 通知重试策略：15s → 30s → 1m → 5m → 30m → 1h → 6h → 12h，最多 8 次
|
||
- 最终通知失败标记为「通知异常」，等待人工处理或下游主动查询
|
||
|
||
**验收标准**：
|
||
- [ ] 正常回调验签通过，交易状态正确更新
|
||
- [ ] 伪造回调验签失败，返回 fail
|
||
- [ ] 重复回调幂等处理，返回 success 但不重复通知
|
||
- [ ] 下游通知失败触发重试
|
||
- [ ] 重试次数耗尽标记通知异常
|
||
|
||
**边界情况**：
|
||
|
||
| 场景 | 处理方式 |
|
||
|--------------------------------|--------------------------------|
|
||
| 回调对应的本地交易不存在 | 记录告警日志，返回 fail |
|
||
| 下游回调地址不可达 | 进入重试队列 |
|
||
| 同一笔交易收到不同状态的回调 | 按状态机处理，只允许正向流转 |
|
||
|
||
#### 3.2.3 退款
|
||
|
||
**功能描述**：
|
||
接收下游系统的退款请求，校验后调用上游渠道退款接口，跟踪退款状态直至完成。
|
||
|
||
**用户故事**：
|
||
> 作为下游系统开发者，我希望调用退款接口传入原交易号和退款金额，就能发起退款，以便处理售后退款业务。
|
||
|
||
**功能流程**：
|
||
```
|
||
1. 下游系统发送 POST /api/v1/pay/refund（原交易号、退款金额、退款原因）
|
||
2. pay-bridge 校验原交易存在且已支付，退款金额不超过可退金额
|
||
3. 创建退款记录 → 调用汇元退款 API
|
||
4. 返回退款受理结果（退款中）
|
||
5. 渠道退款完成回调 → 更新退款状态 → 通知下游
|
||
```
|
||
|
||
**业务规则**：
|
||
- 支持全额退款和部分退款
|
||
- 退款总金额不超过原交易金额
|
||
- 已全额退款的交易不可再次退款
|
||
- 退款到账时间取决于上游渠道（通常 1-7 个工作日）
|
||
|
||
**验收标准**：
|
||
- [ ] 全额退款请求成功受理
|
||
- [ ] 部分退款请求成功受理，可退金额正确扣减
|
||
- [ ] 超额退款被拒绝
|
||
- [ ] 退款完成后下游系统收到通知
|
||
|
||
**边界情况**：
|
||
|
||
| 场景 | 处理方式 |
|
||
|------------------------|--------------------------------------------|
|
||
| 原交易不存在 | 返回错误：交易不存在 |
|
||
| 原交易未支付 | 返回错误：交易未支付，无法退款 |
|
||
| 退款金额 > 可退金额 | 返回错误：退款金额超限 |
|
||
| 渠道退款接口超时 | 记录「退款中」状态，定时查询渠道退款结果 |
|
||
|
||
#### 3.2.4 分润
|
||
|
||
**功能描述**：
|
||
支付订单完成后，自动将收款金额中的一部分从收款方商户分给平台或另一个子商户。分润接收方在应用接入时按应用维度配置（不同应用可设置不同的分润账户），下单时仅需传入分润金额，系统在订单支付成功后自动调用上游分账接口完成分润，并记录分润流水。
|
||
|
||
**用户故事**：
|
||
> 作为下游系统开发者，我希望在下单时传入分润金额，支付完成后系统自动将指定金额分给预配置的接收方，以便实现平台抽佣或多商户分成，无需额外调用分润接口。
|
||
|
||
**功能流程**：
|
||
```
|
||
1. 应用接入时，管理员为该应用配置分润接收方（平台账户或子商户）及最大分润比例
|
||
2. 下游系统下单时传入 profit_sharing_amount（分润金额）
|
||
3. pay-bridge 校验：分润金额 ≤ 订单金额 × 最大分润比例
|
||
4. 支付成功回调到达后，自动调用上游分账接口（传入接收方和金额）
|
||
5. 上游分账完成回调 → 更新分润状态 → 记录分润流水
|
||
6. 若上游支持开票接口 → 触发开票流程
|
||
```
|
||
|
||
**业务规则**：
|
||
- 分润接收方按应用维度配置（不同应用可配不同的分润账户），下单时无需指定接收方
|
||
- 下单时必须显式传入分润金额，不传则不触发分润
|
||
- 分润金额不得超过订单金额 × 最大分润比例（比例在应用配置中设置）
|
||
- 分润在支付成功后自动执行，无需下游系统二次调用
|
||
- 每笔分润生成独立流水记录，可查询和对账
|
||
- 退款时需判断是否已分润：已分润需先调用分账回退再退款（待确认）
|
||
|
||
**验收标准**：
|
||
- [ ] 应用级配置分润接收方和最大比例成功
|
||
- [ ] 下单传入合法分润金额，订单创建成功
|
||
- [ ] 下单传入超限分润金额，返回明确错误
|
||
- [ ] 支付完成后自动触发分润，上游分账接口调用成功
|
||
- [ ] 分润完成后流水记录正确生成
|
||
- [ ] 分润流水纳入对账体系，差异可识别
|
||
- [ ] 未传分润金额的订单，支付完成后不触发分润
|
||
|
||
**边界情况**：
|
||
|
||
| 场景 | 处理方式 |
|
||
|------------------------|--------------------------------------------------------------|
|
||
| 分润金额超过最大比例 | 下单时直接拒绝，返回错误 |
|
||
| 上游分账接口调用失败 | 重试 + 告警，标记分润状态为「分润中」，定时补偿 |
|
||
| 分润接收方未配置 | 下单时传入分润金额则拒绝，提示先配置分润接收方 |
|
||
| 已分润订单发起退款 | 需先回退分润再执行退款（待确认） |
|
||
| 上游不支持分账 | 下单时传入分润金额则拒绝，提示当前渠道不支持分润 |
|
||
|
||
#### 3.2.5 开票
|
||
|
||
**功能描述**：
|
||
分润完成后，若上游渠道提供开票接口，系统自动或按需调用开票接口完成开票操作。
|
||
|
||
**用户故事**：
|
||
> 作为运营/财务人员，我希望分润完成后系统能自动开票，以便简化财税流程、满足合规要求。
|
||
|
||
**功能流程**：
|
||
```
|
||
1. 分润完成 → 检查上游渠道是否支持开票接口
|
||
2. 支持 → 调用上游开票接口（传入分润流水信息）
|
||
3. 上游返回开票结果 → 记录开票状态
|
||
4. 开票失败 → 告警，等待人工处理或重试
|
||
```
|
||
|
||
**业务规则**：
|
||
- 开票依赖上游渠道能力，仅在渠道支持开票接口时可用
|
||
- 开票类型和税目由上游渠道决定（待确认）
|
||
- 开票记录关联对应的分润流水
|
||
- 开票失败不影响分润结果，独立告警处理
|
||
|
||
**验收标准**：
|
||
- [ ] 上游支持开票时，分润完成后自动触发开票
|
||
- [ ] 上游不支持开票时，跳过开票流程，不报错
|
||
- [ ] 开票结果正确记录，可查询
|
||
- [ ] 开票失败产生告警
|
||
|
||
**边界情况**：
|
||
|
||
| 场景 | 处理方式 |
|
||
|----------------------------|------------------|
|
||
| 上游不支持开票 | 静默跳过，不报错 |
|
||
| 开票接口超时 | 重试 + 告警 |
|
||
| 开票金额与分润金额不一致 | 告警，人工确认 |
|
||
|
||
#### 3.2.6 自动对账
|
||
|
||
**功能描述**：
|
||
T+1 日自动从上游渠道下载前一天交易账单，与本地交易记录逐笔核对，生成对账差异报告。
|
||
|
||
**用户故事**：
|
||
> 作为运营/财务人员，我希望系统每天自动完成对账并输出差异报告，以便快速发现和处理资金异常。
|
||
|
||
**功能流程**：
|
||
```
|
||
1. 每日凌晨定时任务触发（如 02:00）
|
||
2. 调用汇元账单下载接口，拉取 T-1 日交易明细
|
||
3. 解析账单数据（CSV/Excel 格式）
|
||
4. 逐笔与本地交易记录比对（交易号、金额、状态）
|
||
5. 生成对账报告：匹配数、长款、短款、金额不一致
|
||
6. 差异记录入库，推送告警通知
|
||
```
|
||
|
||
**业务规则**：
|
||
- 对账周期：T+1，每日凌晨执行
|
||
- 比对维度：渠道交易号、金额（精确到分）、交易状态
|
||
- 差异分类：长款（上游有本地无）、短款（本地有上游无）、金额不一致
|
||
- 账单下载失败重试 3 次，仍失败则告警
|
||
|
||
**验收标准**：
|
||
- [ ] 定时任务按时触发，成功下载上游账单
|
||
- [ ] 对账结果准确：正常交易匹配、差异正确识别
|
||
- [ ] 差异报告包含详细信息（交易号、上游金额、本地金额、差异类型）
|
||
- [ ] 账单下载失败时重试并告警
|
||
|
||
**边界情况**：
|
||
|
||
| 场景 | 处理方式 |
|
||
|----------------------------|----------------------------|
|
||
| 当日无交易 | 标记对账完成，差异为 0 |
|
||
| 账单格式变更 | 解析失败告警，人工介入 |
|
||
| 对账任务执行中服务重启 | 支持断点续对或重新执行 |
|
||
|
||
#### 3.2.7 固定账户收款匹配
|
||
|
||
**功能描述**：
|
||
支持子商户使用上游支付渠道（如汇元支付）为其开通的固定银行账号收款。客户向该固定账号转账付款后，上游渠道将入账通知推送给 pay-bridge，系统根据入账金额、转账备注和付款方账户名称自动匹配待支付订单，完成订单支付确认。
|
||
|
||
**用户故事**：
|
||
> 作为子商户运营人员，我希望客户可以直接向上游开通的固定银行账号转账，系统自动识别并匹配对应订单完成收款确认，以便省去逐笔人工核对付款的工作。
|
||
|
||
**功能流程**：
|
||
```
|
||
1. 上游渠道为子商户开通固定收款银行账号
|
||
2. 管理员在 pay-bridge 中录入子商户的固定收款账号信息（关联 app_id）
|
||
3. 下游系统创建待支付订单（包含金额、备注等匹配要素）
|
||
4. 客户向子商户固定银行账号转账，备注中携带订单相关标识
|
||
5. 上游渠道检测到入账 → 推送入账通知给 pay-bridge
|
||
6. pay-bridge 自动匹配引擎根据「金额 + 备注 + 付款方名称」在该子商户的待支付订单中匹配
|
||
7. 匹配成功 → 更新订单状态为已支付 → 通知下游系统
|
||
8. 匹配失败 → 记录未匹配入账，标记为待人工确认
|
||
```
|
||
|
||
**匹配规则**：
|
||
- **备注优先匹配**：解析转账备注中的订单号或关键字，精确匹配待支付订单
|
||
- **金额辅助匹配**：备注匹配成功后，校验入账金额与订单金额是否一致
|
||
- **付款方名称匹配**：将转入方的账户名称与订单的开票名称进行一致性比对，名称一致则提升匹配置信度，名称不一致时标记差异但不阻断匹配
|
||
- **单一匹配原则**：一笔入账只能匹配一个订单，一个订单只能被一笔入账匹配
|
||
- **匹配时间窗口**：仅匹配指定时间范围内（如 7 天内）的待支付订单
|
||
|
||
**业务规则**：
|
||
- 固定收款账号由上游支付渠道开通和管理，pay-bridge 仅记录账号信息用于关联匹配
|
||
- 每个子商户可绑定一个或多个固定收款账号
|
||
- 入账通知由上游渠道主动推送，pay-bridge 接收后触发匹配流程
|
||
- 匹配成功后的订单走正常支付完成流程（通知下游、记录流水等）
|
||
- 未匹配的入账记录保留，支持人工手动关联订单
|
||
- 当备注和金额匹配成功但付款方名称与开票名称不一致时，匹配成功但标记「名称差异」，供人工复核
|
||
- 同一金额和备注若匹配到多个订单，可通过付款方名称与开票名称一致性进一步缩小范围；仍无法唯一确定时，标记为待人工确认
|
||
|
||
**验收标准**：
|
||
- [ ] 子商户固定收款账号信息录入和查询成功
|
||
- [ ] 收到上游入账通知后，备注中包含有效订单号时自动匹配成功
|
||
- [ ] 匹配成功后订单状态正确更新为已支付，下游系统收到通知
|
||
- [ ] 备注无法解析或金额不一致时，标记为待人工确认
|
||
- [ ] 同金额多订单场景正确标记为待人工确认
|
||
- [ ] 未匹配入账记录可查询，支持手动关联
|
||
- [ ] 付款方名称与开票名称一致时，匹配置信度提升
|
||
- [ ] 付款方名称与开票名称不一致时，匹配成功但标记名称差异
|
||
- [ ] 多订单同金额场景下，付款方名称可辅助缩小匹配范围
|
||
- [ ] 超出匹配时间窗口的订单不参与自动匹配
|
||
|
||
**边界情况**：
|
||
|
||
| 场景 | 处理方式 |
|
||
|----------------------------------|--------------------------------------------------|
|
||
| 备注为空或无法解析 | 仅按金额尝试匹配，若唯一匹配则成功，否则待人工确认 |
|
||
| 入账金额与订单金额不一致 | 匹配失败，标记待人工确认 |
|
||
| 同一金额存在多个待支付订单 | 依赖备注和付款方名称区分，无法区分时待人工确认 |
|
||
| 付款方名称与开票名称不一致 | 备注和金额匹配成功则匹配成功，但标记「名称差异」供复核 |
|
||
| 订单未填写开票名称 | 跳过名称匹配维度，仅依赖备注和金额匹配 |
|
||
| 同一订单收到重复入账通知 | 幂等处理，已匹配的订单不再重复匹配 |
|
||
| 子商户未录入固定收款账号 | 入账通知无法关联子商户，记录告警 |
|
||
| 上游入账通知延迟 | 订单若已超时关闭，入账标记为待人工处理 |
|
||
|
||
#### 3.2.8 服务费
|
||
|
||
**功能描述**：
|
||
按应用维度配置服务费收取规则，支持根据不同支付方式（扫码支付、对公转账、余额支付）设置不同的服务费比例，并指定服务费收款的子商户。交易完成后，系统自动从收款金额中计算服务费，通过上游分账能力将服务费划转至指定子商户。
|
||
|
||
**用户故事**：
|
||
> 作为平台管理员，我希望为每个应用配置不同支付方式的服务费比例，并指定服务费的收款子商户，以便平台能按交易自动收取手续费，实现差异化定价。
|
||
|
||
**功能流程**：
|
||
```
|
||
1. 管理员为应用配置服务费规则（支付方式 → 费率 → 收款子商户）
|
||
2. 下游系统发起支付交易，pay-bridge 记录该订单适用的服务费规则
|
||
3. 交易支付成功后，系统根据订单金额和对应支付方式的费率计算服务费
|
||
4. 调用上游分账接口，将服务费从收款方划转至指定收款子商户
|
||
5. 记录服务费流水，纳入对账体系
|
||
```
|
||
|
||
**业务规则**：
|
||
- 服务费按应用维度配置，每个应用可独立设置不同支付方式的费率
|
||
- 支持的支付方式分类：扫码支付（微信/支付宝扫码）、对公转账（固定账户银行转账）、余额支付
|
||
- 每种支付方式可单独配置费率（百分比），未配置的支付方式默认不收取服务费
|
||
- 服务费收款方为指定的子商户（通过子商户 ID 配置），每个应用可指定不同的收款子商户
|
||
- 服务费在交易完成后自动扣收，无需下游系统额外操作
|
||
- 服务费通过上游分账能力实现划转，与分润流程共用分账通道
|
||
- 服务费金额 = 订单金额 × 对应支付方式费率，精确到分（四舍五入）
|
||
- 当订单同时存在分润和服务费时，分润和服务费分别计算，分账总金额不得超过订单金额
|
||
- 退款时需同步回退已收取的服务费
|
||
|
||
**验收标准**：
|
||
- [ ] 按应用和支付方式配置服务费比例成功
|
||
- [ ] 配置服务费收款子商户成功
|
||
- [ ] 扫码支付交易完成后，按扫码费率自动扣收服务费
|
||
- [ ] 对公转账交易完成后，按对公费率自动扣收服务费
|
||
- [ ] 余额支付交易完成后，按余额费率自动扣收服务费
|
||
- [ ] 未配置费率的支付方式不扣收服务费
|
||
- [ ] 服务费流水记录正确生成，可查询
|
||
- [ ] 服务费纳入对账体系，差异可识别
|
||
- [ ] 分润和服务费同时存在时，分账总额正确，不超过订单金额
|
||
- [ ] 退款时服务费正确回退
|
||
|
||
**边界情况**：
|
||
|
||
| 场景 | 处理方式 |
|
||
|----------------------------------------|--------------------------------------------------------|
|
||
| 应用未配置服务费规则 | 不扣收服务费，正常完成支付 |
|
||
| 支付方式未配置费率 | 该支付方式不扣收服务费 |
|
||
| 服务费收款子商户未配置 | 服务费规则不生效，记录告警 |
|
||
| 服务费 + 分润总额超过订单金额 | 下单时校验拒绝，提示费用配置冲突 |
|
||
| 上游分账接口调用失败 | 重试 + 告警，标记服务费状态为「扣收中」，定时补偿 |
|
||
| 退款时服务费已扣收 | 先回退服务费再执行退款 |
|
||
| 费率配置为 0 | 等同于不收取，不产生分账操作 |
|
||
| 订单金额过小导致服务费不足 1 分 | 服务费为 0，不产生分账操作 |
|
||
|
||
#### 3.2.9 商户进件与管理
|
||
|
||
**功能描述**：
|
||
通过 API 在上游支付平台（如汇元支付）注册开通商户，提交营业执照、法人信息等资质材料，跟踪审核状态。支持商户信息变更后同步更新到上游平台，并定期检测商户状态异常（审核失败、冻结、资质过期等），及时告警。
|
||
|
||
**用户故事**：
|
||
> 作为平台管理员，我希望通过管理后台提交商户资质即可自动完成上游平台的商户开通，并在商户状态异常时第一时间收到告警，以便高效管理大批量商户。
|
||
|
||
**功能流程**：
|
||
```
|
||
【进件流程】
|
||
1. 管理员在后台填写商户资质信息（营业执照、法人身份证、银行账户等）
|
||
2. pay-bridge 调用上游进件 API 提交资质 → 记录进件申请
|
||
3. 上游平台审核 → 审核结果回调或定时查询
|
||
4. 审核通过 → 更新商户状态为「已开通」，记录上游商户 ID
|
||
5. 审核失败 → 记录失败原因，通知管理员修改后重新提交
|
||
|
||
【更新流程】
|
||
1. 管理员修改商户信息（银行账户、联系方式等）
|
||
2. pay-bridge 调用上游商户更新 API 同步变更
|
||
3. 上游返回结果 → 更新本地记录
|
||
|
||
【异常检测】
|
||
1. 定时任务轮询上游商户状态接口（或接收上游回调）
|
||
2. 检测到异常（冻结、资质过期、风控限制等）→ 更新本地状态 → 触发告警
|
||
```
|
||
|
||
**业务规则**：
|
||
- 进件资质字段由上游平台要求决定，pay-bridge 做必要的格式校验后透传
|
||
- 同一商户不可重复进件，需先查询是否已存在
|
||
- 审核状态支持：待提交、审核中、已通过、已驳回、已冻结
|
||
- 商户信息更新仅允许上游平台支持修改的字段
|
||
- 异常检测周期可配置（默认每日一次）
|
||
- 商户状态异常时，关联该商户的支付能力自动受限（告警但不自动停止交易，由管理员决定）
|
||
|
||
**验收标准**：
|
||
- [ ] 提交进件申请成功，上游平台收到资质信息
|
||
- [ ] 审核通过后商户状态正确更新，上游商户 ID 正确记录
|
||
- [ ] 审核失败时失败原因完整记录，可重新提交
|
||
- [ ] 商户信息更新成功同步到上游平台
|
||
- [ ] 定时检测发现商户异常时产生告警
|
||
- [ ] 商户列表可查询，支持按状态筛选
|
||
|
||
**边界情况**：
|
||
|
||
| 场景 | 处理方式 |
|
||
|------------------------------|--------------------------------------------------|
|
||
| 上游进件 API 超时 | 重试 + 记录「提交中」状态，定时查询结果 |
|
||
| 重复提交同一商户 | 返回错误，提示商户已存在 |
|
||
| 上游审核回调延迟 | 定时主动查询审核状态补偿 |
|
||
| 商户资质过期 | 异常检测发现后告警，提示管理员更新资质 |
|
||
| 上游平台不支持信息修改 | 返回错误，提示该字段不可修改 |
|
||
|
||
#### 3.2.10 微信消息通知
|
||
|
||
**功能描述**：
|
||
商户通过扫码绑定微信账号后，系统在关键业务事件发生时（支付到账、退款完成、商户异常、对账差异等）通过微信推送消息通知，使商户实时掌握经营动态。
|
||
|
||
**用户故事**：
|
||
> 作为子商户，我希望绑定微信后能收到每笔到账通知和异常告警，以便随时了解收款情况，无需频繁登录后台查看。
|
||
|
||
**功能流程**：
|
||
```
|
||
【绑定流程】
|
||
1. 商户在管理后台获取微信绑定二维码（关联商户 ID）
|
||
2. 商户用微信扫码 → 关注公众号/进入小程序 → 完成绑定授权
|
||
3. pay-bridge 记录商户与微信 openid 的绑定关系
|
||
|
||
【消息推送】
|
||
1. 业务事件触发（支付到账、退款、异常等）
|
||
2. 查询该商户是否已绑定微信
|
||
3. 已绑定 → 组装消息模板 → 调用微信模板消息/订阅消息接口推送
|
||
4. 推送失败 → 记录失败日志，支持重试
|
||
```
|
||
|
||
**消息类型**：
|
||
|
||
| 消息类型 | 触发时机 | 消息内容 |
|
||
|---------|---------|---------|
|
||
| 到账通知 | 订单支付成功 | 商户名称、订单金额、支付方式、到账时间 |
|
||
| 退款通知 | 退款完成 | 商户名称、退款金额、原订单号、退款时间 |
|
||
| 分润通知 | 分润完成 | 分润金额、关联订单号、接收方 |
|
||
| 异常告警 | 商户状态异常 | 异常类型、商户名称、处理建议 |
|
||
| 对账差异 | 发现对账差异 | 差异类型、涉及金额、差异笔数 |
|
||
|
||
**业务规则**：
|
||
- 每个商户可绑定一个或多个微信账号接收通知
|
||
- 商户可自行选择开启/关闭特定消息类型
|
||
- 微信消息推送依赖公众号或小程序的模板消息能力
|
||
- 消息推送失败不影响主业务流程，独立重试
|
||
- 商户可随时解绑微信
|
||
|
||
**验收标准**：
|
||
- [ ] 商户扫码绑定微信成功，绑定关系正确记录
|
||
- [ ] 支付到账后商户微信收到到账通知
|
||
- [ ] 退款完成后商户微信收到退款通知
|
||
- [ ] 商户异常时微信收到告警消息
|
||
- [ ] 商户可解绑微信，解绑后不再收到消息
|
||
- [ ] 消息推送失败时记录日志，不影响主流程
|
||
|
||
**边界情况**：
|
||
|
||
| 场景 | 处理方式 |
|
||
|----------------------------|--------------------------------------------|
|
||
| 商户未绑定微信 | 跳过推送，不报错 |
|
||
| 微信推送接口超时 | 记录失败，异步重试 |
|
||
| 模板消息额度耗尽 | 记录告警，降级为不推送 |
|
||
| 商户绑定多个微信 | 所有绑定的微信均收到通知 |
|
||
| 高频交易产生大量消息 | 支持消息聚合（如每 N 分钟汇总一次到账通知）|
|
||
|
||
---
|
||
|
||
## 4. 非功能需求
|
||
|
||
### 4.1 性能需求
|
||
|
||
| 场景 | 指标 | 目标值 | 测量方法 |
|
||
|-----|-----|-------|---------|
|
||
| 统一下单 API | P95 延迟 | < 500ms（含渠道调用） | 链路追踪 + 监控 |
|
||
| 支付查询 API | P95 延迟 | < 100ms | APM 监控 |
|
||
| 异步通知处理 | 处理延迟 | < 1s（从收到回调到通知下游） | 日志时间戳 |
|
||
| 并发能力 | QPS | ≥ 500（下单接口） | 压测 |
|
||
| 数据量 | 交易表单表记录 | 支持千万级 | 数据库监控 |
|
||
|
||
### 4.2 可用性需求
|
||
|
||
- 系统可用性：99.9%（全年停机 < 8.76 小时）
|
||
- 计划内维护窗口：凌晨 03:00-05:00
|
||
- 故障恢复时间（RTO）：< 30 分钟
|
||
- 数据恢复点（RPO）：0（事务数据不可丢失）
|
||
|
||
### 4.3 安全需求
|
||
|
||
| 类别 | 需求 | 优先级 |
|
||
|-----|-----|-------|
|
||
| 认证 | 下游系统通过 appId + appSecret 鉴权，签名校验每次请求 | P0 |
|
||
| 授权 | 不同下游系统隔离，只能操作自己的交易 | P0 |
|
||
| 数据安全 | 敏感信息（密钥、证书）加密存储；传输使用 HTTPS；日志脱敏 | P0 |
|
||
| 审计日志 | 完整记录每笔交易的请求/响应/状态变更，保留 ≥ 3 年 | P1 |
|
||
| 合规要求 | 符合支付行业安全规范，不存储银行卡号等敏感信息 | P0 |
|
||
|
||
### 4.4 兼容性需求
|
||
|
||
> pay-bridge 作为后端服务，不直接面向终端用户，兼容性主要体现在 API 层面。
|
||
|
||
**API 兼容性**：
|
||
- RESTful API，JSON 格式
|
||
- 支持 HTTP/1.1 和 HTTP/2
|
||
- API 版本化（/api/v1/），向前兼容
|
||
|
||
**上游渠道兼容**：
|
||
- 汇元支付开放平台 API（首期）
|
||
- 预留微信支付直连、支付宝直连接口扩展
|
||
|
||
---
|
||
|
||
## 5. 数据需求
|
||
|
||
### 5.1 数据模型
|
||
|
||
> 描述核心数据实体及其关系
|
||
|
||
| 实体 | 描述 | 关键字段 |
|
||
|-----|-----|---------|
|
||
| 交易订单（trade_order） | 每笔支付交易的核心记录 | trade_no, merchant_order_no, app_id, channel_code, pay_method, amount, status, notify_url |
|
||
| 退款记录（refund_order） | 退款请求和结果 | refund_no, trade_no, refund_amount, status, reason |
|
||
| 渠道配置（channel_config） | 支付渠道的商户参数 | channel_code, merchant_id, api_key, private_key, cert_path, notify_url, sandbox |
|
||
| 通知记录（notify_log） | 下游通知发送记录 | trade_no, notify_url, status, retry_count, next_retry_time, response |
|
||
| 对账记录（reconciliation） | 每日对账任务和结果 | recon_date, channel_code, status, match_count, long_count, short_count, diff_count |
|
||
| 对账差异（recon_diff） | 对账差异明细 | recon_date, trade_no, diff_type, local_amount, channel_amount |
|
||
| 分润配置（profit_sharing_config） | 应用级分润接收方配置（不同应用可配不同分润账户） | app_id, receiver_merchant_id, receiver_type(platform/sub_merchant), max_sharing_ratio, status |
|
||
| 订单编码序列（order_sequence） | 按应用隔离的订单号生成序列 | app_id, sequence_type(trade/refund/sharing), current_value, prefix, step |
|
||
| 分润记录（profit_sharing_order） | 每笔分润请求和结果 | sharing_no, trade_no, receiver_merchant_id, sharing_amount, status, channel_sharing_no |
|
||
| 分润流水（profit_sharing_log） | 分润操作流水明细 | log_id, sharing_no, action(split/rollback), amount, status, created_at |
|
||
| 开票记录（invoice） | 开票请求和结果 | invoice_no, sharing_no, invoice_type, amount, status, channel_invoice_no |
|
||
| 子商户收款账户（sub_merchant_account） | 上游渠道为子商户开通的固定收款银行账号 | account_id, app_id, sub_merchant_id, channel_code, account_type, account_no, account_name, status |
|
||
| 收款匹配记录（payment_match_log） | 固定账户入账自动匹配的执行记录 | match_id, account_id, trade_no, incoming_amount, incoming_remark, match_status(matched/pending_manual/failed), match_time, operator |
|
||
| 服务费配置（service_fee_config） | 应用级服务费规则，按支付方式设置费率 | config_id, app_id, pay_method(scan/transfer/balance), fee_rate, fee_receiver_merchant_id, status |
|
||
| 服务费流水（service_fee_log） | 每笔服务费扣收/回退记录 | log_id, trade_no, config_id, fee_amount, fee_rate, receiver_merchant_id, action(charge/rollback), status, created_at |
|
||
| 商户（merchant） | 商户基本信息和上游平台状态 | merchant_id, merchant_name, license_no, legal_person, bank_account, channel_merchant_id, status(pending/active/frozen/rejected), created_at |
|
||
| 商户进件记录（merchant_application） | 商户进件申请和审核记录 | application_id, merchant_id, channel_code, submit_data, audit_status, reject_reason, submitted_at, audited_at |
|
||
| 微信绑定（wechat_binding） | 商户与微信账号绑定关系 | binding_id, merchant_id, openid, union_id, nickname, notify_types, status, bindtime |
|
||
| 微信消息记录（wechat_message_log） | 微信消息推送记录 | log_id, merchant_id, openid, msg_type, content, send_status, retry_count, created_at |
|
||
| 接入应用（app） | 下游系统接入凭证 | app_id, app_secret, app_name, status |
|
||
|
||
### 5.2 数据采集
|
||
|
||
| 数据点 | 采集时机 | 用途 | 保留期限 |
|
||
|-------|---------|-----|---------|
|
||
| 交易请求/响应报文 | 每次 API 调用 | 问题排查、审计 | 3 年 |
|
||
| 交易状态变更 | 状态每次流转 | 交易追踪、异常监控 | 3 年 |
|
||
| 渠道调用日志 | 每次调用上游渠道 | 渠道问题排查 | 1 年 |
|
||
| 对账结果 | 每日对账完成 | 资金核对 | 5 年 |
|
||
| 分润操作流水 | 每次分润执行/回退 | 分润追踪、对账 | 3 年 |
|
||
| 开票请求/结果 | 每次开票操作 | 财税合规、审计 | 5 年 |
|
||
| 固定账户入账通知 | 收到上游入账推送 | 收款匹配追踪 | 3 年 |
|
||
| 收款匹配结果 | 每次匹配执行 | 匹配准确率分析、人工处理 | 3 年 |
|
||
| 服务费扣收/回退 | 每次服务费操作 | 服务费追踪、对账 | 3 年 |
|
||
| 商户进件/审核 | 每次进件提交和审核结果 | 商户管理、合规审计 | 5 年 |
|
||
| 商户状态变更 | 状态每次流转 | 异常检测、告警追踪 | 3 年 |
|
||
| 微信消息推送 | 每次消息发送 | 推送成功率分析 | 1 年 |
|
||
| 通知发送记录 | 每次通知下游 | 通知问题排查 | 1 年 |
|
||
|
||
### 5.3 数据报表
|
||
|
||
| 报表名称 | 维度 | 指标 | 更新频率 |
|
||
|---------|-----|-----|---------|
|
||
| 交易汇总 | 日期 / 渠道 / 支付方式 / 下游应用 | 交易笔数、金额、成功率 | 实时 |
|
||
| 退款汇总 | 日期 / 渠道 / 下游应用 | 退款笔数、金额 | 实时 |
|
||
| 对账报告 | 日期 / 渠道 | 匹配数、长款、短款、差异金额 | 每日 |
|
||
| 分润汇总 | 日期 / 渠道 / 下游应用 | 分润笔数、分润金额、成功率 | 实时 |
|
||
| 开票汇总 | 日期 / 渠道 | 开票笔数、开票金额、成功率 | 实时 |
|
||
| 收款匹配汇总 | 日期 / 子商户 / 账户 | 入账笔数、自动匹配数、人工处理数、匹配率 | 实时 |
|
||
| 服务费汇总 | 日期 / 应用 / 支付方式 | 服务费笔数、服务费总额、回退金额 | 实时 |
|
||
| 商户进件统计 | 日期 / 渠道 / 状态 | 申请数、通过数、驳回数、通过率 | 实时 |
|
||
| 商户异常报告 | 日期 / 异常类型 | 异常商户数、异常类型分布 | 每日 |
|
||
| 微信消息推送率 | 日期 / 消息类型 | 推送总数、成功数、失败数 | 实时 |
|
||
| 通知成功率 | 日期 / 下游应用 | 通知总数、成功数、失败数、重试数 | 实时 |
|
||
|
||
---
|
||
|
||
## 6. 技术方案
|
||
|
||
### 6.1 系统架构
|
||
|
||
> pay-bridge 采用分层架构，核心为渠道适配器模式
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 下游业务系统 │
|
||
│ (电商 / SaaS / 多商户平台) │
|
||
└──────────────────┬──────────────────────────────┘
|
||
│ 统一支付 API (REST/JSON)
|
||
┌──────────────────▼──────────────────────────────┐
|
||
│ pay-bridge 支付网关 │
|
||
│ ┌───────────┬──────────┬──────────┬──────────┐ │
|
||
│ │ API 层 │ 业务层 │ 渠道层 │ 任务层 │ │
|
||
│ │ 鉴权/路由 │ 交易管理 │ 适配器框架 │ 对账/通知 │ │
|
||
│ │ 参数校验 │ 状态机 │ 签名加密 │ 定时任务 │ │
|
||
│ └───────────┴──────────┴──────────┴──────────┘ │
|
||
└──────────────────┬──────────────────────────────┘
|
||
│ 渠道协议 (各渠道私有)
|
||
┌──────────────────▼──────────────────────────────┐
|
||
│ 上游支付渠道 │
|
||
│ 汇元支付 │ (微信直连) │ (支付宝直连) │ ... │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**后端**：
|
||
- 语言/框架：Go 1.25+
|
||
- 数据库：MySQL 8.0（交易数据）
|
||
- 缓存：Redis（幂等控制、分布式锁、通知重试队列）
|
||
- 消息队列：Redis Stream 或 RabbitMQ（异步通知、对账任务）
|
||
|
||
**基础设施**：
|
||
- 部署方式：Docker 容器化，支持水平扩展
|
||
- 监控告警：Prometheus + Grafana（指标监控）；告警通知（钉钉/企微/邮件）
|
||
- 日志系统：结构化日志（JSON），支持 ELK 或 Loki 接入
|
||
|
||
### 6.2 第三方依赖
|
||
|
||
| 服务类型 | 服务商 | 用途 | 备选方案 |
|
||
|---------|-------|-----|---------|
|
||
| 聚合支付 | 汇元支付（HePay） | 首期上游支付渠道，提供微信/支付宝/快捷支付 | 微信/支付宝直连 |
|
||
| 数据库 | MySQL | 交易数据持久化 | PostgreSQL |
|
||
| 缓存 | Redis | 幂等控制、分布式锁、消息队列 | - |
|
||
|
||
### 6.3 接口设计
|
||
|
||
#### 应用调用接口
|
||
|
||
> 下游业务系统调用，通过 appId + appSecret 签名鉴权
|
||
|
||
| 接口 | 方法 | 描述 |
|
||
|-----|-----|-----|
|
||
| /api/v1/pay/unified-order | POST | 统一下单，返回支付凭证 |
|
||
| /api/v1/pay/query/:tradeNo | GET | 查询交易状态 |
|
||
| /api/v1/pay/close | POST | 关闭未支付订单 |
|
||
| /api/v1/pay/refund | POST | 发起退款 |
|
||
| /api/v1/pay/refund/query/:refundNo | GET | 查询退款状态 |
|
||
| /api/v1/pay/profit-sharing/query/:sharingNo | GET | 查询分润结果 |
|
||
| /api/v1/pay/profit-sharing/rollback | POST | 分润回退（退款前置操作） |
|
||
| /api/v1/pay/invoice/query/:invoiceNo | GET | 查询开票结果 |
|
||
| /api/v1/wechat/bindQrcode/:merchantId | GET | 获取商户微信绑定二维码 |
|
||
| /api/v1/wechat/bindCallback | POST | 微信绑定授权回调 |
|
||
| /api/v1/wechat/bindStatus/:merchantId | GET | 查询商户微信绑定状态 |
|
||
| /api/v1/wechat/unbind | POST | 解绑商户微信 |
|
||
|
||
#### 上游回调接口
|
||
|
||
> 接收上游支付渠道异步通知，通过渠道验签鉴权
|
||
|
||
| 接口 | 方法 | 描述 |
|
||
|-----|-----|-----|
|
||
| /api/v1/notify/payment/:channelCode | POST | 接收上游支付结果回调 |
|
||
| /api/v1/notify/refund/:channelCode | POST | 接收上游退款结果回调 |
|
||
| /api/v1/notify/account-payment/:channelCode | POST | 接收上游固定账户入账通知 |
|
||
| /api/v1/notify/merchant-audit/:channelCode | POST | 接收上游商户审核结果回调 |
|
||
|
||
#### 管理后台接口
|
||
|
||
> 内部管理系统调用，通过后台登录态 / Token 鉴权
|
||
|
||
| 接口 | 方法 | 描述 |
|
||
|-----|-----|-----|
|
||
| /api/v1/admin/channel | POST/GET | 渠道配置管理 |
|
||
| /api/v1/admin/profit-sharing/config | POST/GET | 分润接收方配置管理 |
|
||
| /api/v1/admin/service-fee/config | POST/GET/PUT | 服务费配置管理（按应用和支付方式） |
|
||
| /api/v1/admin/service-fee/logs | GET | 查询服务费流水 |
|
||
| /api/v1/admin/sub-merchant/account | POST/GET | 子商户固定收款账户管理 |
|
||
| /api/v1/admin/payment-match/list | GET | 查询收款匹配记录（含待人工确认） |
|
||
| /api/v1/admin/payment-match/bindOrder | POST | 手动关联入账与订单 |
|
||
| /api/v1/admin/merchant/apply | POST | 提交商户进件申请 |
|
||
| /api/v1/admin/merchant/list | GET | 查询商户列表（支持状态筛选） |
|
||
| /api/v1/admin/merchant/:merchantId | GET/PUT | 查询/更新商户信息 |
|
||
| /api/v1/admin/merchant/audit-status/:merchantId | GET | 查询商户进件审核状态 |
|
||
| /api/v1/admin/merchant/anomalies | GET | 查询商户异常列表 |
|
||
| /api/v1/admin/reconciliation/trigger | POST | 手动触发对账 |
|
||
| /api/v1/admin/reconciliation/report | GET | 查询对账报告 |
|
||
|
||
---
|
||
|
||
## 7. 发布计划
|
||
|
||
### 7.1 版本规划
|
||
|
||
| 版本 | 目标 | 核心功能 | 预计时间 |
|
||
|-----|-----|---------|---------|
|
||
| MVP (v0.1) | 跑通核心支付流程 | 统一下单 + 支付查询 + 异步通知 + 汇元渠道适配（微信/支付宝） | - |
|
||
| v0.2 | 完善交易管理 | 退款 + 关单 + 银行卡快捷支付 + 交易日志 | - |
|
||
| v1.0 | 正式上线 | 渠道配置管理 + 对账 + 分账 + 渠道路由 + 完整文档 | - |
|
||
| v1.x | 持续迭代 | 新渠道接入（微信/支付宝直连）+ 管理后台 + 数据报表 | - |
|
||
|
||
### 7.2 里程碑
|
||
|
||
| 里程碑 | 计划时间 | 实际时间 | 状态 | 备注 |
|
||
|-------|---------|---------|-----|-----|
|
||
| 需求评审通过 | - | | 待开始 | |
|
||
| 技术方案确定 | - | | 待开始 | 确定框架、数据库、部署方案 |
|
||
| MVP 开发完成 | - | | 待开始 | 核心支付流程可用 |
|
||
| MVP 联调测试 | - | | 待开始 | 汇元沙箱环境联调 |
|
||
| v1.0 开发完成 | - | | 待开始 | 全功能开发完成 |
|
||
| v1.0 上线发布 | - | | 待开始 | 正式环境上线 |
|
||
|
||
### 7.3 灰度策略
|
||
|
||
1. **沙箱验证**：先在汇元支付沙箱环境完成全流程联调
|
||
2. **内部灰度**：选择一个内部业务系统（低流量）首先接入，验证线上稳定性
|
||
3. **逐步放量**：确认稳定后，逐步接入其他业务系统
|
||
4. **全量上线**：所有业务系统切换到 pay-bridge
|
||
|
||
---
|
||
|
||
## 8. 风险管理
|
||
|
||
### 8.1 风险识别
|
||
|
||
| 风险 | 类型 | 可能性 | 影响 | 应对措施 | 负责人 |
|
||
|-----|-----|-------|-----|---------|-------|
|
||
| 汇元支付 API 文档不完善或变更 | 技术 | 中 | 高 | 提前获取完整技术文档；建立汇元技术对接人沟通渠道 | |
|
||
| 汇元支付沙箱环境不稳定 | 技术 | 中 | 中 | Mock 上游接口本地测试；多环境隔离 | |
|
||
| 支付回调丢失或延迟 | 技术 | 低 | 高 | 定时主动查询补偿；对账兜底 | |
|
||
| 资金安全问题（重复扣款等） | 业务 | 低 | 高 | 幂等机制 + 对账 + 交易限额 + 告警 | |
|
||
| 渠道适配器扩展性不足 | 技术 | 中 | 中 | 前期充分设计接口抽象；参考成熟开源方案 | |
|
||
|
||
### 8.2 依赖项
|
||
|
||
| 依赖项 | 类型 | 状态 | 风险 |
|
||
|-------|-----|-----|-----|
|
||
| 汇元支付商户账号及密钥 | 外部 | 待确认 | 影响开发联调 |
|
||
| 汇元支付开放平台 API 文档 | 外部 | 待确认 | 影响接口设计 |
|
||
| MySQL 数据库实例 | 内部 | 待确认 | 影响部署 |
|
||
| Redis 实例 | 内部 | 待确认 | 影响部署 |
|
||
| 下游业务系统回调接口规范 | 内部 | 待确认 | 影响通知设计 |
|
||
|
||
### 8.3 假设与约束
|
||
|
||
**假设**：
|
||
- 汇元支付开放平台功能稳定，API 向后兼容
|
||
- 下游业务系统能提供标准的 HTTPS 回调接口接收支付通知
|
||
- 初期交易量不超过 500 QPS
|
||
|
||
**约束**：
|
||
- 首期仅对接汇元支付一个渠道，其他渠道预留扩展能力
|
||
- 不自建收银台前端，由下游系统负责支付 UI
|
||
- 不涉及资金清算，仅做交易指令转发和状态跟踪
|
||
|
||
---
|
||
|
||
## 9. 需求追踪
|
||
|
||
> 本章节由 `/req:new` 和 `/req:done` 命令自动维护，记录所有从本 PRD 派生的需求。
|
||
|
||
| 编号 | 标题 | 模块 | 状态 | 创建日期 | 完成日期 |
|
||
|------|------|------|------|---------|---------|
|
||
| REQ-001 | 聚合支付网关 | 支付模块 | 草稿 | 2026-02-11 | - |
|
||
|
||
---
|
||
|
||
## 10. 附录
|
||
|
||
### 10.1 术语表
|
||
|
||
| 术语 | 定义 |
|
||
|-----|-----|
|
||
| pay-bridge | 本项目名称，聚合支付网关中间层 |
|
||
| 上游渠道 | 第三方支付平台（如汇元支付、微信支付、支付宝等） |
|
||
| 下游系统 | 调用 pay-bridge 接口的业务系统（电商、SaaS 等） |
|
||
| 渠道适配器 | 将上游渠道私有协议转换为 pay-bridge 统一接口的组件 |
|
||
| 统一下单 | pay-bridge 对外提供的标准支付下单接口 |
|
||
| 异步通知 | 支付完成后上游回调 pay-bridge，pay-bridge 再通知下游的机制 |
|
||
| 对账 | 将本地交易记录与上游渠道账单逐笔核对的过程 |
|
||
| 长款 | 上游有交易记录但本地没有 |
|
||
| 短款 | 本地有交易记录但上游没有 |
|
||
| 分账 | 将一笔支付金额按规则分配给多个收款方 |
|
||
| 分润 | 本项目中特指从收款方商户分给平台或子商户的资金分配行为，在下单时指定金额，支付完成后自动执行 |
|
||
| 分润接收方 | 分润资金的接收方，可以是平台账户或另一个子商户，在应用接入时按应用维度配置 |
|
||
| 最大分润比例 | 应用级配置，限制单笔订单分润金额占订单金额的最大百分比 |
|
||
| 应用隔离 | pay-bridge 以应用（app）为隔离粒度，不同应用拥有独立的分润配置和订单编码序列 |
|
||
| 订单编码服务 | 按应用维度生成唯一订单号的服务，每个应用独立序列，确保编码唯一且互不干扰 |
|
||
| 开票 | 分润完成后调用上游渠道提供的开票接口，完成发票开具 |
|
||
| 固定收款账户 | 上游支付渠道为子商户开通的专属银行账号，客户可直接向该账号转账付款 |
|
||
| 自动匹配 | 系统根据入账金额和转账备注自动匹配待支付订单的机制，匹配成功后自动完成收款确认 |
|
||
| 子商户 | 在多商户平台中，通过上游支付渠道开通账户并接收收款的独立商户 |
|
||
| 服务费 | 平台对每笔交易收取的手续费，按应用和支付方式（扫码/对公/余额）设置不同费率，从收款金额中扣收至指定子商户 |
|
||
| 商户进件 | 通过 API 在上游支付平台注册开通商户，提交营业执照、法人信息等资质材料的过程 |
|
||
| 商户异常检测 | 定期检查商户在上游平台的状态（冻结、资质过期、风控限制等），发现异常及时告警 |
|
||
| 微信消息通知 | 商户绑定微信后，系统在关键业务事件发生时通过微信推送消息（到账、退款、异常等） |
|
||
| 幂等 | 相同请求多次执行产生相同结果，不产生副作用 |
|
||
|
||
### 10.2 参考资料
|
||
|
||
- [汇元支付开放平台](https://open.heepay.com/www/index.html#/document/detail?type=20&docType=1&id=000)
|
||
- [Jeepay - 开源聚合支付系统](https://github.com/jeequan/jeepay)
|
||
|
||
### 10.3 相关文档
|
||
|
||
| 文档 | 链接 |
|
||
|-----|-----|
|
||
| 支付模块文档 | docs/requirements/modules/payment.md |
|
||
| 技术方案 | 待补充 |
|
||
| 测试用例 | 待补充 |
|
||
|
||
---
|
||
|
||
## 审批记录
|
||
|
||
| 角色 | 姓名 | 意见 | 日期 |
|
||
|-----|-----|-----|-----|
|
||
| 产品负责人 | | | |
|
||
| 技术负责人 | | | |
|
||
| 业务负责人 | | | |
|
||
|
||
---
|
||
|
||
> 下一步：完善 PRD 后，可使用 `/req:new <标题>` 创建具体需求
|