101 lines
4.0 KiB
Markdown
101 lines
4.0 KiB
Markdown
# 排名系统（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 已配置本地版本，避免网络下载问题 |