# 管理端支付用户统计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. **预测分析**：基于历史数据的趋势预测