# 支付中台 - 总体需求文档

## 文档信息

| 项目 | 内容 |
|------|------|
| 文档版本 | v1.1 |
| 创建日期 | 2026-02-26 |
| 产品名称 | 支付中台系统 |
| 文档状态 | 待评审 |

---

## 一、产品背景

### 1.1 业务背景

当前物业管理系统涉及多种业务场景(物业费、停车费、商城购物、增值服务等),需要对接多家支付服务商(微信支付、支付宝、易宝支付等),不同小区可能使用不同的支付方式,业务系统直接对接支付服务商存在以下问题:

- **开发成本高**:每个业务系统都要对接多家支付服务商
- **维护困难**:支付服务商接口变更需要修改所有业务系统
- **配置混乱**:不同小区的支付配置分散在各业务系统
- **数据分散**:支付流水、对账数据分散,无法统一管理
- **安全风险**:支付密钥分散存储,缺乏统一管理

### 1.2 产品定位

支付中台作为统一的支付服务层,位于业务系统和支付服务商之间,提供:

- **统一接入**:业务系统只需对接支付中台,无需关心具体支付服务商
- **灵活配置**:支持小区级、业务级支付方式配置
- **智能路由**:根据配置自动选择合适的支付服务商和支付方式
- **统一管理**:支付流水、对账、报表统一管理
- **安全可靠**:支付密钥统一加密存储,操作日志审计

---

## 二、产品目标

### 2.1 业务目标

1. **降低接入成本**:业务系统接入支付能力从 2周 缩短到 2天
2. **提升灵活性**:支持小区按需配置支付方式,无需修改代码
3. **提高可靠性**:支付成功率 ≥ 99.5%,回调成功率 ≥ 99.9%
4. **简化对账**:自动化对账流程,人工处理时间减少 80%

### 2.2 技术目标

1. **高可用**:系统可用性 ≥ 99.9%
2. **高性能**:支付下单响应时间 ≤ 2000ms,TPS ≥ 1000
3. **可扩展**:支持快速接入新的支付服务商(≤ 3天)
4. **安全性**:敏感数据加密存储,操作全程审计

---

## 三、整体架构

### 3.1 系统架构图

```
┌─────────────────────────────────────────────────────────────┐
│                       业务系统层                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │物业缴费  │  │停车管理  │  │商城系统  │  │增值服务  │   │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘   │
│       │             │             │             │          │
│       └─────────────┴─────────────┴─────────────┘          │
│                          │                                  │
└──────────────────────────┼──────────────────────────────────┘
                           │ API调用
┌──────────────────────────┼──────────────────────────────────┐
│                  支付中台系统                                  │
│  ┌────────────────────────────────────────────────────┐     │
│  │              路由服务 (支付路由)                     │     │
│  └────┬───────────────────────────────────────────┬───┘     │
│       │                                           │         │
│  ┌────▼────────┐  ┌──────────┐  ┌──────────┐  ┌──▼───────┐│
│  │运营平台管理 │  │支付渠道  │  │小区支付  │  │用户签约  ││
│  │            │  │管理      │  │配置      │  │管理      ││
│  └────────────┘  └──────────┘  └──────────┘  └──────────┘│
│  ┌────────────┐  ┌──────────┐  ┌──────────┐              │
│  │支付交易    │  │流水与对账 │  │支付报表  │              │
│  │管理        │  │          │  │          │              │
│  └────────────┘  └──────────┘  └──────────┘              │
└──────────────────────────┬───────────────────────────────────┘
                           │ 服务商SDK调用
┌──────────────────────────┼───────────────────────────────────┐
│                   支付服务商层                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │微信支付  │  │支付宝    │  │易宝支付  │  │银行      │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
└─────────────────────────────────────────────────────────────┘
```

### 3.2 v1.1版本架构调整

**运营平台采用支付服务商模式:**

