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

## 概述

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

**基础信息**
- 服务地址：`http://localhost:5001`
- 数据源：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
{
  "_id": "68f3ad112ba085e5d676537e",
  "title": "文章标题",
  "author_id": "test_user_1",
  "cover_image": "封面图片URL",
  "status": "draft",
  "summary": "文章摘要",
  "created_at": "2025-10-18 15:06:57",
  "likes": [],
  "likes_count": 0
}
```

### 文章详情数据项
```json
{
  "_id": "68f3ad112ba085e5d676537e",
  "title": "文章标题",
  "content": "文章完整内容",
  "author_id": "test_user_1",
  "cover_image": "封面图片URL",
  "status": "draft",
  "summary": "文章摘要",
  "created_at": "2025-10-18 15:06:57",
  "likes": [],
  "likes_count": 0
}
```

### 分页信息
```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/rank/videos": "获取视频列表 (支持分页和排序)",
      "/api/rank/top": "获取热门视频榜单",
      "/api/rank/search": "搜索视频",
      "/api/rank/detail": "获取视频详情",
      "/api/rank/stats": "获取统计信息",
      "/api/rank/health": "健康检查",
      "/api/rank/rankings": "获取榜单列表",
      "/api/rank/rankings/dates": "获取可用榜单日期",
      "/api/rank/rankings/types": "获取榜单类型",
      "/api/rank/rankings/latest": "获取最新榜单",
      "/api/rank/rankings/stats": "获取榜单统计",
      "/api/article/list": "获取文章列表 (支持分页和排序)",
      "/api/article/search": "搜索文章",
      "/api/article/detail": "获取文章详情",
      "/api/article/stats": "获取文章统计信息",
      "/api/article/health": "文章服务健康检查"
    },
    "features": [
      "分页支持",
      "多种排序方式",
      "搜索功能",
      "详情查看",
      "统计分析",
      "榜单查询",
      "动态排序",
      "小程序优化",
      "文章管理",
      "内容搜索"
    ]
  }
}
```

### 2. 获取视频列表

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

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

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

**数据源说明**
- `sort=playcount`：从Rankings_list集合动态查询当日播放量数据
- `sort=growth`：从Ranking_storage集合读取预计算的增长排名数据（由定时任务生成）

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

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

# 按自定义日期范围的增长排序
GET /api/rank/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"],
      "growth": 5000000,
      "growth_rate": 4.35
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5,
    "has_next": true,
    "has_prev": false
  },
  "sort_by": "growth",
  "data_source": "ranking_storage",
  "update_time": "2025-10-17 15:30:00"
}
```

### 3. 获取热门榜单

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

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

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

**使用示例**
```
GET /api/rank/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/rank/search
```

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

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

**使用示例**
```
GET /api/rank/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/rank/detail
```

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

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

**使用示例**
```
GET /api/rank/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/rank/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/rank/health
```

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

**请求参数**
无

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

### 8. 获取榜单列表

**接口地址**
```
GET /api/rank/rankings
```

**功能描述**
获取榜单列表，支持按日期和类型查询，支持动态排序

**请求参数**
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| date | string | 否 | 最新日期 | 日期，格式：YYYY-MM-DD |
| type | string | 否 | - | 榜单类型：playcount(播放量榜) / growth(增长榜) / newcomer(新晋榜) |
| sort_by | string | 否 | default | 排序方式：default / play_vv_change / play_vv_change_rate / play_vv |
| sort_order | string | 否 | desc | 排序顺序：asc / desc |
| page | int | 否 | 1 | 页码 |
| limit | int | 否 | 50 | 每页数量 |

**使用示例**
```
# 获取最新日期的所有榜单
GET /api/rank/rankings

# 获取指定日期的播放量榜
GET /api/rank/rankings?date=2025-01-17&type=playcount

# 按播放量变化排序
GET /api/rank/rankings?sort_by=play_vv_change&sort_order=desc

# 分页获取增长榜
GET /api/rank/rankings?type=growth&page=1&limit=20
```

