novalon/gym-manage

Fork 0

Files

T

liwentao 7e4035e0ae 完成模块4，4.1基础信息统计

2026-06-09 23:04:43 +08:00

12 KiB

Raw Blame History

数据统计模块 API 文档

文档版本: v1.0
创建日期: 2026-06-09
作者: system
状态: 正式发布

📋 目录

概述
基础路径
统计数据接口
数据模型
状态码说明
业务规则

概述

数据统计模块提供健身房会员、预约、签到数据的统计功能，支持按日、周、月周期统计，并提供Excel导出功能。采用 Spring WebFlux 响应式编程，统计结果通过 Redis 缓存提高查询性能。

基础路径

所有接口的基础路径为: http://{host}:{port}/api/datacount

统计数据接口

获取综合统计数据

属性	值
HTTP方法	GET
接口路径	`/api/datacount/summary`
所属文件	`DataStatisticsHandler.java`

请求参数:

参数名	类型	必填	默认值	说明
statType	string	否	空	统计类型筛选
periodType	string	否	DAY	统计周期：DAY/WEEK/MONTH
startTime	string	否	自动计算	开始时间（ISO格式）
endTime	string	否	自动计算	结束时间（ISO格式）

请求示例:

# 1. 使用周期类型查询今日统计
GET /api/datacount/summary?periodType=DAY

# 2. 使用周期类型查询本周统计
GET /api/datacount/summary?periodType=WEEK

# 3. 使用周期类型查询本月统计
GET /api/datacount/summary?periodType=MONTH

# 4. 使用自定义时间范围查询
GET /api/datacount/summary?startTime=2026-06-01T00:00:00&endTime=2026-06-07T23:59:59

# 5. 带统计类型筛选
GET /api/datacount/summary?statType=member&periodType=WEEK

成功响应 (200 OK):

{
  "statDate": "2026-06-09",
  "generatedAt": "2026-06-09T10:30:00",
  "memberStatistics": {
    "statDate": "2026-06-09",
    "newMembers": 5,
    "activeMembers": 120,
    "totalMembers": 500,
    "signInMembers": 85,
    "bookingMembers": 45,
    "cancelMembers": 5
  },
  "bookingStatistics": {
    "statDate": "2026-06-09",
    "totalBookings": 60,
    "cancelBookings": 10,
    "attendBookings": 45,
    "absentBookings": 5,
    "attendRate": 75.0,
    "cancelRate": 16.67
  },
  "signInStatistics": {
    "statDate": "2026-06-09",
    "totalSignIns": 95,
    "successSignIns": 92,
    "failSignIns": 3,
    "successRate": 96.84,
    "signInTypeDistribution": {
      "QR_CODE": 60,
      "MANUAL": 25,
      "FACE": 10
    }
  }
}

获取会员统计数据

属性	值
HTTP方法	GET
接口路径	`/api/datacount/member`
所属文件	`DataStatisticsHandler.java`

请求参数:

参数名	类型	必填	默认值	说明
periodType	string	否	DAY	统计周期：DAY/WEEK/MONTH
startTime	string	否	自动计算	开始时间
endTime	string	否	自动计算	结束时间

请求示例:

# 1. 查询今日会员统计
GET /api/datacount/member

# 2. 查询本周会员统计
GET /api/datacount/member?periodType=WEEK

# 3. 查询指定时间范围的会员统计
GET /api/datacount/member?startTime=2026-06-01T00:00:00&endTime=2026-06-30T23:59:59

成功响应 (200 OK):

{
  "statDate": "2026-06-09",
  "newMembers": 5,
  "activeMembers": 120,
  "totalMembers": 500,
  "signInMembers": 85,
  "bookingMembers": 45,
  "cancelMembers": 5
}

获取预约统计数据

属性	值
HTTP方法	GET
接口路径	`/api/datacount/booking`
所属文件	`DataStatisticsHandler.java`

请求参数:

参数名	类型	必填	默认值	说明
periodType	string	否	DAY	统计周期：DAY/WEEK/MONTH
startTime	string	否	自动计算	开始时间
endTime	string	否	自动计算	结束时间

请求示例:

# 1. 查询今日预约统计
GET /api/datacount/booking

# 2. 查询本月预约统计
GET /api/datacount/booking?periodType=MONTH

# 3. 查询指定日期范围的预约统计
GET /api/datacount/booking?startTime=2026-06-01T00:00:00&endTime=2026-06-15T23:59:59

成功响应 (200 OK):

{
  "statDate": "2026-06-09",
  "totalBookings": 60,
  "cancelBookings": 10,
  "attendBookings": 45,
  "absentBookings": 5,
  "attendRate": 75.0,
  "cancelRate": 16.67
}

获取签到统计数据

属性	值
HTTP方法	GET
接口路径	`/api/datacount/signin`
所属文件	`DataStatisticsHandler.java`

请求参数:

参数名	类型	必填	默认值	说明
periodType	string	否	DAY	统计周期：DAY/WEEK/MONTH
startTime	string	否	自动计算	开始时间
endTime	string	否	自动计算	结束时间

请求示例:

# 1. 查询今日签到统计
GET /api/datacount/signin

# 2. 查询本周签到统计
GET /api/datacount/signin?periodType=WEEK

# 3. 查询指定日期范围的签到统计
GET /api/datacount/signin?startTime=2026-06-01T00:00:00&endTime=2026-06-30T23:59:59

成功响应 (200 OK):

{
  "statDate": "2026-06-09",
  "totalSignIns": 95,
  "successSignIns": 92,
  "failSignIns": 3,
  "successRate": 96.84,
  "signInTypeDistribution": {
    "QR_CODE": 60,
    "MANUAL": 25,
    "FACE": 10
  }
}

