# 数据统计模块 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