# 支付报表 - PRD

## 文档信息

| 项目 | 内容 |
|------|------|
| 文档版本 | v1.1 |
| 创建日期 | 2026-02-26 |
| 模块名称 | 支付报表 |
| 文档状态 | 已评审修订 |

---

## 一、模块概述

### 1.1 模块定位

支付报表模块负责对支付数据进行统计分析,为运营管理和财务决策提供数据支持。通过多维度的数据统计和可视化展示,帮助管理者了解支付业务运营情况。

### 1.2 核心功能

1. **支付数据统计** - 多维度统计支付交易数据
2. **手续费分析** - 分析各服务商收取的手续费
3. **数据可视化** - 图表展示数据趋势和分布

### 1.3 使用角色

- **运营平台管理员** - 查看整体运营数据
- **财务人员** - 查看交易数据和手续费
- **小区管理员** - 查看本小区支付数据

---

## 二、功能详细说明

### 2.1 支付数据统计

#### 2.1.1 功能描述

按不同维度统计支付交易数据,包括交易笔数、交易金额、成功率、退款情况等核心指标。

#### 2.1.2 统计维度

**维度1: 按运营平台统计** (v1.1.2新增)
- 选择时间范围
- 按运营平台维度汇总数据
- 支持运营平台对比分析
- 注:独立商户模式的小区(无运营平台关联)归入"独立商户"分类

**维度2: 按小区统计**
- 选择时间范围
- 按小区维度汇总数据
- 支持小区对比分析

**维度3: 按业务类型统计**
- 选择时间范围
- 按业务类型(物业费/停车费/商城等)汇总
- 了解各业务线收入情况

**维度4: 按支付服务商统计**
- 选择时间范围
- 按服务商(微信/支付宝/易宝)汇总
- 对比不同服务商使用情况

**维度5: 按支付方式统计**
- 选择时间范围
- 按支付方式(扫码/H5/公众号/托收)汇总
- 分析用户支付偏好

#### 2.1.3 统计指标

**核心指标:**

| 指标 | 说明 | 计算方式 |
|------|------|---------|
| 交易笔数 | 支付成功的订单数 | COUNT(订单状态=paid) |
| 交易金额 | 支付成功的总金额 | SUM(实付金额) 其中订单状态=paid |
| 成功率 | 支付成功率 | 支付成功笔数 / 总下单笔数 × 100% |
| 退款笔数 | 退款订单数 | COUNT(退款记录) |
| 退款金额 | 退款总金额 | SUM(退款金额) |
| 退款率 | 退款订单占比 | 退款笔数 / 支付成功笔数 × 100% |
| 手续费总额 | 支付手续费总计 | SUM(手续费) 其中订单状态=paid |
| 平均交易金额 | 单笔平均金额 | 交易金额 / 交易笔数 |

**订单状态统一定义 (v1.1):**

在统计计算和页面展示中,使用统一的状态映射:

| 数据库值 | 页面显示 | 颜色标识 | 说明 |
|---------|---------|---------|------|
| pending | 待支付 | 蓝色 | 用户已下单但未支付 |
| paid | 已支付 | 绿色 | 支付成功 |
| closed | 已关闭 | 灰色 | 订单超时关闭或手动关闭 |
| part_refunded | 部分退款 | 黄色 | 已部分退款 |
| refunded | 已退款 | 橙色 | 已全额退款 |

**说明:**
- 数据库存储使用英文枚举值
- 页面展示时映射为中文
- 统计计算时使用数据库原始值

#### 2.1.4 时间维度

**快捷选择:**
- 今日
- 昨日
- 本周
- 上周
- 本月
- 上月
- 本年
- 自定义时间范围

**时间粒度:**
- 按日统计
- 按周统计
- 按月统计
- 按年统计

#### 2.1.5 页面交互

**页面结构:**

**顶部筛选区**
- 时间范围选择 (快捷选择 + 自定义)
- 统计维度选择 (下拉单选:运营平台/小区/业务类型/服务商/支付方式)
- 查询按钮

**核心指标看板区**

展示4个核心指标卡片:

