rank_backend/handlers/Rankings/docs/API接口文档.md

# 抖音播放量数据API接口文档

## 概述

本API服务提供抖音播放量数据的查询、搜索、统计等功能，专为小程序优化设计。

**基础信息**
- 服务地址：`http://localhost:5000`
- 数据源：MongoDB数据库
- 数据更新：每晚24:00自动更新
- 响应格式：JSON

## 通用响应格式

所有API接口都遵循以下响应格式：

```json
{
  "success": true,
  "data": {},
  "message": "操作成功",
  "update_time": "2025-10-17 15:30:00"
}
```

**字段说明**
- `success`: 请求是否成功
- `data`: 返回的数据内容
- `message`: 操作结果描述
- `update_time`: 数据更新时间

## 数据模型

### 合集数据项
```json
{
  "_id": "674f1234567890abcdef",
  "batch_time": "2025-10-17 15:30:00",
  "mix_name": "合集名称",
  "video_url": "https://www.douyin.com/video/xxx",
  "playcount": "1.2亿",
  "play_vv": 120000000,
  "request_id": "request_xxx",
  "rank": 1,
  "cover_image_url": "https://p3.douyinpic.com/xxx",
  "cover_backup_urls": ["url1", "url2"]
}
```

### 分页信息
```json
{
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5,
    "has_next": true,
    "has_prev": false
  }
}
```

## API接口列表

### 1. 首页信息

**接口地址**
```
GET /
```

**功能描述**
获取API服务的基本信息和所有可用接口列表

**请求参数**
无

**响应示例**
```json
{
  "success": true,
  "data": {
    "name": "抖音播放量数据API服务",
    "version": "2.0",
    "description": "主程序服务 - 整合小程序API功能",
    "endpoints": {
      "/api/videos": "获取视频列表 (支持分页和排序)",
      "/api/top": "获取热门视频榜单",
      "/api/search": "搜索视频",
      "/api/detail": "获取视频详情",
      "/api/stats": "获取统计信息",
      "/api/health": "健康检查"
    },
    "features": [
      "分页支持",
      "多种排序方式",
      "搜索功能",
      "详情查看",
      "统计分析",
      "小程序优化"
    ]
  }
}
```

### 2. 获取视频列表

**接口地址**
```
GET /api/videos
```

**功能描述**
获取分页的视频合集列表，支持多种排序方式

**请求参数**
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| page | int | 否 | 1 | 页码 |
| limit | int | 否 | 20 | 每页数量 |
| sort | string | 否 | playcount | 排序方式：playcount(播放量) / growth(增长量) |
| start_date | string | 否 | 昨天 | 增长计算开始日期(格式: YYYY-MM-DD) |
| end_date | string | 否 | 今天 | 增长计算结束日期(格式: YYYY-MM-DD) |

**使用示例**
```
# 按播放量排序
GET /api/videos?page=1&limit=20&sort=playcount

# 按增长量排序（默认昨天到今天的增长）
GET /api/videos?page=1&limit=20&sort=growth

# 按自定义日期范围的增长排序
GET /api/videos?page=1&limit=20&sort=growth&start_date=2025-10-16&end_date=2025-10-17
```

**响应示例**
```json
{
  "success": true,
  "data": [
    {
      "_id": "674f1234567890abcdef",
      "batch_time": "2025-10-17 15:30:00",
      "mix_name": "热门合集1",
      "video_url": "https://www.douyin.com/video/xxx",
      "playcount": "1.2亿",
      "play_vv": 120000000,
      "request_id": "request_xxx",
      "rank": 1,
      "cover_image_url": "https://p3.douyinpic.com/xxx",
      "cover_backup_urls": ["url1", "url2"]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5,
    "has_next": true,
    "has_prev": false
  },
  "sort_by": "playcount",
  "update_time": "2025-10-17 15:30:00"
}
```

### 3. 获取热门榜单

**接口地址**
```
GET /api/top
```

**功能描述**
获取热门视频榜单（按播放量排序）

**请求参数**
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| limit | int | 否 | 10 | 返回数量 |

**使用示例**
```
GET /api/top?limit=10
```

**响应示例**
```json
{
  "success": true,
  "data": [
    {
      "_id": "674f1234567890abcdef",
      "batch_time": "2025-10-17 15:30:00",
      "mix_name": "热门合集1",
      "video_url": "https://www.douyin.com/video/xxx",
      "playcount": "1.2亿",
      "play_vv": 120000000,
      "request_id": "request_xxx",
      "rank": 1,
      "cover_image_url": "https://p3.douyinpic.com/xxx",
      "cover_backup_urls": ["url1", "url2"]
    }
  ],
  "total": 10,
  "update_time": "2025-10-17 15:30:00"
}
```

### 4. 搜索视频

**接口地址**
```
GET /api/search
```

**功能描述**
根据关键词搜索视频合集

