排名系统（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                  # 主服务入口（5000）
├── Timer_worker.py         # 定时抓取任务
├── config.py               # 全局配置
├── database.py             # 数据库封装
├── routers/
│   └── rank_api_routes.py  # 小程序API逻辑模块
├── handlers/
│   └── Rankings/
│       ├── rank_data_scraper.py         # 抓取脚本（Selenium+CDP）
│       ├── config/
│       │   └── chrome_profile/
│       │       └── douyin_persistent/   # 持久化Chrome用户目录（登录态）
│       ├── data/                        # 数据导出/缓存（可选）
│       ├── docs/                        # 使用说明与文档
│       ├── drivers/                     # 浏览器驱动等
│       └── logs/                        # 运行日志
└── 项目启动说明.md

• 核心数据表：Rankings/Rankings_list
• 日志示例：handlers/Rankings/logs/douyin_scraper.log

3. 服务与端口

• 单一服务：app.py（默认端口 5000，包含小程序 API 路由）

4. 一键启动

• 启动主服务：

  python app.py
  

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

  python Timer_worker.py
  

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

• 安装依赖：

  pip install -r handlers/Rankings/docs/requirements.txt
  

• 第一次使用（登录抖音）：

  • 运行抓取脚本：python handlers/Rankings/rank_data_scraper.py
  • 弹出 Chrome 后，完成抖音登录（扫码/账号均可）。
  • 登录完成后，回到终端提示界面按回车继续抓取。
  • 后续运行会复用已登录的浏览器配置，免重复登录。

• 日常流程：

  • 抓取：python handlers/Rankings/rank_data_scraper.py
  • 服务：python app.py（端口 5000）
  • 定时：python Timer_worker.py（每日 9:35 自动执行）

• 验证数据：

  • MongoDB：数据库 Rankings，集合 Rankings_list
  • API 检查：
    • http://localhost:5000/api/health
    • http://localhost:5000/api/videos?page=1&limit=20&sort_by=playcount
    • 增长榜：http://localhost:5000/api/videos?sort_by=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 连接失败：抓取脚本将仅保存本地文件日志
• Chrome 配置：handlers/Rankings/config/chrome_profile/
• 日志位置：handlers/Rankings/logs/

11. 你需要知道的

• 当前架构下没有独立的 5001 端口；routers/rank_api_routes.py 提供逻辑模块，由 app.py 注册路由并统一对外服务（5000）。
• 抓取脚本与 API 使用同一集合，数据结构一致
• 小程序 API 专注返回易用字段（封面、播放量、时间、链接）
• 可直接在现有数据上新增排序或过滤，保持接口向后兼容