453 lines
12 KiB
Markdown
453 lines
12 KiB
Markdown
# 数据统计模块 API 文档
|
||
|
||
> **文档版本**: v1.0
|
||
> **创建日期**: 2026-06-09
|
||
> **作者**: system
|
||
> **状态**: 正式发布
|
||
|
||
---
|
||
|
||
## 📋 目录
|
||
|
||
1. [概述](#概述)
|
||
2. [基础路径](#基础路径)
|
||
3. [统计数据接口](#统计数据接口)
|
||
- [获取综合统计数据](#获取综合统计数据)
|
||
- [获取会员统计数据](#获取会员统计数据)
|
||
- [获取预约统计数据](#获取预约统计数据)
|
||
- [获取签到统计数据](#获取签到统计数据)
|
||
- [查询历史统计数据](#查询历史统计数据)
|
||
- [导出统计数据](#导出统计数据)
|
||
4. [数据模型](#数据模型)
|
||
- [StatisticsQuery（查询条件）](#StatisticsQuery查询条件)
|
||
- [StatisticsSummary（统计汇总）](#StatisticsSummary统计汇总)
|
||
- [MemberStatistics（会员统计）](#MemberStatistics会员统计)
|
||
- [BookingStatistics（预约统计）](#BookingStatistics预约统计)
|
||
- [SignInStatistics（签到统计）](#SignInStatistics签到统计)
|
||
5. [状态码说明](#状态码说明)
|
||
6. [业务规则](#业务规则)
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
数据统计模块提供健身房会员、预约、签到数据的统计功能，支持按日、周、月周期统计，并提供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格式） |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
# 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):
|
||
|
||
```json
|
||
{
|
||
"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 | 否 | 自动计算 | 结束时间 |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
# 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):
|
||
|
||
```json
|
||
{
|
||
"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 | 否 | 自动计算 | 结束时间 |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
# 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):
|
||
|
||
```json
|
||
{
|
||
"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 | 否 | 自动计算 | 结束时间 |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
# 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):
|
||
|
||
```json
|
||
{
|
||
"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） |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
# 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):
|
||
|
||
```json
|
||
[
|
||
{
|
||
"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 | 否 | 自动计算 | 结束时间 |
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
# 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 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 业务规则
|
||
|
||
1. **统计周期**: 支持按日、周、月统计
|
||
- DAY: 当天 00:00:00 - 当前时间
|
||
- WEEK: 本周一 00:00:00 - 本周日 23:59:59
|
||
- MONTH: 本月1日 00:00:00 - 本月最后一天 23:59:59
|
||
|
||
2. **数据保留**: 统计数据缓存30天，业务记录永久保存
|
||
|
||
3. **缓存策略**: 查询结果缓存1小时，统计数据缓存30天
|
||
|
||
4. **定时任务**:
|
||
- 每日凌晨2点执行前一天的日统计
|
||
- 每周一凌晨3点执行上周的周统计
|
||
- 每月1日凌晨3点执行上月的月统计
|
||
- 每月15日凌晨4点清理30天前的旧数据
|
||
|
||
5. **数据导出**: 支持Excel格式导出，包含会员、预约、签到三个Sheet
|