```
支付服务商 (微信/支付宝/易宝/银联)
  ↓
运营平台 (作为服务商申请服务商商户资质)
  ├─ 服务商商户号
  ├─ 服务商应用ID
  ├─ 服务商密钥/证书
  ├─ 小区A → 子商户模式 (在运营平台服务商下申请子商户)
  │    └─ 子商户号 (关联上级服务商)
  ├─ 小区B → 独立商户模式 (小区独立申请普通商户)
  │    └─ 商户号 + AppID + 密钥 (不关联运营平台)
  └─ ...
```

**小区商户模式说明:**

| 模式 | 说明 | 配置信息 | 适用场景 |
|------|------|---------|---------|
| 子商户模式 | 小区在运营平台服务商下申请子商户 | 仅需子商户号,自动关联服务商信息 | 统一管理、结算方便 |
| 独立商户模式 | 小区独立申请普通商户 | 完整商户号、AppID、密钥 | 独立结算、已有商户 |

**对比v1.0:**
- v1.0: 支付服务商配置全局唯一,无法支持多运营平台
- v1.1: 支持多运营平台独立管理自己的支付配置
- v1.1.1: 支持子商户和独立商户两种模式

### 3.3 核心模块说明

| 模块编号 | 模块名称 | 核心职责 | 用户角色 |
|---------|---------|---------|---------|
| 00 | 运营平台管理 | 管理运营平台基础信息 | 系统管理员 |
| 01 | 运营平台服务商配置 | 管理运营平台在各支付服务商申请的服务商商户信息 | 运营平台管理员 |
| 02 | 业务场景管理 | 管理支付方式、业务场景配置 | 运营平台管理员 |
| 03 | 小区支付配置 | 配置小区支付方式(子商户/独立商户模式)、业务场景、路由规则 | 运营平台管理员 |
| 04 | 用户签约管理 | 管理用户签约关系(托收、生活缴费等) | 系统自动 + 管理员查看 |
| 05 | 支付交易管理 | 处理支付下单、查询、退款、回调(含退款回调) | 系统自动 + 业务系统调用 |
| 06 | 流水与对账 | 支付流水查询、对账单下载、差异处理 | 财务人员 |
| 07 | 支付报表 | 支付数据统计、手续费分析 | 运营管理员 + 财务人员 |

---

## 四、模块间关联关系

### 4.1 配置层关联关系

```
运营平台管理 (00)
  ├─ 创建运营平台
  └─ 管理运营平台信息
       ↓
运营平台服务商配置 (01)
  ├─ 为运营平台配置支付服务商 (微信、支付宝、易宝等)
  └─ 配置服务商参数 (服务商商户号、AppID、密钥等)
       ↓
业务场景管理 (02)
  ├─ 配置支付方式 (扫码、H5、APP、托收等)
  └─ 配置业务场景 (生活缴费、普通商户等)
       ↓ 被引用
小区支付配置 (03)
  ├─ 选择商户模式 (子商户模式/独立商户模式)
  ├─ 子商户模式: 关联运营平台服务商,仅需子商户号
  ├─ 独立商户模式: 配置完整商户号、AppID、密钥
  ├─ 配置业务场景对应的支付方式
  └─ 设置路由优先级
       ↓ 被路由服务使用
路由服务
  ├─ 接收业务系统支付请求
  ├─ 根据小区+业务类型查询配置
  ├─ 子商户模式: 查询运营平台服务商配置
  ├─ 独立商户模式: 使用小区独立商户配置
  └─ 返回对应的支付服务商和支付方式
```

**关键数据流**:
1. 系统管理员创建运营平台
2. 运营平台管理员配置服务商信息(服务商商户号、密钥等)
3. 运营平台管理员为小区配置支付方式:
   - 子商户模式: 关联运营平台服务商,仅配置子商户号
   - 独立商户模式: 配置完整商户信息(商户号、AppID、密钥)
4. 业务系统发起支付时,路由服务根据配置自动选择

### 4.2 交易层关联关系

