1818web-hoduan/docs/admin-payment-user-statistics-api.md

管理端支付用户统计API接口文档

概述

本功能为管理端提供了完整的真实支付用户统计分析功能，包括：

• 支付用户数量和信息统计
• 支付金额分布分析
• 时间维度的支付统计
• 复购用户和高消费用户分析
• 支持自定义时间段查询

技术实现

核心文件结构

src/main/java/com/dora/
├── dto/AdminPaymentUserDto.java                    # 数据传输对象
├── mapper/AdminPaymentUserMapper.java             # 数据访问接口
├── service/AdminPaymentUserService.java           # 服务接口
├── service/impl/AdminPaymentUserServiceImpl.java  # 服务实现
└── controller/AdminPaymentUserController.java     # 控制器

src/main/resources/mapper/
└── AdminPaymentUserMapper.xml                     # SQL映射文件

数据库依赖

• order 表：订单数据（status=1表示已支付）
• user 表：用户基本信息
• membership_plan 表：会员套餐信息

API接口详情

1. 获取支付用户统计数据

接口地址：GET /admin/payment-users/statistics

请求参数：

参数名	类型	必填	说明	示例
startDate	String	否	开始日期	2024-01-01
endDate	String	否	结束日期	2024-01-31

响应数据：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "overview": {
      "totalPaymentUsers": 150,
      "totalPaymentOrders": 200,
      "totalPaymentAmount": 25000.00,
      "avgOrderAmount": 125.00,
      "newVipUsers": 80,
      "newSvipUsers": 30,
      "repeatPurchaseUsers": 45,
      "firstTimeUsers": 105
    },
    "paymentUsers": [
      {
        "userId": 1001,
        "username": "用户001",
        "phone": "138****1234",
        "role": 2,
        "orderCount": 3,
        "totalAmount": 299.00,
        "lastPaidAt": "2024-01-15T14:30:00",
        "firstPaidAt": "2024-01-01T10:15:00",
        "paymentMethod": 2,
        "isRepeatUser": true
      }
    ],
    "amountDistribution": {
      "users0To50": 20,
      "users50To100": 35,
      "users100To200": 45,
      "users200To500": 35,
      "usersAbove500": 15
    },
    "dailyStats": [
      {
        "date": "2024-01-01",
        "paymentUsers": 12,
        "paymentOrders": 15,
        "paymentAmount": 1500.00,
        "newVipUsers": 8,
        "newSvipUsers": 2
      }
    ]
  }
}

2. 获取支付用户详情列表

接口地址：GET /admin/payment-users/list

请求参数：

参数名	类型	必填	说明	示例
startDate	String	否	开始日期	2024-01-01
endDate	String	否	结束日期	2024-01-31
role	Integer	否	用户角色筛选	2
onlyRepeatUsers	Boolean	否	只显示复购用户	true
minAmount	BigDecimal	否	最小支付金额	100
maxAmount	BigDecimal	否	最大支付金额	500
sortField	String	否	排序字段	totalAmount
sortOrder	String	否	排序方向	DESC
page	Integer	否	页码	1
size	Integer	否	每页大小	10

响应数据：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "users": [...],
    "total": 150,
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 15
  }
}

3. 便捷统计接口

3.1 今日支付用户统计

接口地址：GET /admin/payment-users/statistics/today

3.2 本周支付用户统计

接口地址：GET /admin/payment-users/statistics/week

3.3 本月支付用户统计

接口地址：GET /admin/payment-users/statistics/month

3.4 复购用户列表

接口地址：GET /admin/payment-users/list/repeat-users

请求参数：

参数名	类型	必填	说明	示例
startDate	String	否	开始日期	2024-01-01
endDate	String	否	结束日期	2024-01-31
page	Integer	否	页码	1
size	Integer	否	每页大小	10

3.5 高消费用户列表

接口地址：GET /admin/payment-users/list/top-spenders

请求参数：同复购用户列表

数据字段说明

用户角色定义

• 1：普通用户
• 2：VIP用户
• 3：SVIP用户

支付方式定义

• 1：支付宝
• 2：微信支付

订单状态定义

• 0：待支付
• 1：已完成（已支付）
• 2：已取消
• 3：支付失败

性能优化

1. SQL优化：使用了合适的索引和查询优化
2. 分页查询：支持大数据量分页显示
3. 缓存机制：可根据需要添加Redis缓存
4. 异步处理：适用于大数据量统计

权限控制

• 所有接口都需要管理员权限验证
• 使用 AdminSecurityUtil.getCurrentAdminId() 验证管理员身份

错误处理

{
  "code": 500,
  "message": "查询支付用户统计数据失败: 具体错误信息",
  "data": null
}

使用示例

查询本月所有支付用户统计

GET /admin/payment-users/statistics/month

查询指定时间段的复购用户

GET /admin/payment-users/list/repeat-users?startDate=2024-01-01&endDate=2024-01-31&page=1&size=10

查询高消费VIP用户（支付金额>200元）

GET /admin/payment-users/list?role=2&minAmount=200&sortField=totalAmount&sortOrder=DESC&page=1&size=20

注意事项

1. 时间范围：如果不指定时间范围，将统计所有历史数据
2. 数据一致性：基于已支付订单（status=1）进行统计
3. 复购定义：有多次支付记录的用户
4. 新增VIP/SVIP：根据购买的会员套餐target_role字段判断
5. 金额分布：按用户总支付金额进行区间统计

扩展功能建议

1. 导出功能：支持Excel导出统计数据
2. 图表展示：前端配合实现数据可视化
3. 定时报告：定期生成支付用户分析报告
4. 对比分析：不同时间段的数据对比
5. 预测分析：基于历史数据的趋势预测