查询历史统计数据

属性	值
HTTP方法	GET
接口路径	`/api/datacount/history`
所属文件	`DataStatisticsHandler.java`

请求参数:

参数名	类型	必填	默认值	说明
statType	string	否	空	统计类型：member/booking/signin
startTime	string	是	-	开始日期（格式：yyyy-MM-dd）
endTime	string	是	-	结束日期（格式：yyyy-MM-dd）

请求示例:

# 1. 查询指定日期范围的签到历史统计
GET /api/datacount/history?statType=signin&startTime=2026-06-01&endTime=2026-06-30

# 2. 查询指定日期范围的会员历史统计
GET /api/datacount/history?statType=member&startTime=2026-06-01&endTime=2026-06-15

# 3. 查询指定日期范围的预约历史统计
GET /api/datacount/history?statType=booking&startTime=2026-06-01&endTime=2026-06-30

# 4. 查询所有类型的历史统计（不指定statType）
GET /api/datacount/history?startTime=2026-06-01&endTime=2026-06-07

成功响应 (200 OK):

[
  {
    "statDate": "2026-06-07",
    "totalSignIns": 88,
    "successSignIns": 86,
    "failSignIns": 2,
    "successRate": 97.73,
    "signInTypeDistribution": {
      "QR_CODE": 55,
      "MANUAL": 23,
      "FACE": 10
    }
  },
  {
    "statDate": "2026-06-08",
    "totalSignIns": 92,
    "successSignIns": 90,
    "failSignIns": 2,
    "successRate": 97.83,
    "signInTypeDistribution": {
      "QR_CODE": 58,
      "MANUAL": 24,
      "FACE": 10
    }
  }
]

导出统计数据

属性	值
HTTP方法	GET
接口路径	`/api/datacount/export`
所属文件	`DataStatisticsHandler.java`

请求参数:

参数名	类型	必填	默认值	说明
periodType	string	否	DAY	统计周期：DAY/WEEK/MONTH
startTime	string	否	自动计算	开始时间
endTime	string	否	自动计算	结束时间

请求示例:

# 1. 导出今日统计数据
GET /api/datacount/export

# 2. 导出本周统计数据
GET /api/datacount/export?periodType=WEEK

# 3. 导出本月统计数据
GET /api/datacount/export?periodType=MONTH

# 4. 导出指定时间范围的统计数据
GET /api/datacount/export?startTime=2026-06-01T00:00:00&endTime=2026-06-30T23:59:59

成功响应 (200 OK):

返回 Excel 文件（.xlsx），包含以下 Sheet：

会员统计: 会员相关统计数据
预约统计: 预约相关统计数据
签到统计: 签到相关统计数据

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

数据模型

StatisticsQuery（查询条件）

字段名	类型	说明
statType	String	统计类型筛选
periodType	String	统计周期：DAY/WEEK/MONTH
startTime	LocalDateTime	开始时间
endTime	LocalDateTime	结束时间

StatisticsSummary（统计汇总）

字段名	类型	说明
statDate	String	统计日期
generatedAt	String	生成时间
memberStatistics	MemberStatistics	会员统计数据
bookingStatistics	BookingStatistics	预约统计数据
signInStatistics	SignInStatistics	签到统计数据

MemberStatistics（会员统计）

字段名	类型	说明
statDate	String	统计日期
newMembers	Long	新增会员数
activeMembers	Long	活跃会员数
totalMembers	Long	累计会员总数
signInMembers	Long	签到会员数
bookingMembers	Long	预约会员数
cancelMembers	Long	取消预约会员数

BookingStatistics（预约统计）

字段名	类型	说明
statDate	String	统计日期
totalBookings	Long	预约总数
cancelBookings	Long	取消预约数
attendBookings	Long	出席预约数
absentBookings	Long	缺席预约数
attendRate	Double	出席率（%）
cancelRate	Double	取消率（%）

SignInStatistics（签到统计）

字段名	类型	说明
statDate	String	统计日期
totalSignIns	Long	签到总次数
successSignIns	Long	成功签到次数
failSignIns	Long	失败签到次数
successRate	Double	签到成功率（%）
signInTypeDistribution	Map<String, Long>	签到类型分布

状态码说明

状态码	说明
200	请求成功
400	请求参数错误
500	服务器内部错误

业务规则

统计周期: 支持按日、周、月统计
- DAY: 当天 00:00:00 - 当前时间
- WEEK: 本周一 00:00:00 - 本周日 23:59:59
- MONTH: 本月1日 00:00:00 - 本月最后一天 23:59:59
数据保留: 统计数据缓存30天，业务记录永久保存
缓存策略: 查询结果缓存1小时，统计数据缓存30天
定时任务:
- 每日凌晨2点执行前一天的日统计
- 每周一凌晨3点执行上周的周统计
- 每月1日凌晨3点执行上月的月统计
- 每月15日凌晨4点清理30天前的旧数据
数据导出: 支持Excel格式导出，包含会员、预约、签到三个Sheet

12 KiB Raw Blame History Unescape Escape

数据统计模块 API 文档

📋 目录

概述

基础路径

统计数据接口

获取综合统计数据

获取会员统计数据

获取预约统计数据

获取签到统计数据

查询历史统计数据

导出统计数据

数据模型

StatisticsQuery（查询条件）

StatisticsSummary（统计汇总）

MemberStatistics（会员统计）

BookingStatistics（预约统计）

SignInStatistics（签到统计）

状态码说明

业务规则

12 KiB

Raw Blame History