```
支付交易管理 (05)
  ├─ 下单前:查询"小区支付配置"获取支付方式和商户模式
  ├─ 子商户模式: 查询"运营平台服务商配置"获取服务商商户号和密钥
  ├─ 独立商户模式: 使用小区独立配置的商户号和密钥
  ├─ 签约支付:查询"用户签约管理"验证签约状态
  ├─ 支付完成:记录到"流水与对账"
  ├─ 支付回调:通知业务系统 + 记录日志
  └─ 退款回调:更新退款状态 + 通知业务系统
       ↓
流水与对账 (06)
  ├─ 接收支付订单数据
  ├─ 下载服务商对账单
  └─ 对比生成差异报告
       ↓
支付报表 (07)
  ├─ 读取支付流水数据
  ├─ 统计交易金额、笔数、成功率
  └─ 分析手续费
```

**关键数据流**:
1. 业务系统调用"支付交易管理"下单
2. 查询小区配置和运营平台配置
3. 支付完成后自动记录到"流水与对账"
4. "支付报表"定时汇总流水数据生成报表

### 4.3 签约场景关联关系

```
用户签约管理 (04)
  ├─ 用户发起签约请求
  ├─ 调用支付服务商签约接口
  └─ 保存签约协议号
       ↓ 被支付交易使用
支付交易管理 (05)
  ├─ 托收支付:必须验证签约状态
  ├─ 生活缴费:可选验证签约状态
  └─ 普通支付:不需要签约
```

**业务规则**:
- 银行托收场景:必须先签约才能支付
- 微信生活缴费场景:需要签约才能享受手续费优惠
- 普通商户场景:无需签约

---

## 五、核心业务流程

### 5.1 支付下单流程 (v1.1)

```
业务系统
  │
  ├─ 1. 调用支付中台下单接口
  │    ├─ 参数: community_id, business_type, amount, user_id
  │    └─ 可选: payment_method_id (指定支付方式)
  │
  ▼
支付中台 - 路由服务
  │
  ├─ 2. 查询小区支付配置
  │    ├─ 根据 community_id + business_type 查询
  │    └─ 获取 platform_id (运营平台ID)
  │
  ├─ 3. 查询运营平台服务商配置
  │    ├─ 根据 platform_id + provider_id 查询
  │    └─ 获取 platform_merchant_no, platform_secret_key
  │
  ├─ 4. 验证签约状态 (如果是签约支付场景)
  │    └─ 查询用户签约管理,验证签约有效性
  │
  ├─ 5. 调用支付服务商下单接口
  │    └─ 使用运营平台的商户号和密钥
  │
  ├─ 6. 保存支付订单
  │    └─ 状态: pending (待支付)
  │
  ▼
返回业务系统
  └─ 返回支付信息供用户支付
```

### 5.2 支付回调流程 (v1.1)

```
支付服务商
  │
  ├─ 1. 支付完成后回调支付中台
  │    └─ 携带: 订单号、支付结果、支付时间、手续费等
  │
  ▼
支付中台 - 回调处理
  │
  ├─ 2. 验证签名 (使用运营平台密钥)
  │
  ├─ 3. 更新订单状态 (pending → paid)
  │    └─ 记录: 支付时间、交易流水号、手续费
  │
  ├─ 4. 记录支付流水
  │
  ├─ 5. 异步通知业务系统
  │    ├─ 首次通知
  │    ├─ 失败重试1 (延迟10秒)
  │    ├─ 失败重试2 (延迟30秒)
  │    └─ 失败重试3 (延迟60秒)
  │
  ├─ 6. 记录回调日志 (含通知业务系统结果)
  │
  ▼
返回服务商
  └─ 返回成功响应
```

### 5.3 退款流程 (v1.1 - 含退款回调)

```
业务系统
  │
  ├─ 1. 业务系统审核退款申请
  │    └─ 审核通过后调用支付中台退款接口
  │
  ▼
支付中台 - 退款处理
  │
  ├─ 2. 验证退款请求 (含并发控制)
  │    ├─ 使用乐观锁防止并发退款
  │    ├─ 验证退款金额 (不能超过可退金额)
  │    └─ 防止重复退款
  │
  ├─ 3. 调用支付服务商退款接口
  │
  ├─ 4. 保存退款记录 (状态: processing)
  │
  ├─ 5. 更新订单状态
  │    ├─ 部分退款: part_refunded
  │    └─ 全额退款: refunded
  │
  ▼
服务商异步处理
  │
  ├─ 退款成功/失败回调支付中台
  │
  ▼
支付中台 - 退款回调处理
  │
  ├─ 验证回调签名
  │
  ├─ 更新退款状态 (processing → success/failed)
  │
  ├─ 异步通知业务系统退款结果
  │
  └─ 返回成功响应给服务商
```

