# 页面点击记录 API 接口文档

## 目录
- [概述](#概述)
- [基础信息](#基础信息)
- [数据模型](#数据模型)
- [接口列表](#接口列表)
  - [1. 记录页面点击](#1-记录页面点击)
  - [2. 获取页面点击统计](#2-获取页面点击统计)
  - [3. 获取今日点击统计汇总](#3-获取今日点击统计汇总)
  - [4. 获取指定页面的点击量](#4-获取指定页面的点击量)
- [错误码说明](#错误码说明)
- [使用示例](#使用示例)

---

## 概述

页面点击记录功能用于统计首页和视频页面的访问量。数据存储在 Redis 中，自动保存 7 天，支持按 IP 去重（同一 IP 每天只计数一次）。

**支持的页面类型：**
- `home` - 首页
- `video` - 视频页面

---

## 基础信息

**Base URL:** `/api/page-clicks`

**认证方式：**
- 记录接口：无需认证（公开接口）
- 查询接口：需要管理员权限（Bearer Token）

**数据存储：**
- 存储位置：Redis
- 保留时间：7 天（自动过期）
- 去重机制：同一 IP 每天只计数一次

---

## 数据模型

### PageType（页面类型枚举）

```typescript
enum PageType {
  HOME = 'home',    // 首页
  VIDEO = 'video'   // 视频页面
}
```

### 请求/响应数据结构

#### 记录点击请求
```json
{
  "pageType": "home"  // 或 "video"
}
```

#### 统计响应
```json
{
  "success": true,
  "statistics": [
    {
      "pageType": "home",
      "date": "2024-01-15",
      "clickCount": 1234
    }
  ],
  "total": [
    {
      "pageType": "home",
      "totalClicks": 5678
    }
  ]
}
```

---

## 接口列表

### 1. 记录页面点击

记录用户访问首页或视频页面的点击。

**接口地址：** `POST /api/page-clicks/click`

**认证要求：** 无需认证（公开接口）

**请求头：**
```
Content-Type: application/json
```

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageType | string | 是 | 页面类型，必须是 `"home"` 或 `"video"` |

**请求示例：**
```bash
curl -X POST http://your-domain.com/api/page-clicks/click \
  -H "Content-Type: application/json" \
  -d '{
    "pageType": "home"
  }'
```

**响应示例：**

成功响应（200）：
```json
{
  "success": true,
  "pageType": "home",
  "clickCount": 1234,
  "message": "点击记录成功"
}
```

错误响应（400）：
```json
{
  "message": "pageType 为必填字段，必须是 \"home\" 或 \"video\""
}
```

错误响应（503）：
```json
{
  "message": "Redis服务未配置，无法记录点击"
}
```

**说明：**
- 系统会自动获取客户端 IP 进行去重
- 同一 IP 在同一天多次访问同一页面，只计数一次
- 点击量实时更新

---

### 2. 获取页面点击统计

获取指定日期范围内的页面点击统计数据。

**接口地址：** `GET /api/page-clicks/statistics`

**认证要求：** 需要管理员权限（Bearer Token）

**请求头：**
```
Authorization: Bearer {token}
```

**查询参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageType | string | 否 | 页面类型，`"home"` 或 `"video"`，不传则返回所有页面 |
| startDate | string | 否 | 开始日期，格式：`YYYY-MM-DD`，默认：7天前 |
| endDate | string | 否 | 结束日期，格式：`YYYY-MM-DD`，默认：今天 |

**请求示例：**

查询所有页面最近7天的统计：
```bash
curl -X GET "http://your-domain.com/api/page-clicks/statistics" \
  -H "Authorization: Bearer {token}"
```

查询首页指定日期范围：
```bash
curl -X GET "http://your-domain.com/api/page-clicks/statistics?pageType=home&startDate=2024-01-01&endDate=2024-01-07" \
  -H "Authorization: Bearer {token}"
```

**响应示例：**

成功响应（200）：
```json
{
  "success": true,
  "statistics": [
    {
      "pageType": "home",
      "date": "2024-01-15",
      "clickCount": 1234
    },
    {
      "pageType": "home",
      "date": "2024-01-16",
      "clickCount": 1456
    },
    {
      "pageType": "video",
      "date": "2024-01-15",
      "clickCount": 2345
    },
    {
      "pageType": "video",
      "date": "2024-01-16",
      "clickCount": 2678
    }
  ],
  "total": [
    {
      "pageType": "home",
      "totalClicks": 2690
    },
    {
      "pageType": "video",
      "totalClicks": 5023
    }
  ],
  "query": {
    "pageType": "all",
    "startDate": "2024-01-15",
    "endDate": "2024-01-16"
  }
}
```

错误响应（400）：
```json
{
  "message": "pageType 必须是 \"home\" 或 \"video\""
}
```

或

```json
{
  "message": "日期格式错误，请使用 YYYY-MM-DD 格式"
}
```

**说明：**
- 统计数据按日期和页面类型排序
- `statistics` 数组包含每日详细数据
- `total` 数组包含每个页面的总点击量
- 如果查询日期范围内没有数据，返回空数组

---

### 3. 获取今日点击统计汇总

获取所有页面今日的点击统计汇总。

**接口地址：** `GET /api/page-clicks/statistics/today`

**认证要求：** 需要管理员权限（Bearer Token）

**请求头：**
```
Authorization: Bearer {token}
```

**请求示例：**
```bash
curl -X GET "http://your-domain.com/api/page-clicks/statistics/today" \
  -H "Authorization: Bearer {token}"
```

**响应示例：**

成功响应（200）：
```json
{
  "success": true,
  "date": "2024-01-16",
  "summary": [
    {
      "pageType": "video",
      "clickCount": 1234
    },
    {
      "pageType": "home",
      "clickCount": 567
    }
  ]
}
```

**说明：**
- 返回结果按点击量降序排序
- `date` 字段为当前日期
- 即使点击量为 0 的页面也会返回

---

### 4. 获取指定页面的点击量

获取指定页面在指定日期的点击量。

**接口地址：** `GET /api/page-clicks/count`

**认证要求：** 需要管理员权限（Bearer Token）

**请求头：**
```
Authorization: Bearer {token}
```

**查询参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageType | string | 是 | 页面类型，必须是 `"home"` 或 `"video"` |
| date | string | 否 | 日期，格式：`YYYY-MM-DD`，默认：今天 |

**请求示例：**

查询首页今日点击量：
```bash
curl -X GET "http://your-domain.com/api/page-clicks/count?pageType=home" \
  -H "Authorization: Bearer {token}"
```

查询视频页面指定日期点击量：
```bash
curl -X GET "http://your-domain.com/api/page-clicks/count?pageType=video&date=2024-01-15" \
  -H "Authorization: Bearer {token}"
```

**响应示例：**

成功响应（200）：
```json
{
  "success": true,
  "pageType": "home",
  "date": "2024-01-16",
  "clickCount": 1234
}
```

错误响应（400）：
```json
{
  "message": "pageType 为必填字段，必须是 \"home\" 或 \"video\""
}
```

或

```json
{
  "message": "日期格式错误，请使用 YYYY-MM-DD 格式"
}
```

**说明：**
- 如果指定日期没有数据，`clickCount` 返回 `0`
- 只能查询最近 7 天内的数据（超过 7 天的数据已过期）

---

## 错误码说明

| HTTP 状态码 | 说明 | 示例 |
|------------|------|------|
| 200 | 请求成功 | - |
| 400 | 请求参数错误 | 页面类型错误、日期格式错误等 |
| 401 | 未认证 | 缺少或无效的 Token |
| 403 | 权限不足 | 非管理员用户访问管理接口 |
| 500 | 服务器内部错误 | 服务器处理异常 |
| 503 | 服务不可用 | Redis 未配置或连接失败 |

**错误响应格式：**
```json
{
  "message": "错误描述信息"
}
```

---

## 使用示例

### JavaScript/TypeScript 示例

#### 记录首页点击
```javascript
async function recordHomeClick() {
  const response = await fetch('http://your-domain.com/api/page-clicks/click', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      pageType: 'home'
    })
  });
  
  const data = await response.json();
  console.log('点击记录成功，当前点击量：', data.clickCount);
}
```

#### 记录视频页面点击
```javascript
async function recordVideoClick() {
  const response = await fetch('http://your-domain.com/api/page-clicks/click', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      pageType: 'video'
    })
  });
  
  const data = await response.json();
  console.log('点击记录成功，当前点击量：', data.clickCount);
}
```

#### 获取统计数据（需要管理员 Token）
```javascript
async function getStatistics(pageType, startDate, endDate) {
  const token = 'your-admin-token';
  const params = new URLSearchParams();
  
  if (pageType) params.append('pageType', pageType);
  if (startDate) params.append('startDate', startDate);
  if (endDate) params.append('endDate', endDate);
  
  const response = await fetch(
    `http://your-domain.com/api/page-clicks/statistics?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );
  
  const data = await response.json();
  console.log('统计数据：', data);
  return data;
}

// 使用示例
getStatistics('home', '2024-01-01', '2024-01-07');
```

#### 获取今日汇总
```javascript
async function getTodaySummary() {
  const token = 'your-admin-token';
  const response = await fetch(
    'http://your-domain.com/api/page-clicks/statistics/today',
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );
  
  const data = await response.json();
  console.log('今日汇总：', data.summary);
  return data;
}
```

### cURL 示例

#### 记录点击
```bash
# 记录首页点击
curl -X POST http://your-domain.com/api/page-clicks/click \
  -H "Content-Type: application/json" \
  -d '{"pageType": "home"}'

# 记录视频页面点击
curl -X POST http://your-domain.com/api/page-clicks/click \
  -H "Content-Type: application/json" \
  -d '{"pageType": "video"}'
```

#### 查询统计
```bash
# 获取所有页面最近7天统计
curl -X GET "http://your-domain.com/api/page-clicks/statistics" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 获取首页指定日期范围统计
curl -X GET "http://your-domain.com/api/page-clicks/statistics?pageType=home&startDate=2024-01-01&endDate=2024-01-07" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 获取今日汇总
curl -X GET "http://your-domain.com/api/page-clicks/statistics/today" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 获取指定页面指定日期点击量
curl -X GET "http://your-domain.com/api/page-clicks/count?pageType=video&date=2024-01-15" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

## 注意事项

1. **数据保留时间**：所有数据在 Redis 中保存 7 天，超过 7 天的数据会自动过期删除
2. **IP 去重**：同一 IP 在同一天访问同一页面多次，只计数一次
3. **时区**：所有日期使用服务器时区，按天（00:00:00 - 23:59:59）统计
4. **性能**：记录接口无需认证，适合高频调用；查询接口需要管理员权限
5. **Redis 依赖**：功能依赖 Redis，如果 Redis 未配置或连接失败，记录接口会返回 503 错误

---

## 更新日志

- **v1.0.0** (2024-01-16)
  - 初始版本
  - 支持首页和视频页面点击记录
  - 支持 7 天数据保留
  - 支持 IP 去重