```
┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ 交易笔数    │  │ 交易金额    │  │ 成功率      │  │ 退款金额    │
│             │  │             │  │             │  │             │
│  12,345     │  │  1,234,567  │  │   98.5%     │  │   23,456   │
│  笔         │  │  元         │  │             │  │   元        │
│             │  │             │  │             │  │             │
│  ↑ 15.2%    │  │  ↑ 20.3%    │  │  ↑ 0.5%     │  │  ↓ 5.1%    │
│  (环比上期) │  │  (环比上期) │  │  (环比上期) │  │  (环比上期) │
└─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘
```

**趋势图表区**

**图表1: 交易趋势图 (折线图)**
- X轴:时间 (日期)
- Y轴左:交易金额 (元)
- Y轴右:交易笔数 (笔)
- 双Y轴折线图
- 支持数据点悬停查看详情

**图表2: 成功率趋势图 (折线图)**
- X轴:时间 (日期)
- Y轴:成功率 (%)
- 折线图
- 基准线:95% (可配置)

**明细列表区**

根据选择的统计维度展示明细:

**按运营平台统计明细:** (v1.1.2新增)
| 运营平台名称 | 关联小区数 | 交易笔数 | 交易金额 | 成功率 | 退款笔数 | 退款金额 | 手续费 | 操作 |
|-------------|-----------|---------|---------|-------|---------|---------|-------|------|
| 华南运营平台 | 50 | 5000 | 250000.00 | 98.8% | 30 | 1500.00 | 150.00 | 查看详情 |
| 华北运营平台 | 30 | 3000 | 150000.00 | 98.2% | 25 | 1200.00 | 90.00 | 查看详情 |
| 独立商户 | 10 | 500 | 25000.00 | 97.5% | 5 | 200.00 | 15.00 | 查看详情 |

**按小区统计明细:**
| 小区名称 | 交易笔数 | 交易金额 | 成功率 | 退款笔数 | 退款金额 | 手续费 | 操作 |
|---------|---------|---------|-------|---------|---------|-------|------|
| 阳光花园 | 1000 | 50000.00 | 98.5% | 10 | 500.00 | 30.00 | 查看详情 |
| 绿城小区 | 800 | 40000.00 | 97.8% | 15 | 600.00 | 24.00 | 查看详情 |

**按业务类型统计明细:**
| 业务类型 | 交易笔数 | 交易金额 | 成功率 | 退款笔数 | 退款金额 | 手续费 |
|---------|---------|---------|-------|---------|---------|-------|
| 物业费 | 5000 | 250000.00 | 99.0% | 20 | 1000.00 | 150.00 |
| 停车费 | 3000 | 30000.00 | 98.0% | 30 | 300.00 | 18.00 |
| 商城购物 | 2000 | 50000.00 | 97.5% | 50 | 1000.00 | 30.00 |

**按服务商统计明细:**
| 服务商 | 交易笔数 | 交易金额 | 成功率 | 手续费 | 费率 |
|-------|---------|---------|-------|-------|------|
| 微信支付 | 8000 | 400000.00 | 98.5% | 240.00 | 0.06% |
| 支付宝 | 1500 | 80000.00 | 97.8% | 48.00 | 0.06% |
| 易宝支付 | 500 | 50000.00 | 99.2% | 25.00 | 0.05% |

**操作:**
- 导出Excel

#### 2.1.6 数据展示格式

**金额显示:**
- 单位:元
- 保留2位小数
- 千分位分隔符 (如: 1,234,567.89)

**百分比显示:**
- 保留1位小数
- 带百分号 (如: 98.5%)

**趋势显示:**
- ↑ 上升 (绿色)
- ↓ 下降 (红色)
- - 持平 (灰色)

---

### 2.2 手续费分析

#### 2.2.1 功能描述

分析各支付服务商收取的手续费,帮助财务人员和管理者了解支付成本,为服务商选择和费率谈判提供数据支持。

#### 2.2.2 统计维度

**维度1: 按服务商统计手续费**
- 各服务商手续费总额
- 各服务商交易金额
- 实际费率 (手续费 / 交易金额)