### 5.4 订单超时关闭机制 (v1.1新增)

```
定时任务 (每5分钟执行)
  │
  ├─ 1. 查询超时未支付订单
  │    └─ order_status = 'pending'
  │    └─ created_at < 当前时间 - 30分钟
  │
  ├─ 2. 批量关闭订单
  │    └─ 更新 order_status = 'closed'
  │    └─ 记录 close_time
  │
  └─ 3. 不通知业务系统
       └─ 业务系统可主动查询订单状态
```

---

## 六、数据流转关系

### 6.1 配置数据流转 (v1.1)

```
1. 运营平台配置
   ├─ 输入: 系统管理员创建运营平台
   ├─ 存储: operation_platform 表
   └─ 使用: 支付渠道管理、小区支付配置

2. 支付服务商配置
   ├─ 输入: 运营平台管理员配置服务商基础信息
   ├─ 存储: payment_provider 表
   └─ 使用: 运营平台服务商配置

3. 运营平台服务商配置
   ├─ 输入: 为运营平台配置平台商户号和密钥
   ├─ 存储: platform_provider_config 表
   └─ 使用: 支付路由、支付下单

4. 小区支付配置
   ├─ 输入: 关联运营平台和支付服务商
   ├─ 存储: community_payment_config 表 (含platform_id)
   └─ 使用: 支付路由服务
```

### 6.2 交易数据流转

```
1. 支付订单
   ├─ 输入: 业务系统调用下单接口
   ├─ 存储: payment_order 表 (含version字段用于并发控制)
   ├─ 状态变更: pending → paid → (part_refunded/refunded)
   └─ 使用: 退款、流水查询、对账、报表

2. 退款记录
   ├─ 输入: 业务系统调用退款接口
   ├─ 存储: payment_refund 表
   ├─ 状态变更: processing → success/failed
   └─ 使用: 流水查询、报表

3. 回调日志
   ├─ 输入: 服务商回调时自动记录
   ├─ 存储: payment_callback_log 表 (含通知业务系统结果)
   └─ 使用: 问题排查、审计
```

---

## 七、非功能性需求

### 7.1 性能要求

| 指标 | 要求 | 说明 |
|------|------|------|
| 下单响应时间 | ≤ 2000ms | P95 响应时间 (v1.1调整,含路由查询和服务商调用) |
| 查询响应时间 | ≤ 200ms | P95 响应时间 |
| 并发处理能力 | ≥ 1000 TPS | 支付下单 TPS |
| 回调处理时间 | ≤ 100ms | 快速响应服务商 |
| 退款响应时间 | ≤ 500ms | 退款接口响应时间 |

### 7.2 可靠性要求

| 指标 | 要求 | 说明 |
|------|------|------|
| 系统可用性 | ≥ 99.9% | 年故障时间 ≤ 8.76小时 |
| 支付成功率 | ≥ 99.5% | 排除用户原因 |
| 回调成功率 | ≥ 99.9% | 含重试机制 |
| 数据一致性 | 100% | 支付数据不丢失、不重复 |

### 7.3 安全性要求

| 类别 | 要求 | 实现方式 |
|------|------|---------|
| 数据加密 | 敏感数据加密存储 | AES-256-GCM 加密 |
| 传输安全 | HTTPS 传输 | TLS 1.2+ |
| 接口鉴权 | API签名认证 | HMAC-SHA256签名 + 时间戳 + 随机数 |
| 数据脱敏 | 敏感信息脱敏展示 | 银行卡号、姓名、手机号、密钥 |
| 操作审计 | 关键操作日志记录 | 配置变更、退款操作等 |

#### 7.3.1 密钥管理方案 (v1.1新增)

**KEK管理方案 (生产环境):**
- 使用KMS (密钥管理服务)
- KEK不落地,存储在KMS中
- 支持密钥轮转
- 满足合规要求

