231 lines
6.0 KiB
Markdown
231 lines
6.0 KiB
Markdown
# 管理端支付用户统计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 |
|
||
|
||
**响应数据**：
|
||
```json
|
||
{
|
||
"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 |
|
||
|
||
**响应数据**：
|
||
```json
|
||
{
|
||
"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()` 验证管理员身份
|
||
|
||
## 错误处理
|
||
|
||
```json
|
||
{
|
||
"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. **预测分析**：基于历史数据的趋势预测
|
||
|
||
|
||
|
||
|
||
|