**维度2: 按小区统计手续费**
- 各小区手续费总额
- 各小区使用的服务商分布
- 各小区平均费率

**维度3: 按业务类型统计手续费**
- 各业务线手续费总额
- 各业务线交易金额
- 各业务线平均费率

#### 2.2.3 手续费指标

| 指标 | 说明 | 计算方式 |
|------|------|---------|
| 手续费总额 | 支付手续费合计 | SUM(手续费) |
| 交易金额 | 支付成功总金额 | SUM(实付金额) |
| 实际费率 | 实际支付的费率 | 手续费 / 交易金额 × 100% |
| 平均单笔手续费 | 单笔平均手续费 | 手续费总额 / 交易笔数 |

#### 2.2.4 页面交互

**页面结构:**

**顶部筛选区**
- 时间范围选择
- 统计维度选择 (下拉:服务商/小区/业务类型)
- 查询按钮

**手续费概览区**

```
┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ 手续费总额  │  │ 交易金额    │  │ 平均费率    │  │ 平均单笔    │
│             │  │             │  │             │  │  手续费     │
│  3,456.78   │  │  5,678,900  │  │   0.061%    │  │   0.35     │
│  元         │  │  元         │  │             │  │   元        │
└─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘
```

**手续费趋势图 (折线图)**
- X轴:时间
- Y轴:手续费金额 (元)
- 展示手续费随时间的变化趋势

**服务商费率对比图 (柱状图)**
- X轴:服务商名称
- Y轴:费率 (%)
- 展示不同服务商的实际费率对比

**手续费明细列表**

**按服务商统计:**
| 服务商 | 交易笔数 | 交易金额 | 手续费总额 | 实际费率 | 平均单笔手续费 |
|-------|---------|---------|----------|---------|--------------|
| 微信支付 | 8000 | 400000.00 | 240.00 | 0.060% | 0.03 |
| 支付宝 | 1500 | 80000.00 | 48.00 | 0.060% | 0.03 |
| 易宝支付 | 500 | 50000.00 | 25.00 | 0.050% | 0.05 |

**按小区统计:**
| 小区名称 | 主要服务商 | 交易金额 | 手续费总额 | 平均费率 |
|---------|----------|---------|----------|---------|
| 阳光花园 | 微信支付 | 250000.00 | 150.00 | 0.060% |
| 绿城小区 | 微信支付 | 150000.00 | 90.00 | 0.060% |

**操作:**
- 导出Excel

#### 2.2.5 手续费来源说明

**重要**: 手续费不由业务系统计算,而是从第三方支付系统获取。

- 手续费来源:服务商回调中返回的实际扣除手续费
- 存储位置:payment_order.fee_amount 字段
- 获取时机:支付成功回调时,服务商返回手续费金额
- 数据准确性:以服务商返回数据为准

---

### 2.3 分账预留

#### 2.3.1 功能说明

MVP版本只预留分账相关字段,暂不实现具体功能。为后续分账功能做准备。

#### 2.3.2 预留字段 (在payment_order表中)

| 字段名 | 类型 | 长度 | 说明 |
|-------|------|------|------|
| platform_commission | BIGINT | - | 运营平台抽成 (分) |
| community_income | BIGINT | - | 小区收入 (分) |
| split_status | VARCHAR | 20 | 分账状态:not_split/splitting/split_success/split_failed |

#### 2.3.3 后续分账功能设想

**分账规则 (v2.0):**
- 支付成功后,按比例分账给运营平台和小区
- 分账比例可配置 (如:平台10%,小区90%)
- 自动调用服务商分账接口
- 记录分账结果

**分账报表 (v2.0):**
- 按小区统计分账金额
- 按时间统计平台收入
- 分账明细查询

---

## 三、数据库设计

### 3.1 数据来源

支付报表模块不创建新表,直接从现有表读取数据进行统计:

**主要数据表:**
- payment_order (支付订单表) - 主要数据源
- payment_refund (退款记录表) - 退款统计
- payment_provider (支付服务商表) - 服务商信息
- payment_method (支付方式表) - 支付方式信息

### 3.2 统计SQL示例