**响应示例**
```json
{
  "success": true,
  "message": "获取榜单成功",
  "data": {
    "rankings": [
      {
        "date": "2025-01-17",
        "ranking_type": "playcount",
        "ranking_name": "播放量榜",
        "description": "按播放量排序的榜单",
        "data": [
          {
            "_id": "674f1234567890abcdef",
            "mix_name": "热门合集1",
            "play_vv": 120000000,
            "rank": 1,
            "timeline_data": {
              "play_vv_change": 5000000,
              "play_vv_change_rate": 4.35
            }
          }
        ],
        "total_count": 100,
        "current_page_count": 20,
        "generated_at": "2025-01-17 15:30:00",
        "version": "1.0",
        "sort_info": {
          "sort_by": "default",
          "sort_order": "desc"
        }
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50,
    "sort_by": "default",
    "sort_order": "desc"
  }
}
```

### 9. 获取可用榜单日期

**接口地址**
```
GET /api/rank/rankings/dates
```

**功能描述**
获取所有可用的榜单日期列表

**请求参数**
无

**响应示例**
```json
{
  "success": true,
  "message": "获取日期列表成功",
  "data": {
    "dates": [
      "2025-01-17",
      "2025-01-16",
      "2025-01-15"
    ],
    "total": 3
  }
}
```

### 10. 获取榜单类型

**接口地址**
```
GET /api/rank/rankings/types
```

**功能描述**
获取支持的榜单类型及其说明

**请求参数**
无

**响应示例**
```json
{
  "success": true,
  "message": "获取榜单类型成功",
  "data": {
    "types": [
      {
        "type": "playcount",
        "description": "播放量榜 - 按播放量排序"
      },
      {
        "type": "growth",
        "description": "增长榜 - 播放量增长最快"
      },
      {
        "type": "newcomer",
        "description": "新晋榜 - 新上榜内容"
      }
    ],
    "total": 3
  }
}
```

### 11. 获取最新榜单

**接口地址**
```
GET /api/rank/rankings/latest
```

**功能描述**
获取最新日期的所有类型榜单（每个榜单只返回前20条数据）

**请求参数**
无

**响应示例**
```json
{
  "success": true,
  "message": "获取最新榜单成功",
  "data": {
    "date": "2025-01-17",
    "rankings": [
      {
        "ranking_type": "playcount",
        "ranking_name": "播放量榜",
        "description": "按播放量排序的榜单",
        "data": [
          {
            "_id": "674f1234567890abcdef",
            "mix_name": "热门合集1",
            "play_vv": 120000000,
            "rank": 1
          }
        ],
        "total_count": 100,
        "preview_count": 20
      }
    ],
    "total_types": 3
  }
}
```

### 12. 获取榜单统计

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

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

**请求参数**
无

**响应示例**
```json
{
  "success": true,
  "message": "获取榜单统计成功",
  "data": {
    "total_rankings": 150,
    "total_dates": 30,
    "total_types": 3,
    "latest_date": "2025-01-17",
    "earliest_date": "2024-12-18",
    "date_range": "2024-12-18 至 2025-01-17"
  }
}
```

## 错误处理

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

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

## 文章管理接口

### 1. 获取文章列表

**接口地址**
```
GET /api/article/list
```

**功能描述**
获取文章列表，支持分页和排序

**请求参数**
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| page | int | 否 | 1 | 页码 |
| limit | int | 否 | 10 | 每页数量 |
| sort | string | 否 | created_at | 排序字段 |
| order | string | 否 | desc | 排序方向 (asc/desc) |

**响应示例**
```json
{
  "success": true,
  "data": [
    {
      "_id": "68f3ad112ba085e5d676537e",
      "title": "对于ai影视化的思考",
      "author_id": "test_user_1",
      "cover_image": "",
      "status": "draft",
      "summary": "AI影视化的发展趋势和思考",
      "created_at": "2025-10-18 15:06:57",
      "likes": [],
      "likes_count": 0
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_items": 1,
    "has_next": false,
    "has_prev": false
  },
  "message": "获取文章列表成功",
  "update_time": "2025-10-18 15:06:57"
}
```