**密钥加密存储:**
- platform_secret_key: AES-256-GCM加密
- platform_cert: AES-256-GCM加密
- 加密后存储在数据库

**日志脱敏规则:**
- 密钥字段: 完全脱敏 (******)
- 银行卡号: 622202******1234
- 手机号: 138****5678
- 姓名: 张**

#### 7.3.2 API签名认证方案 (v1.1新增)

**签名算法: HMAC-SHA256**

**请求头必须包含:**
- X-App-Id: 业务系统ID
- X-Timestamp: 请求时间戳(秒)
- X-Nonce: 随机字符串
- X-Signature: 签名

**验证规则:**
- 时间戳验证 (5分钟内有效)
- Nonce防重放 (缓存已用nonce)
- 签名验证 (使用业务系统密钥)

### 7.4 扩展性要求

| 类别 | 要求 | 说明 |
|------|------|------|
| 支付服务商扩展 | ≤ 3天接入新服务商 | 通过配置 + 适配器模式 |
| 支付方式扩展 | ≤ 1天支持新支付方式 | 配置化实现 |
| 业务场景扩展 | ≤ 1天支持新业务场景 | 配置化实现 |
| 运营平台扩展 | 支持多运营平台 | v1.1新增,支持独立配置 |
| 小区数量 | 支持 10000+ 小区 | 数据库分表、缓存优化 |

### 7.5 数据保留要求

| 数据类型 | 保留时长 | 说明 |
|---------|---------|------|
| 支付订单 | 永久保留 | 财务凭证,支持分表 |
| 退款记录 | 永久保留 | 财务凭证 |
| 回调日志 | 1年 | 问题排查 |
| 对账记录 | 5年 | 财务审计 |
| 操作日志 | 2年 | 安全审计 |

---

## 八、统一错误码体系 (v1.1新增)

### 8.1 错误码格式

```
错误码格式: PAY-XXXX-YY
- PAY: 支付中台标识
- XXXX: 模块代码
- YY: 错误序号

模块代码:
- 1000: 参数校验
- 2000: 路由服务
- 3000: 签约管理
- 4000: 支付交易
- 5000: 退款处理
- 6000: 对账管理
- 9000: 系统错误
```

### 8.2 常见错误码

**参数校验错误 (PAY-1000-XX)**

| 错误码 | 错误信息 | 说明 |
|-------|---------|------|
| PAY-1000-01 | 缺少必填参数:[参数名] | 必填参数缺失 |
| PAY-1000-02 | 支付金额不合法 | 金额≤0或超过限额 |
| PAY-1000-03 | 业务订单号已存在 | 幂等性校验失败 |
| PAY-1000-04 | 回调地址格式不正确 | URL格式校验失败 |

**路由服务错误 (PAY-2000-XX)**

| 错误码 | 错误信息 | 说明 |
|-------|---------|------|
| PAY-2000-01 | 小区未配置支付方式 | 小区无支付配置 |
| PAY-2000-02 | 小区未配置该支付方式 | 指定的支付方式不可用 |
| PAY-2000-03 | 支付配置已停用 | 配置被禁用 |
| PAY-2000-04 | 运营平台配置缺失 | 未找到运营平台服务商配置 |

**签约管理错误 (PAY-3000-XX)**

| 错误码 | 错误信息 | 说明 |
|-------|---------|------|
| PAY-3000-01 | 该支付方式需要签约,请先完成签约 | 支付方式需要签约但用户未签约 |
| PAY-3000-02 | 签约已失效,请重新签约 | 签约状态为invalid(房屋退租/变更导致) (v1.1.1) |
| PAY-3000-03 | 签约已解约,请重新签约 | 签约状态为cancelled(用户/管理员主动解约) (v1.1.1) |
| PAY-3000-04 | 签约服务商不匹配 | 签约与支付服务商不一致 |
| PAY-3000-05 | 用户不存在 | 签约失效接口:用户ID无效 (v1.1.1) |
| PAY-3000-06 | 小区不存在 | 签约失效接口:小区ID无效 (v1.1.1) |