**请求参数**
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| q | string | 是 | - | 搜索关键词 |
| page | int | 否 | 1 | 页码 |
| limit | int | 否 | 10 | 每页数量 |

**使用示例**
```
GET /api/search?q=关键词&page=1&limit=10
```

**响应示例**
```json
{
  "success": true,
  "data": [
    {
      "_id": "674f1234567890abcdef",
      "batch_time": "2025-10-17 15:30:00",
      "mix_name": "包含关键词的合集",
      "video_url": "https://www.douyin.com/video/xxx",
      "playcount": "1.2亿",
      "play_vv": 120000000,
      "request_id": "request_xxx",
      "rank": 1,
      "cover_image_url": "https://p3.douyinpic.com/xxx",
      "cover_backup_urls": ["url1", "url2"]
    }
  ],
  "keyword": "关键词",
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 15,
    "pages": 2,
    "has_next": true,
    "has_prev": false
  },
  "update_time": "2025-10-17 15:30:00"
}
```

### 5. 获取视频详情

**接口地址**
```
GET /api/detail
```

**功能描述**
获取指定合集的详细信息

**请求参数**
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| id | string | 是 | - | 合集ID（支持ObjectId、合集名称、request_id） |

**使用示例**
```
GET /api/detail?id=674f1234567890abcdef
```

**响应示例**
```json
{
  "success": true,
  "data": {
    "_id": "674f1234567890abcdef",
    "batch_time": "2025-10-17 15:30:00",
    "mix_name": "合集名称",
    "video_url": "https://www.douyin.com/video/xxx",
    "playcount": "1.2亿",
    "play_vv": 120000000,
    "request_id": "request_xxx",
    "rank": 1,
    "cover_image_url": "https://p3.douyinpic.com/xxx",
    "cover_backup_urls": ["url1", "url2"]
  },
  "update_time": "2025-10-17 15:30:00"
}
```

### 6. 获取统计信息

**接口地址**
```
GET /api/stats
```

**功能描述**
获取系统统计信息

**请求参数**
无

**响应示例**
```json
{
  "success": true,
  "data": {
    "total_mixes": 1000,
    "total_playcount": 5000000000,
    "avg_playcount": 5000000,
    "max_playcount": 200000000,
    "min_playcount": 1000,
    "categories": [
      {
        "name": "超热门",
        "min": 100000000,
        "count": 5
      },
      {
        "name": "热门",
        "min": 50000000,
        "max": 99999999,
        "count": 20
      },
      {
        "name": "中等",
        "min": 10000000,
        "max": 49999999,
        "count": 150
      },
      {
        "name": "一般",
        "min": 0,
        "max": 9999999,
        "count": 825
      }
    ],
    "latest_update": "2025-10-17 15:30:00"
  },
  "update_time": "2025-10-17 15:30:00"
}
```

### 7. 健康检查

**接口地址**
```
GET /api/health
```

**功能描述**
检查服务状态和数据库连接

**请求参数**
无

**响应示例**
```json
{
  "success": true,
  "message": "服务正常",
  "data": {
    "database": "连接正常",
    "total_records": 1000,
    "timestamp": "2025-10-17 15:30:00"
  }
}
```

## 错误处理

### 通用错误格式
```json
{
  "success": false,
  "message": "错误描述",
  "update_time": "2025-10-17 15:30:00"
}
```

### 常见错误
- `数据库连接失败`：MongoDB连接异常
- `未找到合集信息`：查询的合集不存在
- `请提供搜索关键词`：搜索接口缺少关键词参数
- `获取数据失败`：数据查询异常

## 小程序使用建议

### 1. 分页加载
推荐使用分页加载，避免一次性加载过多数据：
```javascript
// 小程序端示例
wx.request({
  url: 'http://localhost:5000/api/videos',
  data: {
    page: 1,
    limit: 20,
    sort: 'playcount'
  },
  success: (res) => {
    if (res.data.success) {
      this.setData({
        videos: res.data.data,
        hasNext: res.data.pagination.has_next
      })
    }
  }
})
```

### 2. 搜索优化
- 使用防抖处理搜索请求
- 显示搜索进度和结果数量
- 提供搜索建议

### 3. 图片加载
- 优先使用 `cover_image_url`
- 备用 `cover_backup_urls` 作为备选
- 添加图片加载失败处理

### 4. 数据更新
- 注意 `update_time` 字段，判断数据新鲜度
- 合理使用缓存策略
- 定期检查服务健康状态

## 部署说明

### 启动服务
```bash
cd C:\Users\EDY\Desktop\rank_backend
python app.py
```

### 服务信息
- 端口：5000
- 数据库：MongoDB (localhost:27017)
- 数据更新：每晚24:00自动执行

### 注意事项
- 确保MongoDB服务已启动
- 确保网络连接正常
- 小程序端需要配置合法域名（生产环境）

---

**文档版本**：v2.0
**最后更新**：2025-10-17**维护者**：系统自动生成