**按运营平台统计示例:** (v1.1.2新增)
```sql
-- 通过小区支付配置关联运营平台
SELECT
    COALESCE(cpc.platform_id, 0) as platform_id,
    CASE
        WHEN cpc.platform_id IS NULL THEN '独立商户'
        ELSE p.platform_name
    END as platform_name,
    COUNT(DISTINCT o.community_id) as community_count,
    COUNT(*) as trade_count,
    SUM(o.paid_amount) as trade_amount,
    SUM(o.refund_amount) as refund_amount,
    SUM(o.fee_amount) as fee_amount
FROM payment_order o
LEFT JOIN community_payment_config cpc ON o.community_id = cpc.community_id
    AND o.provider_id = cpc.provider_id
LEFT JOIN operating_platform p ON cpc.platform_id = p.id
WHERE o.order_status = 'paid'
  AND o.pay_time >= ?
  AND o.pay_time <= ?
GROUP BY COALESCE(cpc.platform_id, 0),
    CASE WHEN cpc.platform_id IS NULL THEN '独立商户' ELSE p.platform_name END
ORDER BY trade_amount DESC;
```

**按小区统计示例:**
```sql
SELECT
    community_id,
    community_name,
    COUNT(*) as trade_count,
    SUM(paid_amount) as trade_amount,
    COUNT(*) * 100.0 / (SELECT COUNT(*) FROM payment_order WHERE created_at >= ? AND created_at <= ?) as success_rate,
    SUM(refund_amount) as refund_amount,
    SUM(fee_amount) as fee_amount
FROM payment_order
WHERE order_status = 'paid'
  AND pay_time >= ?
  AND pay_time <= ?
GROUP BY community_id, community_name
ORDER BY trade_amount DESC;
```

**按服务商统计手续费示例:**
```sql
SELECT
    p.provider_name,
    COUNT(*) as trade_count,
    SUM(o.paid_amount) as trade_amount,
    SUM(o.fee_amount) as fee_amount,
    SUM(o.fee_amount) * 100.0 / SUM(o.paid_amount) as fee_rate
FROM payment_order o
JOIN payment_provider p ON o.provider_id = p.id
WHERE o.order_status = 'paid'
  AND o.pay_time >= ?
  AND o.pay_time <= ?
GROUP BY p.id, p.provider_name
ORDER BY fee_amount DESC;
```

---

## 四、业务流程

### 4.1 数据统计流程

```
管理员/财务人员
  │
  ├─ 1. 进入支付报表页面
  │
  ├─ 2. 选择统计维度和时间范围
  │    ├─ 维度:小区/业务类型/服务商/支付方式
  │    └─ 时间:今日/本月/自定义等
  │
  ├─ 3. 点击"查询"按钮
  │
  ▼
支付中台 - 报表统计
  │
  ├─ 4. 根据条件查询数据
  │    ├─ 查询支付订单
  │    ├─ 查询退款记录
  │    └─ 关联服务商、支付方式信息
  │
  ├─ 5. 数据汇总计算
  │    ├─ 计算交易笔数、金额
  │    ├─ 计算成功率
  │    ├─ 计算退款金额、退款率
  │    ├─ 计算手续费
  │    └─ 按维度分组汇总
  │
  ├─ 6. 生成图表数据
  │    ├─ 趋势图数据
  │    ├─ 对比图数据
  │    └─ 明细列表数据
  │
  ├─ 7. 返回统计结果
  │
  ▼
前端页面
  │
  ├─ 8. 渲染核心指标看板
  │
  ├─ 9. 渲染趋势图表
  │
  └─ 10. 渲染明细列表
```

---

## 五、异常处理

### 5.1 查询异常

| 异常场景 | 处理方式 |
|---------|---------|
| 时间范围未选择 | 提示"请选择时间范围" |
| 时间范围过大 | 提示"时间范围不能超过1年,请重新选择" |
| 查询超时 | 提示"查询超时,请缩小时间范围或调整筛选条件" |
| 无数据 | 展示"暂无数据" |

### 5.2 导出异常