**支付交易错误 (PAY-4000-XX)**

| 错误码 | 错误信息 | 说明 |
|-------|---------|------|
| PAY-4000-01 | 订单不存在 | 订单号错误 |
| PAY-4000-02 | 订单状态不支持该操作 | 状态流转错误 |
| PAY-4000-03 | 服务商下单失败:[原因] | 服务商接口调用失败 |

**退款处理错误 (PAY-5000-XX)**

| 错误码 | 错误信息 | 说明 |
|-------|---------|------|
| PAY-5000-01 | 退款金额超过可退金额 | 金额校验失败 |
| PAY-5000-02 | 订单状态不支持退款 | 只有paid/part_refunded可退款 |
| PAY-5000-03 | 退款单号重复 | 幂等性校验失败 |
| PAY-5000-04 | 订单状态已变更,请重试 | 乐观锁并发控制失败,建议业务系统重试 (v1.1.1增强) |

**系统错误 (PAY-6000-XX)** (v1.1.1新增)

| 错误码 | 错误信息 | 说明 |
|-------|---------|------|
| PAY-6000-01 | 系统异常,请稍后重试 | 数据库更新失败等系统异常 |
| PAY-6000-02 | 缓存服务异常 | Redis等缓存服务故障(已降级) |
| PAY-6000-03 | 参数验证失败 | 必填参数缺失或格式错误 |

**通用系统错误 (PAY-9000-XX)**

| 错误码 | 错误信息 | 说明 |
|-------|---------|------|
| PAY-9000-01 | 系统繁忙,请稍后重试 | 系统异常 |
| PAY-9000-02 | 数据库操作失败 | DB异常 |
| PAY-9000-03 | 服务商接口超时 | 网络超时 |

---

## 九、订单状态统一定义 (v1.1新增)

### 9.1 数据库状态 (英文)

**payment_order.order_status:**
- `pending` - 待支付
- `paid` - 已支付
- `closed` - 已关闭
- `part_refunded` - 部分退款
- `refunded` - 已退款

### 9.2 页面展示 (中文)

**状态映射表:**

| 数据库值 | 页面显示 | 颜色标识 |
|---------|---------|---------|
| pending | 待支付 | 蓝色 |
| paid | 已支付 | 绿色 |
| closed | 已关闭 | 灰色 |
| part_refunded | 部分退款 | 黄色 |
| refunded | 已退款 | 橙色 |

### 9.3 退款状态

**payment_refund.refund_status:**

| 数据库值 | 页面显示 | 颜色标识 |
|---------|---------|---------|
| processing | 退款中 | 蓝色 |
| success | 退款成功 | 绿色 |
| failed | 退款失败 | 红色 |

### 9.4 签约状态

**user_payment_sign.sign_status:**

| 数据库值 | 页面显示 | 颜色标识 | 说明 (v1.1.1) |
|---------|---------|---------|--------------|
| signing | 签约中 | 蓝色 | 用户未完成签约 |
| signed | 已签约 | 绿色 | 可正常使用自动扣款 |
| cancelled | 已解约 | 灰色 | 用户/管理员主动解约 |
| invalid | 已失效 | 红色 | 房屋退租/变更导致失效 (v1.1.1新增) |

---

## 十、技术约束

### 10.1 开发技术栈

- **后端语言**:Java 17+ / Go 1.20+
- **框架**:Spring Boot / Gin
- **数据库**:MySQL 8.0+
- **缓存**:Redis 6.0+
- **消息队列**:RabbitMQ / Kafka (用于异步通知)

### 10.2 第三方依赖

| 依赖项 | 用途 | 版本要求 |
|-------|------|---------|
| 微信支付 SDK | 微信支付对接 | 官方最新版 |
| 支付宝 SDK | 支付宝对接 | 官方最新版 |
| 易宝支付 SDK | 易宝支付对接 | 官方最新版 |
| KMS服务 | 密钥管理 (v1.1新增) | 云厂商KMS或自建Vault |

### 10.3 部署要求