### 2. 搜索文章

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

**功能描述**
根据关键词搜索文章

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

**响应示例**
```json
{
  "success": true,
  "data": [
    {
      "_id": "68f3ad112ba085e5d676537e",
      "title": "对于ai影视化的思考",
      "author_id": "test_user_1",
      "cover_image": "",
      "status": "draft",
      "summary": "AI影视化的发展趋势和思考",
      "created_at": "2025-10-18 15:06:57",
      "likes": [],
      "likes_count": 0
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_items": 1,
    "has_next": false,
    "has_prev": false
  },
  "message": "搜索文章成功",
  "update_time": "2025-10-18 15:06:57"
}
```

### 3. 获取文章详情

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

**功能描述**
根据文章ID获取文章详细信息

**请求参数**
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| id | string | 是 | - | 文章ID |

**响应示例**
```json
{
  "success": true,
  "data": {
    "_id": "68f3ad112ba085e5d676537e",
    "title": "对于ai影视化的思考",
    "content": "# AI影视化的思考\n\n在2025年，AI技术在影视行业的应用...",
    "author_id": "test_user_1",
    "cover_image": "",
    "status": "draft",
    "summary": "AI影视化的发展趋势和思考",
    "created_at": "2025-10-18 15:06:57",
    "likes": [],
    "likes_count": 0
  },
  "message": "获取文章详情成功",
  "update_time": "2025-10-18 15:06:57"
}
```

### 4. 获取文章统计信息

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

**功能描述**
获取文章相关的统计信息

**请求参数**
无

**响应示例**
```json
{
  "success": true,
  "data": {
    "total_articles": 1,
    "latest_update": "2025-10-18 15:06:57",
    "status_count": {
      "draft": 1,
      "published": 0,
      "archived": 0
    }
  },
  "message": "获取文章统计成功",
  "update_time": "2025-10-18 15:06:57"
}
```

### 5. 文章服务健康检查

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

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

**请求参数**
无

**响应示例**
```json
{
  "success": true,
  "data": {
    "status": "服务正常",
    "database": "连接正常",
    "article_count": 1
  },
  "message": "文章服务健康检查通过",
  "update_time": "2025-10-18 15:06:57"
}
```

## 小程序使用建议

### 1. 分页加载
推荐使用分页加载，避免一次性加载过多数据：
```javascript
// 小程序端示例
wx.request({
  url: 'http://localhost:5000/api/rank/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` 字段，判断数据新鲜度
- 合理使用缓存策略
- 定期检查服务健康状态

### 5. 文章管理
推荐的文章列表加载方式：
```javascript
// 小程序端示例 - 文章列表
wx.request({
  url: 'http://localhost:5001/api/article/list',
  data: {
    page: 1,
    limit: 10,
    sort: 'created_at',
    order: 'desc'
  },
  success: (res) => {
    if (res.data.success) {
      this.setData({
        articles: res.data.data,
        hasNext: res.data.pagination.has_next
      })
    }
  }
})
```

文章搜索示例：
```javascript
// 小程序端示例 - 文章搜索
wx.request({
  url: 'http://localhost:5001/api/article/search',
  data: {
    q: 'AI',
    page: 1,
    limit: 5
  },
  success: (res) => {
    if (res.data.success) {
      this.setData({
        searchResults: res.data.data
      })
    }
  }
})
```

## 部署说明

### 启动服务
```bash
cd /Users/binghuixiong/剧变AI/rank_backend
python3 app.py
```

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

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

---

**文档版本**：v4.1  
**最后更新**：2025-01-18  
**维护者**：系统自动生成  
**更新内容**：优化增长排名接口数据源策略，现在专门使用Ranking_storage预计算数据，提升查询性能和数据一致性