排名系统（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. 一键启动

• 启动主服务：

  python app.py
  

• 启动定时任务（每日 9:35 自动抓取）：

  python Timer_worker.py
  

5. 使用步骤（首次登录与日常）

• 安装依赖：

  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 已配置本地版本，避免网络下载问题