novalon/gym-manage

Fork 0

Files

T

liwentao 54a65b2a74 完善模块4，4.1基础数据统计

2026-06-09 18:16:56 +08:00

23 KiB

Raw Blame History

数据统计模块 API 文档

模块：gym-dataCount
版本：1.0.0
更新日期：2026-06-06

概述

数据统计模块提供会员数据统计、预约数据统计和数据导出功能，支持按日期查询、日期范围查询和汇总统计。

基础信息

Base URL: /api/stats
Content-Type: application/json
响应格式: JSON

1. 会员数据统计

1.1 获取指定日期的会员统计

获取某一天的会员数据统计信息。

请求

GET /api/stats/member/date/{date}

路径参数

参数	类型	必填	说明
date	string	是	统计日期，格式：yyyy-MM-dd

请求示例

curl -X GET "http://localhost:8080/api/stats/member/date/2026-06-01"

响应示例

{
  "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 获取日期范围内的会员统计列表

获取指定日期范围内每天的会员统计数据。

请求

GET /api/stats/member/range?startDate=2026-06-01&endDate=2026-06-05

查询参数

参数	类型	必填	说明
startDate	string	是	开始日期，格式：yyyy-MM-dd
endDate	string	是	结束日期，格式：yyyy-MM-dd

请求示例

curl -X GET "http://localhost:8080/api/stats/member/range?startDate=2026-06-01&endDate=2026-06-03"

响应示例

[
  {
    "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 获取会员统计汇总

获取指定日期范围内的会员数据汇总统计。

请求

GET /api/stats/member/summary?startDate=2026-06-01&endDate=2026-06-30

查询参数

参数	类型	必填	说明
startDate	string	是	开始日期，格式：yyyy-MM-dd
endDate	string	是	结束日期，格式：yyyy-MM-dd

请求示例

curl -X GET "http://localhost:8080/api/stats/member/summary?startDate=2026-06-01&endDate=2026-06-06"

响应示例

{
  "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 获取指定日期的预约统计

获取某一天的团课预约数据统计信息。

请求

GET /api/stats/booking/date/{date}

路径参数

参数	类型	必填	说明
date	string	是	统计日期，格式：yyyy-MM-dd

请求示例

curl -X GET "http://localhost:8080/api/stats/booking/date/2026-06-01"

响应示例

{
  "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 获取日期范围内的预约统计列表

获取指定日期范围内每天的预约统计数据。

请求

GET /api/stats/booking/range?startDate=2026-06-01&endDate=2026-06-05

查询参数

参数	类型	必填	说明
startDate	string	是	开始日期，格式：yyyy-MM-dd
endDate	string	是	结束日期，格式：yyyy-MM-dd

请求示例

curl -X GET "http://localhost:8080/api/stats/booking/range?startDate=2026-06-01&endDate=2026-06-03"

响应示例

[
  {
    "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 获取预约统计汇总

获取指定日期范围内的预约数据汇总统计。

请求

GET /api/stats/booking/summary?startDate=2026-06-01&endDate=2026-06-30

查询参数

参数	类型	必填	说明
startDate	string	是	开始日期，格式：yyyy-MM-dd
endDate	string	是	结束日期，格式：yyyy-MM-dd

请求示例

curl -X GET "http://localhost:8080/api/stats/booking/summary?startDate=2026-06-01&endDate=2026-06-06"

响应示例

{
  "startDate": "2026-06-01",
  "endDate": "2026-06-06",
  "totalBookings": 172,
  "cancelledBookings": 16,
  "attendedBookings": 156,
  "cancellationRate": 9.30,
  "attendanceRate": 90.70
}

3. 签到数据统计

3.1 获取签到统计

获取指定日期范围内的签到统计数据。

请求

GET /api/checkIn/statistics

查询参数

参数	类型	必填	说明
startDate	string	是	开始日期，格式：yyyy-MM-dd
endDate	string	是	结束日期，格式：yyyy-MM-dd

请求示例

curl -X GET "http://localhost:8080/api/checkIn/statistics?startDate=2026-06-01&endDate=2026-06-06"

响应示例

{
  "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 获取每日签到统计

获取指定日期范围内每天的签到统计列表。

请求

GET /api/checkIn/daily-stats?startDate=2026-06-01&endDate=2026-06-05

查询参数

参数	类型	必填	说明
startDate	string	是	开始日期，格式：yyyy-MM-dd
endDate	string	是	结束日期，格式：yyyy-MM-dd

请求示例

curl -X GET "http://localhost:8080/api/checkIn/daily-stats?startDate=2026-06-01&endDate=2026-06-03"

响应示例

[
  {
    "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文件。

请求

GET /api/stats/export/member?startDate=2026-06-01&endDate=2026-06-30

查询参数

参数	类型	必填	说明
startDate	string	是	开始日期，格式：yyyy-MM-dd
endDate	string	是	结束日期，格式：yyyy-MM-dd

请求示例

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格式示例

统计日期,新增会员数,活跃会员数,总会员数,男性会员数,女性会员数,购卡人数,平均年龄
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文件。

请求

GET /api/stats/export/booking?startDate=2026-06-01&endDate=2026-06-30

查询参数

参数	类型	必填	说明
startDate	string	是	开始日期，格式：yyyy-MM-dd
endDate	string	是	结束日期，格式：yyyy-MM-dd

请求示例

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格式示例

统计日期,预约总数,取消预约数,实际到场数,取消率(%),到场率(%),热门课程,热门课程预约数,团课总数,满员课程数
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文件。

请求

GET /api/checkIn/records/export?startDate=2026-06-01&endDate=2026-06-30

查询参数

参数	类型	必填	说明
startDate	string	是	开始日期，格式：yyyy-MM-dd
endDate	string	是	结束日期，格式：yyyy-MM-dd

请求示例

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格式示例

签到时间,会员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文件。

请求

GET /api/stats/export/all?startDate=2026-06-01&endDate=2026-06-30

查询参数

参数	类型	必填	说明
startDate	string	是	开始日期，格式：yyyy-MM-dd
endDate	string	是	结束日期，格式：yyyy-MM-dd

请求示例

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格式示例

=== 会员数据统计 ===
统计日期,新增会员数,活跃会员数,总会员数,男性会员数,女性会员数,购卡人数,平均年龄
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. 错误响应

所有接口在发生错误时返回统一的错误格式：

{
  "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：获取单日会员统计

curl -X GET "http://localhost:8080/api/stats/member/date/2026-06-01"

预期结果：

{
  "date": "2026-06-01",
  "newMembers": 5,
  "activeMembers": 0,
  "retainedMembers": 0,
  "totalMembers": 19,
  "maleMembers": 10,
  "femaleMembers": 9,
  "cardPurchaseCount": 19,
  "averageAge": 29.5
}

测试2：获取日期范围会员统计

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：获取会员统计汇总

curl -X GET "http://localhost:8080/api/stats/member/summary?startDate=2026-06-01&endDate=2026-06-06"

预期结果：

{
  "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：获取单日预约统计

curl -X GET "http://localhost:8080/api/stats/booking/date/2026-06-01"

预期结果：

{
  "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：获取日期范围预约统计

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：获取预约统计汇总

curl -X GET "http://localhost:8080/api/stats/booking/summary?startDate=2026-06-01&endDate=2026-06-06"

预期结果：

{
  "startDate": "2026-06-01",
  "endDate": "2026-06-06",
  "totalBookings": 172,
  "cancelledBookings": 16,
  "attendedBookings": 156,
  "cancellationRate": 9.30,
  "attendanceRate": 90.70
}

9.2.3 数据导出

测试7：导出会员统计数据

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：导出预约统计数据

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：导出全部统计数据

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：测试单日统计

# 测试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：测试一周统计

# 测试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：测试数据导出

# 导出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：日期格式错误

curl -X GET "http://localhost:8080/api/stats/member/date/2026/06/01"

预期结果：HTTP 400 Bad Request

测试11：日期范围无效

curl -X GET "http://localhost:8080/api/stats/member/range?startDate=2026-06-06&endDate=2026-06-01"

预期结果：HTTP 400 Bad Request

测试12：日期超出测试数据范围

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}}

23 KiB Raw Blame History Unescape Escape

数据统计模块 API 文档

概述

基础信息

1. 会员数据统计

1.1 获取指定日期的会员统计

1.2 获取日期范围内的会员统计列表

1.3 获取会员统计汇总

2. 预约数据统计

2.1 获取指定日期的预约统计

2.2 获取日期范围内的预约统计列表

2.3 获取预约统计汇总

3. 签到数据统计

3.1 获取签到统计

3.2 获取每日签到统计

4. 数据导出

4.1 导出会员统计数据

4.2 导出预约统计数据

4.3 导出签到记录数据

4.4 导出全部统计数据

5. 错误响应

6. 定时任务

7. 数据来源

8. 技术实现

附录：接口列表汇总

9. 测试指南

9.1 测试数据说明

会员数据分布

预约数据分布

9.2 测试用例

9.2.1 会员数据统计

9.2.2 预约数据统计

9.2.3 数据导出

9.3 测试参数说明

日期参数格式

日期范围参数

9.4 常见测试场景

场景1：测试单日统计

场景2：测试一周统计

场景3：测试数据导出

9.5 错误测试用例

测试10：日期格式错误

测试11：日期范围无效

测试12：日期超出测试数据范围

9.6 使用 Postman 测试

23 KiB

Raw Blame History