| 异常场景 | 处理方式 |
|---------|---------|
| 导出数据过多 | 提示"单次最多导出10000条,请缩小范围" |
| 导出失败 | 提示"导出失败,请重试" |

---

## 六、数据约束

### 6.1 时间范围限制

| 快捷选项 | 时间范围 |
|---------|---------|
| 今日 | 当天00:00:00 - 23:59:59 |
| 昨日 | 前一天00:00:00 - 23:59:59 |
| 本周 | 本周周一00:00:00 - 当前时间 |
| 上周 | 上周周一00:00:00 - 上周周日23:59:59 |
| 本月 | 本月1日00:00:00 - 当前时间 |
| 上月 | 上月1日00:00:00 - 上月最后一天23:59:59 |
| 本年 | 本年1月1日00:00:00 - 当前时间 |
| 自定义 | 最多跨度1年 |

### 6.2 导出限制

- 单次最多导出10000条
- 导出文件保留7天后自动删除

---

## 七、与其他模块的关系

### 7.1 依赖关系

本模块依赖以下模块:

1. **支付交易管理模块**
   - 读取 payment_order (支付订单)
   - 读取 payment_refund (退款记录)

2. **支付渠道管理模块**
   - 读取 payment_provider (服务商信息)
   - 读取 payment_method (支付方式信息)

3. **流水与对账模块**
   - 可选引用对账数据

---

## 八、验收标准

### 8.1 功能验收

- [ ] 支持多维度统计 (运营平台/小区/业务类型/服务商/支付方式)
- [ ] 支持按运营平台统计 (v1.1.2新增)
- [ ] 支持多时间维度 (日/周/月/年)
- [ ] 支持核心指标展示
- [ ] 支持趋势图表展示
- [ ] 支持手续费分析
- [ ] 支持明细列表
- [ ] 支持导出Excel
- [ ] 数据统计准确

### 8.2 性能验收

- [ ] 报表查询响应时间 ≤ 3秒 (1个月数据)
- [ ] 报表查询响应时间 ≤ 10秒 (1年数据)
- [ ] 导出10000条数据 ≤ 15秒

### 8.3 数据准确性验收

- [ ] 统计数据与实际订单数据一致
- [ ] 手续费统计准确
- [ ] 成功率计算准确
- [ ] 退款率计算准确

---

## 九、FAQ

### 9.1 为什么手续费从服务商获取而不是计算?

**回答**:
- 手续费由服务商实际扣除,金额最准确
- 不同服务商、不同场景费率可能不同
- 避免计算误差
- 确保财务数据准确

### 9.2 如何理解成功率?

**回答**:
- 成功率 = 支付成功笔数 / 总下单笔数
- 包含用户下单但未支付、订单关闭等情况
- 高成功率(>95%)表示支付流程顺畅

### 9.3 为什么要做手续费分析?

**回答**:
- 了解支付成本
- 对比不同服务商费率
- 为服务商选择提供数据支持
- 为费率谈判提供依据

### 9.4 报表数据多久更新一次?

**回答**:
- 实时统计,点击查询即获取最新数据
- 数据来源于支付订单表,与实际订单同步

### 9.5 为什么只预留分账字段而不实现?

**回答**:
- MVP版本聚焦核心支付功能
- 分账涉及复杂的结算规则
- 需要与服务商分账接口对接
- 预留字段便于后续扩展

### 9.6 v1.1统一状态定义有什么变化?

**回答**: v1.1明确了状态定义的标准:
- 数据库存储:使用英文枚举值 (pending/paid/closed/part_refunded/refunded)
- 页面展示:映射为中文并使用颜色标识
- 统一了各模块的状态显示规范
- 提升用户体验和数据一致性

---

## 变更记录

| 版本 | 日期 | 修改人 | 修改内容 |
|------|------|-------|---------|
| v1.0 | 2026-02-25 | 产品经理 | 初始版本 |
| v1.1 | 2026-02-26 | 产品经理 | 1. 统一订单状态定义(数据库英文,页面中文)<br>2. 新增订单状态映射说明表<br>3. 完善状态颜色标识说明<br>4. 新增FAQ关于状态定义的说明 |