1019 lines
23 KiB
Markdown
1019 lines
23 KiB
Markdown
# 数据统计模块 API 文档
|
||
|
||
> 模块：gym-dataCount
|
||
> 版本：1.0.0
|
||
> 更新日期：2026-06-06
|
||
|
||
## 概述
|
||
|
||
数据统计模块提供会员数据统计、预约数据统计和数据导出功能，支持按日期查询、日期范围查询和汇总统计。
|
||
|
||
---
|
||
|
||
## 基础信息
|
||
|
||
- **Base URL**: `/api/stats`
|
||
- **Content-Type**: `application/json`
|
||
- **响应格式**: JSON
|
||
|
||
---
|
||
|
||
## 1. 会员数据统计
|
||
|
||
### 1.1 获取指定日期的会员统计
|
||
|
||
获取某一天的会员数据统计信息。
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/stats/member/date/{date}
|
||
```
|
||
|
||
**路径参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| date | string | 是 | 统计日期，格式：yyyy-MM-dd |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/member/date/2026-06-01"
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"date": "2026-06-01",
|
||
"newMembers": 5,
|
||
"activeMembers": 0,
|
||
"retainedMembers": 0,
|
||
"totalMembers": 19,
|
||
"maleMembers": 10,
|
||
"femaleMembers": 9,
|
||
"cardPurchaseCount": 19,
|
||
"averageAge": 29.5
|
||
}
|
||
```
|
||
|
||
**响应字段说明**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|-----|------|------|
|
||
| date | string | 统计日期 |
|
||
| newMembers | integer | 当日新增会员数 |
|
||
| activeMembers | integer | 当日活跃会员数（有会员卡操作的会员） |
|
||
| retainedMembers | integer | 留存会员数 |
|
||
| totalMembers | integer | 总会员数（累计） |
|
||
| maleMembers | integer | 男性会员总数 |
|
||
| femaleMembers | integer | 女性会员总数 |
|
||
| cardPurchaseCount | integer | 当日购卡人数 |
|
||
| averageAge | number | 会员平均年龄 |
|
||
|
||
---
|
||
|
||
### 1.2 获取日期范围内的会员统计列表
|
||
|
||
获取指定日期范围内每天的会员统计数据。
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/stats/member/range?startDate=2026-06-01&endDate=2026-06-05
|
||
```
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| startDate | string | 是 | 开始日期，格式：yyyy-MM-dd |
|
||
| endDate | string | 是 | 结束日期，格式：yyyy-MM-dd |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/member/range?startDate=2026-06-01&endDate=2026-06-03"
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"date": "2026-06-01",
|
||
"newMembers": 5,
|
||
"activeMembers": 0,
|
||
"totalMembers": 19,
|
||
"maleMembers": 10,
|
||
"femaleMembers": 9,
|
||
"cardPurchaseCount": 19,
|
||
"averageAge": 29.5
|
||
},
|
||
{
|
||
"date": "2026-06-02",
|
||
"newMembers": 4,
|
||
"activeMembers": 0,
|
||
"totalMembers": 19,
|
||
"maleMembers": 10,
|
||
"femaleMembers": 9,
|
||
"cardPurchaseCount": 19,
|
||
"averageAge": 29.5
|
||
},
|
||
{
|
||
"date": "2026-06-03",
|
||
"newMembers": 3,
|
||
"activeMembers": 0,
|
||
"totalMembers": 19,
|
||
"maleMembers": 10,
|
||
"femaleMembers": 9,
|
||
"cardPurchaseCount": 19,
|
||
"averageAge": 29.5
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### 1.3 获取会员统计汇总
|
||
|
||
获取指定日期范围内的会员数据汇总统计。
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/stats/member/summary?startDate=2026-06-01&endDate=2026-06-30
|
||
```
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| startDate | string | 是 | 开始日期，格式：yyyy-MM-dd |
|
||
| endDate | string | 是 | 结束日期，格式：yyyy-MM-dd |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/member/summary?startDate=2026-06-01&endDate=2026-06-06"
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"startDate": "2026-06-01",
|
||
"endDate": "2026-06-06",
|
||
"newMembers": 19,
|
||
"activeMembers": 0,
|
||
"totalMembers": 19,
|
||
"maleMembers": 10,
|
||
"femaleMembers": 9,
|
||
"cardPurchaseCount": 19,
|
||
"averageAge": 29.5
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 预约数据统计
|
||
|
||
### 2.1 获取指定日期的预约统计
|
||
|
||
获取某一天的团课预约数据统计信息。
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/stats/booking/date/{date}
|
||
```
|
||
|
||
**路径参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| date | string | 是 | 统计日期，格式：yyyy-MM-dd |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/booking/date/2026-06-01"
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"date": "2026-06-01",
|
||
"totalBookings": 32,
|
||
"cancelledBookings": 5,
|
||
"attendedBookings": 27,
|
||
"bookingSuccessRate": 0.0,
|
||
"cancellationRate": 15.63,
|
||
"attendanceRate": 84.38,
|
||
"popularCourseName": "燃脂单车",
|
||
"popularCourseCount": 19,
|
||
"totalCourses": 3,
|
||
"fullCourses": 1
|
||
}
|
||
```
|
||
|
||
**响应字段说明**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|-----|------|------|
|
||
| date | string | 统计日期 |
|
||
| totalBookings | integer | 预约总数 |
|
||
| cancelledBookings | integer | 取消预约数 |
|
||
| attendedBookings | integer | 实际到场数 |
|
||
| bookingSuccessRate | number | 预约成功率（保留） |
|
||
| cancellationRate | number | 取消率（百分比） |
|
||
| attendanceRate | number | 到场率（百分比） |
|
||
| popularCourseName | string | 最热门课程名称 |
|
||
| popularCourseCount | integer | 热门课程预约数 |
|
||
| totalCourses | integer | 当日团课总数 |
|
||
| fullCourses | integer | 满员课程数 |
|
||
|
||
---
|
||
|
||
### 2.2 获取日期范围内的预约统计列表
|
||
|
||
获取指定日期范围内每天的预约统计数据。
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/stats/booking/range?startDate=2026-06-01&endDate=2026-06-05
|
||
```
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| startDate | string | 是 | 开始日期，格式：yyyy-MM-dd |
|
||
| endDate | string | 是 | 结束日期，格式：yyyy-MM-dd |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/booking/range?startDate=2026-06-01&endDate=2026-06-03"
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"date": "2026-06-01",
|
||
"totalBookings": 32,
|
||
"cancelledBookings": 5,
|
||
"attendedBookings": 27,
|
||
"cancellationRate": 15.63,
|
||
"attendanceRate": 84.38,
|
||
"popularCourseName": "燃脂单车",
|
||
"popularCourseCount": 19,
|
||
"totalCourses": 3,
|
||
"fullCourses": 1
|
||
},
|
||
{
|
||
"date": "2026-06-02",
|
||
"totalBookings": 30,
|
||
"cancelledBookings": 3,
|
||
"attendedBookings": 27,
|
||
"cancellationRate": 10.00,
|
||
"attendanceRate": 90.00,
|
||
"popularCourseName": "流瑜伽",
|
||
"popularCourseCount": 10,
|
||
"totalCourses": 3,
|
||
"fullCourses": 0
|
||
},
|
||
{
|
||
"date": "2026-06-03",
|
||
"totalBookings": 35,
|
||
"cancelledBookings": 4,
|
||
"attendedBookings": 31,
|
||
"cancellationRate": 11.43,
|
||
"attendanceRate": 88.57,
|
||
"popularCourseName": "哈他瑜伽",
|
||
"popularCourseCount": 12,
|
||
"totalCourses": 3,
|
||
"fullCourses": 2
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### 2.3 获取预约统计汇总
|
||
|
||
获取指定日期范围内的预约数据汇总统计。
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/stats/booking/summary?startDate=2026-06-01&endDate=2026-06-30
|
||
```
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| startDate | string | 是 | 开始日期，格式：yyyy-MM-dd |
|
||
| endDate | string | 是 | 结束日期，格式：yyyy-MM-dd |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/booking/summary?startDate=2026-06-01&endDate=2026-06-06"
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"startDate": "2026-06-01",
|
||
"endDate": "2026-06-06",
|
||
"totalBookings": 172,
|
||
"cancelledBookings": 16,
|
||
"attendedBookings": 156,
|
||
"cancellationRate": 9.30,
|
||
"attendanceRate": 90.70
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 签到数据统计
|
||
|
||
### 3.1 获取签到统计
|
||
|
||
获取指定日期范围内的签到统计数据。
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/checkIn/statistics
|
||
```
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| startDate | string | 是 | 开始日期，格式：yyyy-MM-dd |
|
||
| endDate | string | 是 | 结束日期，格式：yyyy-MM-dd |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/checkIn/statistics?startDate=2026-06-01&endDate=2026-06-06"
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"startDate": "2026-06-01",
|
||
"endDate": "2026-06-06",
|
||
"totalSignInCount": 156,
|
||
"successSignInCount": 148,
|
||
"failedSignInCount": 8,
|
||
"successRate": 94.87,
|
||
"avgDailySignIn": 26,
|
||
"mostSignInDay": "2026-06-03",
|
||
"mostSignInCount": 32,
|
||
"qrCodeSignInCount": 120,
|
||
"manualSignInCount": 28,
|
||
"faceSignInCount": 8
|
||
}
|
||
```
|
||
|
||
**响应字段说明**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|-----|------|------|
|
||
| startDate | string | 统计开始日期 |
|
||
| endDate | string | 统计结束日期 |
|
||
| totalSignInCount | integer | 签到总次数 |
|
||
| successSignInCount | integer | 成功签到次数 |
|
||
| failedSignInCount | integer | 失败签到次数 |
|
||
| successRate | number | 签到成功率（百分比） |
|
||
| avgDailySignIn | integer | 日均签到数 |
|
||
| mostSignInDay | string | 签到最多的日期 |
|
||
| mostSignInCount | integer | 单日最多签到数 |
|
||
| qrCodeSignInCount | integer | 扫码签到次数 |
|
||
| manualSignInCount | integer | 手动签到次数 |
|
||
| faceSignInCount | integer | 人脸识别签到次数 |
|
||
|
||
---
|
||
|
||
### 3.2 获取每日签到统计
|
||
|
||
获取指定日期范围内每天的签到统计列表。
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/checkIn/daily-stats?startDate=2026-06-01&endDate=2026-06-05
|
||
```
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| startDate | string | 是 | 开始日期，格式：yyyy-MM-dd |
|
||
| endDate | string | 是 | 结束日期，格式：yyyy-MM-dd |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/checkIn/daily-stats?startDate=2026-06-01&endDate=2026-06-03"
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"date": "2026-06-01",
|
||
"totalSignInCount": 28,
|
||
"successSignInCount": 26,
|
||
"failedSignInCount": 2,
|
||
"successRate": 92.86,
|
||
"qrCodeSignInCount": 22,
|
||
"manualSignInCount": 4,
|
||
"faceSignInCount": 2
|
||
},
|
||
{
|
||
"date": "2026-06-02",
|
||
"totalSignInCount": 24,
|
||
"successSignInCount": 24,
|
||
"failedSignInCount": 0,
|
||
"successRate": 100.00,
|
||
"qrCodeSignInCount": 20,
|
||
"manualSignInCount": 3,
|
||
"faceSignInCount": 1
|
||
},
|
||
{
|
||
"date": "2026-06-03",
|
||
"totalSignInCount": 32,
|
||
"successSignInCount": 30,
|
||
"failedSignInCount": 2,
|
||
"successRate": 93.75,
|
||
"qrCodeSignInCount": 26,
|
||
"manualSignInCount": 4,
|
||
"faceSignInCount": 2
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 数据导出
|
||
|
||
### 4.1 导出会员统计数据
|
||
|
||
导出指定日期范围内的会员统计数据为CSV文件。
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/stats/export/member?startDate=2026-06-01&endDate=2026-06-30
|
||
```
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| startDate | string | 是 | 开始日期，格式：yyyy-MM-dd |
|
||
| endDate | string | 是 | 结束日期，格式：yyyy-MM-dd |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/export/member?startDate=2026-06-01&endDate=2026-06-03" \
|
||
-H "Accept: text/csv" \
|
||
--output member_stats.csv
|
||
```
|
||
|
||
**响应**
|
||
|
||
- **Content-Type**: `text/csv; charset=UTF-8`
|
||
- **Content-Disposition**: `attachment; filename=member_statistics_2026-06-01_2026-06-03.csv`
|
||
|
||
**CSV格式示例**
|
||
|
||
```csv
|
||
统计日期,新增会员数,活跃会员数,总会员数,男性会员数,女性会员数,购卡人数,平均年龄
|
||
2026-06-01,5,0,19,10,9,19,29.5
|
||
2026-06-02,4,0,19,10,9,19,29.5
|
||
2026-06-03,3,0,19,10,9,19,29.5
|
||
```
|
||
|
||
---
|
||
|
||
### 4.2 导出预约统计数据
|
||
|
||
导出指定日期范围内的预约统计数据为CSV文件。
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/stats/export/booking?startDate=2026-06-01&endDate=2026-06-30
|
||
```
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| startDate | string | 是 | 开始日期，格式：yyyy-MM-dd |
|
||
| endDate | string | 是 | 结束日期，格式：yyyy-MM-dd |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/export/booking?startDate=2026-06-01&endDate=2026-06-03" \
|
||
-H "Accept: text/csv" \
|
||
--output booking_stats.csv
|
||
```
|
||
|
||
**响应**
|
||
|
||
- **Content-Type**: `text/csv; charset=UTF-8`
|
||
- **Content-Disposition**: `attachment; filename=booking_statistics_2026-06-01_2026-06-03.csv`
|
||
|
||
**CSV格式示例**
|
||
|
||
```csv
|
||
统计日期,预约总数,取消预约数,实际到场数,取消率(%),到场率(%),热门课程,热门课程预约数,团课总数,满员课程数
|
||
2026-06-01,32,5,27,15.63,84.38,燃脂单车,19,3,1
|
||
2026-06-02,30,3,27,10.00,90.00,流瑜伽,10,3,0
|
||
2026-06-03,35,4,31,11.43,88.57,哈他瑜伽,12,3,2
|
||
```
|
||
|
||
---
|
||
|
||
### 4.3 导出签到记录数据
|
||
|
||
导出指定日期范围内的签到记录数据为CSV文件。
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/checkIn/records/export?startDate=2026-06-01&endDate=2026-06-30
|
||
```
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| startDate | string | 是 | 开始日期，格式：yyyy-MM-dd |
|
||
| endDate | string | 是 | 结束日期，格式：yyyy-MM-dd |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/checkIn/records/export?startDate=2026-06-01&endDate=2026-06-03" \
|
||
-H "Accept: text/csv" \
|
||
--output sign_in_records.csv
|
||
```
|
||
|
||
**响应**
|
||
|
||
- **Content-Type**: `text/csv; charset=UTF-8`
|
||
- **Content-Disposition**: `attachment; filename=sign_in_records_2026-06-01_2026-06-03.csv`
|
||
|
||
**CSV格式示例**
|
||
|
||
```csv
|
||
签到时间,会员ID,会员卡ID,签到方式,签到状态,操作人,来源
|
||
2026-06-01 08:30:00,1,1001,QR_CODE,SUCCESS,张三,MINI_PROGRAM
|
||
2026-06-01 09:15:00,2,1002,MANUAL,SUCCESS,李四,PC_BACKEND
|
||
2026-06-01 10:00:00,3,1003,FACE,SUCCESS,,MINI_PROGRAM
|
||
```
|
||
|
||
---
|
||
|
||
### 4.4 导出全部统计数据
|
||
|
||
导出指定日期范围内的会员和预约统计数据为CSV文件。
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/stats/export/all?startDate=2026-06-01&endDate=2026-06-30
|
||
```
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| startDate | string | 是 | 开始日期，格式：yyyy-MM-dd |
|
||
| endDate | string | 是 | 结束日期，格式：yyyy-MM-dd |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/export/all?startDate=2026-06-01&endDate=2026-06-03" \
|
||
-H "Accept: text/csv" \
|
||
--output all_stats.csv
|
||
```
|
||
|
||
**响应**
|
||
|
||
- **Content-Type**: `text/csv; charset=UTF-8`
|
||
- **Content-Disposition**: `attachment; filename=all_statistics_2026-06-01_2026-06-03.csv`
|
||
|
||
**CSV格式示例**
|
||
|
||
```csv
|
||
=== 会员数据统计 ===
|
||
统计日期,新增会员数,活跃会员数,总会员数,男性会员数,女性会员数,购卡人数,平均年龄
|
||
2026-06-01,5,0,19,10,9,19,29.5
|
||
2026-06-02,4,0,19,10,9,19,29.5
|
||
2026-06-03,3,0,19,10,9,19,29.5
|
||
|
||
=== 预约数据统计 ===
|
||
统计日期,预约总数,取消预约数,实际到场数,取消率(%),到场率(%),热门课程,热门课程预约数,团课总数,满员课程数
|
||
2026-06-01,32,5,27,15.63,84.38,燃脂单车,19,3,1
|
||
2026-06-02,30,3,27,10.00,90.00,流瑜伽,10,3,0
|
||
2026-06-03,35,4,31,11.43,88.57,哈他瑜伽,12,3,2
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 错误响应
|
||
|
||
所有接口在发生错误时返回统一的错误格式：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误描述信息"
|
||
}
|
||
```
|
||
|
||
**常见错误码**
|
||
|
||
| HTTP状态码 | 说明 |
|
||
|-----------|------|
|
||
| 400 Bad Request | 参数格式错误或缺少必填参数 |
|
||
| 404 Not Found | 指定日期的数据不存在 |
|
||
| 500 Internal Server Error | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 6. 定时任务
|
||
|
||
模块内置以下定时任务，自动计算统计数据并缓存到Redis：
|
||
|
||
| 任务名称 | 执行时间 | 说明 |
|
||
|---------|---------|------|
|
||
| 每日统计 | 每日凌晨1点 | 计算前一天的会员和预约统计 |
|
||
| 每周汇总 | 每周一凌晨2点 | 计算上周的汇总统计 |
|
||
| 每月汇总 | 每月1号凌晨3点 | 计算上月的汇总统计 |
|
||
|
||
**缓存策略**
|
||
|
||
- 缓存键前缀：`stats:member:` 和 `stats:booking:`
|
||
- 缓存过期时间：3600秒（1小时）
|
||
- 每日定时任务会自动刷新缓存
|
||
|
||
---
|
||
|
||
## 7. 数据来源
|
||
|
||
统计数据来源于以下数据表：
|
||
|
||
| 统计类型 | 数据表 | 说明 |
|
||
|---------|-------|------|
|
||
| 会员统计 | `member_user` | 会员基本信息表 |
|
||
| 会员卡统计 | `member_card_record` | 会员卡记录表 |
|
||
| 预约统计 | `group_course_booking` | 团课预约记录表 |
|
||
| 课程统计 | `group_course` | 团课课程表 |
|
||
| 签到统计 | `sign_in_record` | 会员到店签到记录表 |
|
||
|
||
---
|
||
|
||
## 8. 技术实现
|
||
|
||
- **框架**: Spring WebFlux（响应式编程）
|
||
- **数据库访问**: Spring Data R2DBC
|
||
- **缓存**: Redis（ReactiveRedisTemplate）
|
||
- **API文档**: OpenAPI 3.0 / Swagger
|
||
- **导出格式**: CSV
|
||
|
||
---
|
||
|
||
## 附录：接口列表汇总
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|-----|------|------|
|
||
| GET | `/api/stats/member/date/{date}` | 获取指定日期会员统计 |
|
||
| GET | `/api/stats/member/range` | 获取日期范围会员统计列表 |
|
||
| GET | `/api/stats/member/summary` | 获取会员统计汇总 |
|
||
| GET | `/api/stats/booking/date/{date}` | 获取指定日期预约统计 |
|
||
| GET | `/api/stats/booking/range` | 获取日期范围预约统计列表 |
|
||
| GET | `/api/stats/booking/summary` | 获取预约统计汇总 |
|
||
| GET | `/api/checkIn/statistics` | 获取签到统计 |
|
||
| GET | `/api/checkIn/daily-stats` | 获取每日签到统计 |
|
||
| GET | `/api/stats/export/member` | 导出会员统计CSV |
|
||
| GET | `/api/stats/export/booking` | 导出预约统计CSV |
|
||
| GET | `/api/stats/export/all` | 导出全部统计CSV |
|
||
| GET | `/api/checkIn/records/export` | 导出签到记录CSV |
|
||
|
||
---
|
||
|
||
## 9. 测试指南
|
||
|
||
### 9.1 测试数据说明
|
||
|
||
数据库已预置测试数据，日期范围为 **2026-06-01 至 2026-06-10**。
|
||
|
||
#### 会员数据分布
|
||
|
||
| 日期 | 新增会员数 | 男性会员 | 女性会员 |
|
||
|------|-----------|---------|---------|
|
||
| 2026-06-01 | 5 | 3 | 2 |
|
||
| 2026-06-02 | 4 | 2 | 2 |
|
||
| 2026-06-03 | 3 | 1 | 2 |
|
||
| 2026-06-04 | 2 | 1 | 1 |
|
||
| 2026-06-05 | 3 | 2 | 1 |
|
||
| 2026-06-06 | 2 | 1 | 1 |
|
||
| **合计** | **19** | **10** | **9** |
|
||
|
||
#### 预约数据分布
|
||
|
||
| 日期 | 预约总数 | 取消预约 | 实际到场 | 满员课程数 |
|
||
|------|---------|---------|---------|-----------|
|
||
| 2026-06-01 | 32 | 5 | 27 | 1 |
|
||
| 2026-06-02 | 30 | 3 | 27 | 0 |
|
||
| 2026-06-03 | 35 | 4 | 31 | 2 |
|
||
| 2026-06-04 | 28 | 2 | 26 | 1 |
|
||
| 2026-06-05 | 25 | 1 | 24 | 0 |
|
||
| 2026-06-06 | 22 | 1 | 21 | 0 |
|
||
|
||
---
|
||
|
||
### 9.2 测试用例
|
||
|
||
#### 9.2.1 会员数据统计
|
||
|
||
**测试1：获取单日会员统计**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/member/date/2026-06-01"
|
||
```
|
||
|
||
**预期结果**：
|
||
```json
|
||
{
|
||
"date": "2026-06-01",
|
||
"newMembers": 5,
|
||
"activeMembers": 0,
|
||
"retainedMembers": 0,
|
||
"totalMembers": 19,
|
||
"maleMembers": 10,
|
||
"femaleMembers": 9,
|
||
"cardPurchaseCount": 19,
|
||
"averageAge": 29.5
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
**测试2：获取日期范围会员统计**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/member/range?startDate=2026-06-01&endDate=2026-06-03"
|
||
```
|
||
|
||
**预期结果**：返回3条记录，分别为 2026-06-01、2026-06-02、2026-06-03 的统计数据。
|
||
|
||
---
|
||
|
||
**测试3：获取会员统计汇总**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/member/summary?startDate=2026-06-01&endDate=2026-06-06"
|
||
```
|
||
|
||
**预期结果**：
|
||
```json
|
||
{
|
||
"startDate": "2026-06-01",
|
||
"endDate": "2026-06-06",
|
||
"newMembers": 19,
|
||
"activeMembers": 0,
|
||
"totalMembers": 19,
|
||
"maleMembers": 10,
|
||
"femaleMembers": 9,
|
||
"cardPurchaseCount": 19,
|
||
"averageAge": 29.5
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 9.2.2 预约数据统计
|
||
|
||
**测试4：获取单日预约统计**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/booking/date/2026-06-01"
|
||
```
|
||
|
||
**预期结果**：
|
||
```json
|
||
{
|
||
"date": "2026-06-01",
|
||
"totalBookings": 32,
|
||
"cancelledBookings": 5,
|
||
"attendedBookings": 27,
|
||
"bookingSuccessRate": 0.0,
|
||
"cancellationRate": 15.63,
|
||
"attendanceRate": 84.38,
|
||
"popularCourseName": "燃脂单车",
|
||
"popularCourseCount": 19,
|
||
"totalCourses": 3,
|
||
"fullCourses": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
**测试5：获取日期范围预约统计**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/booking/range?startDate=2026-06-01&endDate=2026-06-03"
|
||
```
|
||
|
||
**预期结果**：返回3条记录，分别为 2026-06-01、2026-06-02、2026-06-03 的统计数据。
|
||
|
||
---
|
||
|
||
**测试6：获取预约统计汇总**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/booking/summary?startDate=2026-06-01&endDate=2026-06-06"
|
||
```
|
||
|
||
**预期结果**：
|
||
```json
|
||
{
|
||
"startDate": "2026-06-01",
|
||
"endDate": "2026-06-06",
|
||
"totalBookings": 172,
|
||
"cancelledBookings": 16,
|
||
"attendedBookings": 156,
|
||
"cancellationRate": 9.30,
|
||
"attendanceRate": 90.70
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 9.2.3 数据导出
|
||
|
||
**测试7：导出会员统计数据**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/export/member?startDate=2026-06-01&endDate=2026-06-03" \
|
||
-H "Accept: text/csv" \
|
||
--output member_stats.csv
|
||
```
|
||
|
||
**预期结果**：下载 CSV 文件，包含 2026-06-01 至 2026-06-03 的会员统计数据。
|
||
|
||
---
|
||
|
||
**测试8：导出预约统计数据**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/export/booking?startDate=2026-06-01&endDate=2026-06-03" \
|
||
-H "Accept: text/csv" \
|
||
--output booking_stats.csv
|
||
```
|
||
|
||
**预期结果**：下载 CSV 文件，包含 2026-06-01 至 2026-06-03 的预约统计数据。
|
||
|
||
---
|
||
|
||
**测试9：导出全部统计数据**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/export/all?startDate=2026-06-01&endDate=2026-06-03" \
|
||
-H "Accept: text/csv" \
|
||
--output all_stats.csv
|
||
```
|
||
|
||
**预期结果**：下载 CSV 文件，包含会员和预约的完整统计数据。
|
||
|
||
---
|
||
|
||
### 9.3 测试参数说明
|
||
|
||
#### 日期参数格式
|
||
|
||
所有日期参数必须使用 `yyyy-MM-dd` 格式，例如：
|
||
- ✅ `2026-06-01`
|
||
- ❌ `2026/06/01`
|
||
- ❌ `2026-6-1`
|
||
- ❌ `06-01-2026`
|
||
|
||
#### 日期范围参数
|
||
|
||
| 参数 | 说明 | 示例 |
|
||
|-----|------|------|
|
||
| startDate | 开始日期（包含） | `2026-06-01` |
|
||
| endDate | 结束日期（包含） | `2026-06-06` |
|
||
|
||
**注意事项**：
|
||
- `startDate` 必须 ≤ `endDate`
|
||
- 日期范围不能超过 365 天
|
||
- 日期必须在测试数据范围内（2026-06-01 至 2026-06-10）
|
||
|
||
---
|
||
|
||
### 9.4 常见测试场景
|
||
|
||
#### 场景1：测试单日统计
|
||
|
||
```bash
|
||
# 测试6月1日的会员和预约统计
|
||
curl "http://localhost:8080/api/stats/member/date/2026-06-01"
|
||
curl "http://localhost:8080/api/stats/booking/date/2026-06-01"
|
||
```
|
||
|
||
---
|
||
|
||
#### 场景2：测试一周统计
|
||
|
||
```bash
|
||
# 测试6月第一周的统计
|
||
curl "http://localhost:8080/api/stats/member/summary?startDate=2026-06-01&endDate=2026-06-06"
|
||
curl "http://localhost:8080/api/stats/booking/summary?startDate=2026-06-01&endDate=2026-06-06"
|
||
```
|
||
|
||
---
|
||
|
||
#### 场景3：测试数据导出
|
||
|
||
```bash
|
||
# 导出6月前3天的所有统计数据
|
||
curl "http://localhost:8080/api/stats/export/all?startDate=2026-06-01&endDate=2026-06-03" \
|
||
--output test_data.csv
|
||
```
|
||
|
||
---
|
||
|
||
### 9.5 错误测试用例
|
||
|
||
#### 测试10：日期格式错误
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/member/date/2026/06/01"
|
||
```
|
||
|
||
**预期结果**：HTTP 400 Bad Request
|
||
|
||
---
|
||
|
||
#### 测试11：日期范围无效
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/member/range?startDate=2026-06-06&endDate=2026-06-01"
|
||
```
|
||
|
||
**预期结果**：HTTP 400 Bad Request
|
||
|
||
---
|
||
|
||
#### 测试12：日期超出测试数据范围
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/stats/member/date/2025-01-01"
|
||
```
|
||
|
||
**预期结果**：HTTP 404 Not Found 或返回空数据
|
||
|
||
---
|
||
|
||
### 9.6 使用 Postman 测试
|
||
|
||
导入以下环境变量到 Postman：
|
||
|
||
| 变量名 | 值 | 说明 |
|
||
|-------|---|------|
|
||
| `base_url` | `http://localhost:8080` | API 基础地址 |
|
||
| `test_start_date` | `2026-06-01` | 测试开始日期 |
|
||
| `test_end_date` | `2026-06-06` | 测试结束日期 |
|
||
|
||
示例请求：
|
||
|
||
```
|
||
GET {{base_url}}/api/stats/member/date/2026-06-01
|
||
GET {{base_url}}/api/stats/member/range?startDate={{test_start_date}}&endDate={{test_end_date}}
|
||
GET {{base_url}}/api/stats/booking/summary?startDate={{test_start_date}}&endDate={{test_end_date}}
|
||
```
|