页面点击记录 API 接口文档

概述

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

支持的页面类型：

home - 首页
video - 视频页面

基础信息

Base URL: /api/page-clicks

认证方式：

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

数据存储：

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

数据模型

PageType（页面类型枚举）

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

请求/响应数据结构

记录点击请求

{
  "pageType": "home"  // 或 "video"
}

统计响应

{
  "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"`

请求示例：

curl -X POST http://your-domain.com/api/page-clicks/click \
  -H "Content-Type: application/json" \
  -d '{
    "pageType": "home"
  }'

响应示例：

成功响应（200）：

{
  "success": true,
  "pageType": "home",
  "clickCount": 1234,
  "message": "点击记录成功"
}

错误响应（400）：

{
  "message": "pageType 为必填字段，必须是 \"home\" 或 \"video\""
}

错误响应（503）：

{
  "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天的统计：

curl -X GET "http://your-domain.com/api/page-clicks/statistics" \
  -H "Authorization: Bearer {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 {token}"

响应示例：

成功响应（200）：

{
  "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）：

{
  "message": "pageType 必须是 \"home\" 或 \"video\""
}

或

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

说明：

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

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

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

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

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

请求头：

Authorization: Bearer {token}

请求示例：

curl -X GET "http://your-domain.com/api/page-clicks/statistics/today" \
  -H "Authorization: Bearer {token}"

响应示例：

成功响应（200）：

{
  "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`，默认：今天

请求示例：

查询首页今日点击量：

curl -X GET "http://your-domain.com/api/page-clicks/count?pageType=home" \
  -H "Authorization: Bearer {token}"

查询视频页面指定日期点击量：

curl -X GET "http://your-domain.com/api/page-clicks/count?pageType=video&date=2024-01-15" \
  -H "Authorization: Bearer {token}"

响应示例：

成功响应（200）：

{
  "success": true,
  "pageType": "home",
  "date": "2024-01-16",
  "clickCount": 1234
}

错误响应（400）：

{
  "message": "pageType 为必填字段，必须是 \"home\" 或 \"video\""
}

或

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

说明：

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

错误码说明

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

错误响应格式：

{
  "message": "错误描述信息"
}

使用示例

JavaScript/TypeScript 示例

记录首页点击

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

记录视频页面点击

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）

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');

获取今日汇总

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

记录点击

# 记录首页点击
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"}'

查询统计

# 获取所有页面最近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"

注意事项

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

更新日志

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

page-click-record-api.md 11 KB

Permalink History Raw

页面点击记录 API 接口文档

目录

概述

基础信息

数据模型

PageType（页面类型枚举）

请求/响应数据结构

记录点击请求

统计响应

接口列表

1. 记录页面点击

2. 获取页面点击统计

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

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

错误码说明

使用示例

JavaScript/TypeScript 示例

记录首页点击

记录视频页面点击

获取统计数据（需要管理员 Token）

获取今日汇总

cURL 示例

记录点击

查询统计

注意事项

更新日志

page-click-record-api.md 11 KB Permalink History Raw

页面点击记录 API 接口文档

目录

概述

基础信息

数据模型

PageType（页面类型枚举）

请求/响应数据结构

记录点击请求

统计响应

接口列表

1. 记录页面点击

2. 获取页面点击统计

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

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

错误码说明

使用示例

JavaScript/TypeScript 示例

记录首页点击

记录视频页面点击

获取统计数据（需要管理员 Token）

获取今日汇总

cURL 示例

记录点击

查询统计

注意事项

更新日志

page-click-record-api.md 11 KB

Permalink History Raw