rank_backend/docs/API接口文档.md

# 小程序抖音播放量数据API文档

## 概述

抖音短剧播放量数据API，专为小程序优化，支持分页、搜索、增长分析等功能。

**服务地址**: `http://localhost:5001`
**启动命令**: `cd backend && python miniprogram_api_server.py`

## 接口列表

### 1. 健康检查
`GET /api/health`
- 检查服务器和数据库状态

### 2. 视频列表
`GET /api/videos`

**参数**:
- `page`: 页码（默认1）
- `limit`: 每页数量（默认20，最大50）
- `sort`: 排序方式
  - `playcount`: 按总播放量排序
  - `growth`: 按增长排序
  - `time`: 按时间排序
- `start_date`: 开始日期（增长排序用，格式：2025-10-16）
- `end_date`: 结束日期（增长排序用，格式：2025-10-17）

**示例**:
```
# 总播放量排序
/api/videos?page=1&limit=10&sort=playcount

# 增长排序（昨天到今天）
/api/videos?page=1&limit=10&sort=growth

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

### 3. 热门榜单
`GET /api/top`
- `limit`: 返回数量（默认10，最大50）

### 4. 搜索视频
`GET /api/search`
- `q`: 搜索关键词
- `page`: 页码
- `limit`: 每页数量

### 5. 视频详情
`GET /api/detail`
- `id`: 视频ID

## 数据字段说明

### 视频数据字段
- `_id`: 视频唯一ID
- `mix_name`: 短剧名称
- `playcount`: 播放量文本（如"2.1亿"）
- `play_vv`: 播放量数值
- `video_url`: 抖音合集链接
- `rank`: 排名
- `batch_time`: 数据采集时间
- `aweme_ids`: 视频ID数组
- `cover_image_url`: 封面图片
- `cover_backup_urls`: 备用封面图片
- `request_id`: 请求ID

### 增长排序特有字段
- `growth`: 播放量增长值
- `start_date`: 开始日期
- `end_date`: 结束日期

## 响应格式

所有接口返回格式：
```json
{
  "success": true/false,
  "data": [...],
  "message": "错误信息（仅当success为false时）"
}
```

视频列表接口额外包含：
- `pagination`: 分页信息
- `sort_by`: 排序方式
- `date_range`: 日期范围（仅增长排序）
- `update_time`: 更新时间

## 📱 小程序集成示例

### 微信小程序示例

```javascript
// 获取视频列表
wx.request({
  url: 'http://localhost:5001/api/videos',
  data: {
    page: 1,
    limit: 10,
    sort: 'playcount'
  },
  success: function(res) {
    if (res.data.success) {
      const videos = res.data.data;
      videos.forEach(video => {
        console.log(`${video.mix_name}: ${video.playcount}`);
        console.log(`封面: ${video.cover_image_url}`);
        console.log(`链接: ${video.video_url}`);
        console.log(`视频数量: ${video.aweme_ids.length}`);
      });
      console.log('分页信息:', res.data.pagination);
    }
  }
});

// 搜索视频
wx.request({
  url: 'http://localhost:5001/api/search',
  data: {
    q: '奶团',
    page: 1,
    limit: 5
  },
  success: function(res) {
    if (res.data.success) {
      const results = res.data.data;
      results.forEach(video => {
        console.log(`找到: ${video.mix_name}`);
        console.log(`播放量: ${video.playcount}`);
        console.log(`数值播放量: ${video.play_vv}`);
      });
    }
  }
});

// 获取热门榜单
wx.request({
  url: 'http://localhost:5001/api/top',
  data: {
    limit: 10
  },
  success: function(res) {
    if (res.data.success) {
      console.log('热门榜单:', res.data.data);
    }
  }
});
```

### uni-app示例

```javascript
// 封装API请求
const API_BASE = 'http://localhost:5001';

// 获取视频列表
export function getVideoList(page = 1, limit = 20, sort = 'playcount') {
  return uni.request({
    url: `${API_BASE}/api/videos`,
    data: { page, limit, sort }
  });
}

// 搜索视频
export function searchVideos(keyword, page = 1, limit = 10) {
  return uni.request({
    url: `${API_BASE}/api/search`,
    data: { q: keyword, page, limit }
  });
}

// 获取视频详情
export function getVideoDetail(id) {
  return uni.request({
    url: `${API_BASE}/api/detail`,
    data: { id }
  });
}

// 使用示例
getVideoList(1, 10).then(([err, res]) => {
  if (!err && res.data.success) {
    console.log('视频列表:', res.data.data);
  }
});
```

## 🎯 数据字段说明

### 视频合集字段
- `_id`: 合集唯一标识符（MongoDB ObjectId）
- `mix_name`: 合集名称
- `playcount`: 播放量文本（如"2.1亿"）
- `play_vv`: 播放量数值
- `video_url`: 合集链接
- `rank`: 排名
- `batch_time`: 批次时间
- `aweme_ids`: 视频ID数组
- `cover_image_url`: 封面图片URL
- `cover_backup_urls`: 备用封面图片URL数组
- `request_id`: 请求ID

### 分页信息字段
- `page`: 当前页码
- `limit`: 每页数量
- `total`: 总记录数
- `pages`: 总页数
- `has_next`: 是否有下一页
- `has_prev`: 是否有上一页

## 🔧 技术特性

### 1. 小程序优化
- **轻量级响应**: 精简数据结构，减少传输量
- **分页支持**: 避免一次性加载大量数据
- **搜索功能**: 支持关键词模糊搜索
- **错误处理**: 统一的错误响应格式

### 2. 性能优化
- **数据缓存**: MongoDB查询优化
- **分页限制**: 防止过大的数据请求
- **连接池**: 数据库连接复用
- **日志记录**: 完整的请求日志

### 3. 安全特性
- **参数验证**: 输入参数安全检查
- **CORS支持**: 跨域请求支持
- **错误隐藏**: 不暴露内部错误信息

## 📊 测试结果

最新测试结果（100%通过率）：
- ✅ API首页: 正常
- ✅ 健康检查: 数据库连接正常，35条记录
- ✅ 视频列表: 分页功能正常
- ✅ 热门榜单: 排序功能正常
- ✅ 搜索功能: 关键词搜索正常
- ✅ 视频详情: 详情获取正常
- ✅ 统计信息: 数据统计正常

## 🚀 部署建议

### 开发环境
```bash
# 启动API服务器
python scripts/miniprogram_api_server.py

# 运行测试
python scripts/test_miniprogram_api.py
```

### 生产环境
```bash
# 使用Gunicorn部署
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5001 scripts.miniprogram_api_server:app

# 使用Nginx反向代理
# 配置SSL证书支持HTTPS
```

## 📝 更新日志

### v2.0 (2025-10-16)
- 🎉 全新的小程序优化API
- ✨ 添加分页和搜索功能
- 🔧 优化数据结构和响应格式
- 📊 增加统计信息接口
- 🧪 完整的测试覆盖

### 与v1.0的主要区别
- **更好的分页**: 支持灵活的分页参数
- **搜索功能**: 关键词模糊搜索
- **详情接口**: 单独的视频详情查看
- **统计分析**: 数据统计和分类
- **小程序优化**: 专为小程序设计的数据格式

## 🤝 技术支持

如有问题，请检查：
1. MongoDB服务是否正常运行
2. API服务器是否启动成功
3. 网络连接是否正常
4. 参数格式是否正确

测试工具会自动生成详细的测试报告，保存在 `api_test_report.json` 文件中。