# 排名系统（Rankings）说明大纲

## 1. 项目概览
- 提供抖音收藏合集真实播放量数据采集与API服务
- 抓取脚本写入 MongoDB；API 按播放量与增长榜返回数据

## 2. 目录速览（关键）
- `handlers/Rankings/rank_data_scraper.py` 数据抓取脚本（Selenium+CDP）
- `routers/rank_api_routes.py` 小程序 API 数据访问/逻辑模块（由 `app.py` 调用，不独立运行）
- `app.py` 主服务入口（Flask应用，注册所有 API 路由）
- `Timer_worker.py` 定时任务，每日自动运行抓取

### 项目结构（简版）
```
项目根/
├── app.py                  # 主服务入口（5001）
├── Timer_worker.py         # 定时抓取任务
├── config.py               # 全局配置
├── database.py             # 数据库封装
├── docs/                   # 项目文档
│   ├── README.md           # 项目说明文档
│   ├── API接口文档.md      # API接口说明
│   └── requirements.txt    # 依赖包列表
├── routers/
│   └── rank_api_routes.py  # 小程序API逻辑模块
└── handlers/
    └── Rankings/
        ├── rank_data_scraper.py         # 抓取脚本（Selenium+CDP）
        └── drivers/                     # 浏览器驱动等
            └── chromedriver.exe         # Chrome驱动程序
```
- 核心数据表：`Rankings/Rankings_list`
- 日志示例：`handlers/Rankings/logs/douyin_scraper.log`

## 3. 服务与端口
- 单一服务：`app.py`（默认端口 `5001`，包含小程序 API 路由）

## 4. 一键启动
- 启动主服务：
  ```bash
  python app.py
  ```
- 启动定时任务（每日 9:35 自动抓取）：
  ```bash
  python Timer_worker.py
  ```

## 5. 使用步骤（首次登录与日常）
- 安装依赖：
  ```bash
  pip install -r docs/requirements.txt
  ```
- 第一次使用（登录抖音）：
  - 运行抓取脚本：`python handlers/Rankings/rank_data_scraper.py`
  - 弹出 Chrome 后，完成抖音登录（扫码/账号均可）。
  - 登录完成后，回到终端提示界面按回车继续抓取。
  - 后续运行会复用已登录的浏览器配置，免重复登录。

- 日常流程：
  - 抓取：`python handlers/Rankings/rank_data_scraper.py`
  - 服务：`python app.py`（端口 `5001`）
  - 定时：`python Timer_worker.py`（每日 14:23 自动执行）
  
- 验证数据：
  - MongoDB：数据库 `Rankings`，集合 `Rankings_list`
  - API 检查：
    - `http://localhost:5001/api/rank/health`
    - `http://localhost:5001/api/rank/videos?page=1&limit=20&sort=playcount`
    - 增长榜：`http://localhost:5001/api/rank/videos?sort=growth&page=1&limit=20`

## 6. 数据抓取流程（简版）
- 复用已登录的 Chrome 配置，滚动/刷新触发请求
- 通过 CDP 捕获响应，解析 `play_vv` 与 SSR 数据
- 按合集聚合视频，写入 MongoDB 指定集合

## 7. 数据库与集合
- 数据库：`Rankings`
- 集合：`Rankings_list`
- 连接：`mongodb://localhost:27017/`（可通过环境变量覆盖）

## 8. API 功能摘要
- 视频列表（分页、按播放量/时间排序，仅当日最新数据）
- 增长榜（按指定日期区间对比增长量，分页返回）

## 9. 配置项（环境变量）
- `MONGO_HOST` 默认 `localhost`
- `MONGO_PORT` 默认 `27017`
- `MONGO_DB` 默认 `Rankings`
- `MONGO_COLLECTION` 默认 `Rankings_list`

## 10. 快速排错
- MongoDB 连接失败：抓取脚本将仅保存本地文件日志
- ChromeDriver 配置：`handlers/Rankings/drivers/chromedriver.exe`
- 日志位置：`handlers/Rankings/logs/`（运行时自动创建）

## 11. 你需要知道的
- 当前架构下使用单一服务端口 `5001`；`routers/rank_api_routes.py` 提供逻辑模块，由 `app.py` 注册路由并统一对外服务。
- 抓取脚本与 API 使用同一集合，数据结构一致
- 小程序 API 专注返回易用字段（封面、播放量、时间、链接）
- 可直接在现有数据上新增排序或过滤，保持接口向后兼容
- ChromeDriver 已配置本地版本，避免网络下载问题