- **部署方式**:Docker 容器化部署
- **服务器要求**:≥ 4核8G (生产环境建议 8核16G)
- **高可用**:至少 2个实例 + 负载均衡
- **数据备份**:每日全量备份 + 实时增量备份

---

## 十一、项目里程碑

### 11.1 MVP版本范围 (v1.1)

| 模块 | 功能范围 | 优先级 |
|------|---------|-------|
| 运营平台管理 | 运营平台CRUD | P0 |
| 运营平台服务商配置 | 服务商商户信息配置、密钥管理 | P0 |
| 业务场景管理 | 支付方式配置、业务场景配置 | P0 |
| 小区支付配置 | 主支付配置(子商户/独立商户模式)、业务场景配置、路由服务 | P0 |
| 用户签约管理 | 签约流程、签约关系管理 | P0 |
| 支付交易管理 | 下单、查询、退款、回调、校验、退款回调、超时关闭、并发控制 | P0 |
| 流水与对账 | 流水查询、对账单下载、简单匹配、差异展示 | P0 |
| 支付报表 | 数据统计、手续费分析 | P0 |

### 11.2 后续迭代计划 (v2.0+)

| 功能 | 版本 | 说明 |
|------|------|------|
| 自动分账 | v2.0 | 支持平台与小区自动分账 |
| 智能对账 | v2.0 | 复杂规则匹配、自动调账 |
| 手动重新通知 | v2.0 | 支持手动触发业务系统通知 |
| 支付风控 | v2.1 | 异常交易监控、风险预警 |
| 多租户隔离 | v2.1 | 支持多运营平台独立部署 |

---

## 十二、风险与应对

### 12.1 技术风险

| 风险 | 影响 | 应对措施 |
|------|------|---------|
| 支付服务商接口变更 | 高 | 使用适配器模式隔离、定期检查官方文档 |
| 高并发场景性能瓶颈 | 中 | 引入缓存、数据库读写分离、限流降级 |
| 数据一致性问题 | 高 | 引入分布式事务、幂等性设计、补偿机制、乐观锁并发控制 |
| 订单表数据量大 | 中 | 按月分表,历史数据归档 |

### 12.2 业务风险

| 风险 | 影响 | 应对措施 |
|------|------|---------|
| 回调通知失败 | 高 | 3次重试 + 业务系统主动查询 |
| 对账差异处理 | 中 | 人工审核 + 记录处理结果 |
| 退款审核流程缺失 | 中 | 明确退款由业务系统审核,中台只执行 |
| 退款并发超额 | 高 | 使用乐观锁控制并发,防止超额退款 |

---

## 十三、v1.0到v1.1的主要变更

### 13.1 架构调整

1. **新增运营平台维度**
   - 新增运营平台表 (operation_platform)
   - 新增运营平台服务商配置表 (platform_provider_config)
   - payment_provider表调整为只存储服务商基础信息
   - community_payment_config表新增platform_id字段

2. **支持多运营平台**
   - 每个运营平台独立管理自己的服务商商户号和密钥
   - 小区配置关联到具体运营平台
   - 支付路由增加运营平台维度查询

3. **模块拆分调整 (v1.1.1)**
   - 原"支付渠道管理"拆分为"运营平台服务商配置"和"业务场景管理"
   - 运营平台服务商配置: 管理服务商商户信息
   - 业务场景管理: 管理支付方式和业务场景

4. **小区支持两种商户模式 (v1.1.1)**
   - 子商户模式: 关联运营平台服务商,仅需配置子商户号
   - 独立商户模式: 独立配置完整商户信息(商户号、AppID、密钥)

### 13.2 功能完善

1. **新增退款回调处理**
   - 支持服务商退款回调接口
   - 自动更新退款状态
   - 异步通知业务系统退款结果

2. **新增订单超时关闭机制**
   - 定时任务自动关闭超时订单
   - 订单超时30分钟自动关闭
   - 不通知业务系统

3. **新增退款并发控制**
   - 使用乐观锁防止并发退款
   - payment_order表新增version字段
   - 防止超额退款

4. **完善密钥管理方案**
   - 明确KEK管理方案 (KMS/HSM)
   - 定义日志脱敏规则
   - 密钥加密存储和使用流程

