[Claude Workbench] Initial commit - preserving existing code

2025-11-14 17:41:15 +08:00
commit 0f7bc05697
587 changed files with 103215 additions and 0 deletions
--- a/docs/admin-payment-user-statistics-api.md
+++ b/docs/admin-payment-user-statistics-api.md
@@ -0,0 +1,230 @@
+# 管理端支付用户统计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. **预测分析**：基于历史数据的趋势预测
+
+
+
+
+