rank_backend/docs/API接口文档.md

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

## 🚀 服务器信息

- **服务器地址**: `http://localhost:5000` 或 `http://你的服务器IP:5000`
- **协议**: HTTP
- **数据格式**: JSON
- **编码**: UTF-8
- **跨域支持**: 已配置CORS，支持小程序调用

## 📋 API接口列表

### 1. 获取最新播放量数据

**接口地址**: `GET /api/latest`

**功能说明**: 获取最新一批的抖音剧本播放量数据，按排名排序

**请求参数**:
- `limit` (可选): 返回数据条数，默认50条

**请求示例**:
```
GET /api/latest?limit=10
```

**返回数据格式**:
```json
{
  "success": true,
  "data": [
    {
      "rank": 1,
      "script_name": "九尾狐男妖爱上我更新37集",
      "playcount": "2.1亿",
      "playcount_number": 210000000.0,
      "update_time": "2025-10-15 18:39:29"
    }
  ],
  "total": 35,
  "update_time": "2025-10-15 18:39:29"
}
```

### 2. 搜索剧本

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

**功能说明**: 根据剧本名称进行模糊搜索

**请求参数**:
- `name` (必需): 搜索关键词

**请求示例**:
```
GET /api/search?name=九尾狐
```

**返回数据格式**:
```json
{
  "success": true,
  "data": [
    {
      "rank": 1,
      "script_name": "九尾狐男妖爱上我更新37集",
      "playcount": "2.1亿",
      "playcount_number": 210000000.0,
      "update_time": "2025-10-15 18:39:29"
    }
  ],
  "total": 1,
  "search_keyword": "九尾狐"
}
```

### 3. 获取热门剧本

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

**功能说明**: 获取播放量最高的剧本列表

**请求参数**:
- `limit` (可选): 返回数据条数，默认10条

**请求示例**:
```
GET /api/top?limit=5
```

**返回数据格式**:
```json
{
  "success": true,
  "data": [
    {
      "rank": 1,
      "script_name": "九尾狐男妖爱上我更新37集",
      "playcount": "2.1亿",
      "playcount_number": 210000000.0,
      "update_time": "2025-10-15 18:39:29"
    }
  ],
  "total": 5
}
```

### 4. 服务器状态

**接口地址**: `GET /api/status`

**功能说明**: 获取API服务器和数据库状态

**请求示例**:
```
GET /api/status
```

**返回数据格式**:
```json
{
  "success": true,
  "mongodb_status": "连接正常",
  "total_records": 35,
  "latest_update": "2025-10-15 18:39:29",
  "server_time": "2025-10-15 18:54:45"
}
```

## 📱 小程序调用示例

### 微信小程序示例代码

```javascript
// 获取最新数据
wx.request({
  url: 'http://你的服务器IP:5000/api/latest',
  method: 'GET',
  data: {
    limit: 20
  },
  success: function(res) {
    console.log('获取数据成功:', res.data);
    if (res.data.success) {
      // 处理数据
      const scripts = res.data.data;
      // 更新页面数据
    }
  },
  fail: function(err) {
    console.error('请求失败:', err);
  }
});

// 搜索剧本
wx.request({
  url: 'http://你的服务器IP:5000/api/search',
  method: 'GET',
  data: {
    name: '九尾狐'
  },
  success: function(res) {
    if (res.data.success) {
      const searchResults = res.data.data;
      // 显示搜索结果
    }
  }
});
```

## 🔄 数据更新机制

1. **自动更新**: 每天24:00自动运行抓取脚本
2. **实时同步**: 抓取完成后，API立即返回最新数据
3. **排序规则**: 数据按播放量自动排序，最高播放量排第一

## 📊 数据字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| rank | number | 排名（1为最高） |
| script_name | string | 剧本名称 |
| playcount | string | 播放量文本（如"2.1亿"） |
| playcount_number | number | 播放量数值（用于排序） |
| update_time | string | 更新时间 |

## ⚠️ 注意事项

1. **服务器地址**: 请将`localhost`替换为实际的服务器IP地址
2. **端口配置**: 默认端口5000，可在服务器代码中修改
3. **数据更新**: 数据每天更新一次，建议小程序缓存数据
4. **错误处理**: 请在小程序中添加网络错误处理逻辑

## 🛠️ 启动API服务器

```bash
# 安装依赖
pip install -r requirements.txt

# 启动服务器
python douyin_api_server.py
```

服务器启动后会显示：
```
🚀 启动抖音播放量API服务器...
📡 API地址: http://localhost:5000
```

## 📞 技术支持

如有问题，请检查：
1. MongoDB是否正常运行
2. 服务器端口是否被占用
3. 网络连接是否正常
4. 数据是否已更新