5. **新增API签名认证**
   - HMAC-SHA256签名算法
   - 时间戳验证防重放
   - Nonce验证防重放

6. **统一错误码体系**
   - 定义错误码格式
   - 按模块分类错误码
   - 提供常见错误码清单

7. **统一订单状态定义**
   - 明确数据库状态 (英文)
   - 明确页面展示 (中文)
   - 定义颜色标识

### 13.3 数据库调整

1. **新增表**
   - operation_platform (运营平台表)
   - platform_provider_config (运营平台服务商配置表)
   - payment_business_type (业务类型配置表) - 业务类型配置化

2. **调整表**
   - payment_provider: 删除平台配置字段
   - community_payment_config: 新增platform_id,删除community_name冗余字段
   - user_payment_sign: 删除错误的唯一索引,新增sign_no唯一索引
   - payment_order: 新增version字段,新增多个复合索引,支持按月分表
   - payment_callback_log: 新增通知业务系统相关字段

3. **索引优化**
   - payment_order表新增多个复合索引
   - user_payment_sign表新增查询索引
   - payment_reconciliation_diff表新增索引

### 13.4 性能调整

- 下单响应时间: 500ms → 2000ms (更符合实际,含路由查询和服务商调用)
- 其他性能指标保持不变

---

## 十四、附录

### 14.1 术语表

| 术语 | 说明 |
|------|------|
| 运营平台 | v1.1新增,管理多个小区的运营主体 |
| 服务商商户号 | 运营平台在支付服务商处申请的服务商商户号 |
| 子商户号 | 小区在运营平台服务商下申请的子商户号,关联上级服务商 |
| 独立商户号 | 小区独立申请的普通商户号,不关联运营平台 |
| 子商户模式 | 小区使用运营平台服务商下的子商户,仅需配置子商户号 |
| 独立商户模式 | 小区使用独立申请的普通商户,需配置完整商户信息 |
| 支付服务商 | 提供支付能力的第三方公司 (微信、支付宝、易宝等) |
| 支付方式 | 具体的支付类型 (扫码、H5、APP、托收等) |
| 业务场景 | 服务商对业务的分类 (生活缴费、普通商户等) |
| 签约 | 用户授权服务商从银行卡扣款的协议 |
| 托收 | 定期自动从用户银行卡扣款的支付方式 |
| 对账 | 核对支付中台数据与服务商数据是否一致 |
| 分账 | 支付金额自动分配给平台和小区 |
| 长款 | 服务商有交易记录,系统无 |
| 短款 | 系统有交易记录,服务商无 |
| KEK | 密钥加密密钥 (Key Encryption Key) |
| KMS | 密钥管理服务 (Key Management Service) |

### 14.2 参考文档

- 微信支付官方文档: https://pay.weixin.qq.com/wiki/doc/api/
- 支付宝开放平台: https://opendocs.alipay.com/
- 易宝支付文档: https://www.yeepay.com/
- CHANGELOG_v1.0_to_v1.1.md: v1.0到v1.1的详细变更说明

---

## 变更记录

| 版本 | 日期 | 修改人 | 修改内容 |
|------|------|-------|---------|
| v1.0 | 2026-02-25 | 产品经理 | 初始版本 |
| v1.1 | 2026-02-26 | 产品经理 | 基于评审报告进行系统性修复和架构优化:<br>1. 新增运营平台维度,支持多运营平台管理<br>2. 新增退款回调处理机制<br>3. 新增订单超时关闭机制<br>4. 新增退款并发控制<br>5. 完善密钥管理和API签名认证方案<br>6. 统一错误码体系和订单状态定义<br>7. 数据库表结构调整和索引优化<br>8. 性能指标调整<br>9. 业务类型配置化 |
| v1.1.1 | 2026-03-05 | 产品经理 | 模块拆分和商户模式优化:<br>1. 原"支付渠道管理"拆分为"运营平台服务商配置"和"业务场景管理"<br>2. 小区支付配置支持子商户模式和独立商户模式<br>3. 更新模块编号和关联关系<br>4. 完善术语定义 |