236 lines
7.5 KiB
Markdown
236 lines
7.5 KiB
Markdown
# Douyin Targeted Crawling Requirements
|
||
|
||
## Goal
|
||
|
||
在现有“登录浏览器后附着抓取”的基础上，扩展为支持更明确、但尽量少参数的目标选择能力，使系统不仅能抓默认博主主页，还能：
|
||
|
||
- 指定某个博主主页进行抓取
|
||
- 直接抓当前浏览器里正在查看的博主主页
|
||
- 指定某个单独视频进行抓取
|
||
|
||
本需求文档只定义需求、范围、交互、错误处理和 TDD 约束，不直接定义实现细节代码。
|
||
|
||
## Current Behavior
|
||
|
||
当前系统具备以下行为：
|
||
|
||
- 通过 `login_douyin.py` 启动可见 Chrome，并开启调试端口
|
||
- 通过 `Douyin.py` 附着到该浏览器
|
||
- 打开某个博主主页 URL
|
||
- 监听抖音作品列表接口 `web/aweme/post/`
|
||
- 从接口返回的 `aweme_list` 中提取视频地址并下载
|
||
|
||
当前默认目标是一个硬编码博主主页，但也支持在命令行传入另一个博主主页 URL。
|
||
|
||
## Target Modes
|
||
|
||
从实现视角看，新版本仍需同时支持以下三种目标模式；但默认用户交互应尽量自动判断，不要求用户每次显式传模式参数。
|
||
|
||
### 1. `creator-url`
|
||
|
||
用户显式传入某个博主主页 URL，系统以该博主主页为目标进行抓取。
|
||
|
||
### 2. `current-page`
|
||
|
||
系统直接读取当前已附着浏览器当前活动标签页正在查看的页面：
|
||
|
||
- 如果当前页面是博主主页，则以该页面为目标进行抓取
|
||
- 如果当前页面是单视频页，则按单视频方式抓取
|
||
- 如果当前页面不是支持的抖音页面，则提示用户手动传入链接或 `aweme_id`
|
||
|
||
### 3. `single-video`
|
||
|
||
用户传入单个视频链接或 `aweme_id`，系统仅下载这一条视频，不执行博主作品列表抓取。
|
||
|
||
## Scope Rules
|
||
|
||
### Creator Targets
|
||
|
||
当目标是博主时，默认只抓“当前页面中已加载、当前可见范围对应的作品”。
|
||
|
||
这意味着：
|
||
|
||
- 不默认自动抓完整个博主全部作品
|
||
- 不默认自动多页翻完所有历史内容
|
||
- 不自动替用户点击筛选器或改动页面状态
|
||
- 如果用户已经在页面里手动做了筛选、切换或滚动，则抓取结果以当前页面已加载状态为准
|
||
|
||
### Single Video Target
|
||
|
||
当目标是单视频时：
|
||
|
||
- 若输入是视频 URL，系统需要先解析出对应作品标识
|
||
- 若输入是 `aweme_id`，系统直接按单作品逻辑抓取
|
||
- 最终只下载一条视频
|
||
|
||
## Recommended User Experience
|
||
|
||
保留现有两步模式，不改成自动登录的一体化入口：
|
||
|
||
### Step 1
|
||
|
||
先启动登录浏览器：
|
||
|
||
```bash
|
||
./.venv/bin/python login_douyin.py
|
||
```
|
||
|
||
### Step 2
|
||
|
||
登录完成后，再运行抓取命令。
|
||
|
||
默认抓取命令应尽量零参数：
|
||
|
||
```bash
|
||
./.venv/bin/python Douyin.py
|
||
```
|
||
|
||
其推荐行为为：
|
||
|
||
- 默认附着已启动的登录浏览器
|
||
- 默认读取当前活动标签页 URL
|
||
- 自动判断当前页是博主主页还是单视频页
|
||
- 若当前页不是支持页面，则报错并提示用户手动传入链接或 `aweme_id`
|
||
|
||
同时系统必须保留一个简单的手动兜底入口，例如单个位置参数：
|
||
|
||
```bash
|
||
./.venv/bin/python Douyin.py "https://www.douyin.com/user/..."
|
||
./.venv/bin/python Douyin.py "https://www.douyin.com/video/..."
|
||
./.venv/bin/python Douyin.py "7619989983668240802"
|
||
```
|
||
|
||
具体参数名可在实现设计阶段微调，但必须满足以下原则：
|
||
|
||
- 默认路径应尽量不需要复杂参数
|
||
- “当前浏览器页面自动判断”与“手动传入目标”不能混淆
|
||
- 单视频目标与博主目标在内部逻辑上不能混淆
|
||
- 用户一旦需要手动兜底，输入形式应尽量简单
|
||
|
||
## Functional Requirements
|
||
|
||
### Requirement A: Explicit Creator URL Crawling
|
||
|
||
系统必须允许用户通过博主主页 URL 指定抓取目标。
|
||
|
||
完成条件：
|
||
|
||
- 系统接受有效博主主页 URL
|
||
- 浏览器打开或切换到该 URL
|
||
- 系统只抓当前页面已加载的作品
|
||
|
||
### Requirement B: Current Browser Page Auto Detection
|
||
|
||
系统必须允许用户不手输目标 URL，而是直接按当前已附着浏览器的活动标签页进行自动判断。
|
||
|
||
完成条件：
|
||
|
||
- 系统能读取当前浏览器活动标签页 URL
|
||
- 若当前页面是博主主页，则正常抓取
|
||
- 若当前页面是单视频页，则按单视频逻辑抓取
|
||
- 若当前页面不是支持的抖音页面，则明确报错，并提示用户手动传链接或 `aweme_id`
|
||
|
||
### Requirement C: Single Video Download
|
||
|
||
系统必须允许用户通过单个视频链接或 `aweme_id` 只下载一个视频。
|
||
|
||
完成条件：
|
||
|
||
- 支持视频 URL 输入
|
||
- 支持 `aweme_id` 输入
|
||
- 最终只落地一个视频文件
|
||
|
||
### Requirement D: Visible-Only Creator Scope
|
||
|
||
当目标是博主时，系统默认只处理当前页面已经加载出来的作品。
|
||
|
||
完成条件：
|
||
|
||
- 不自动继续滚动抓到所有历史内容
|
||
- 抓取范围受当前页面加载状态约束
|
||
- 用户先手动筛选、滚动、切换后，再执行抓取时，系统按当前页面状态工作
|
||
|
||
## Error Handling Requirements
|
||
|
||
系统必须提供明确错误，不允许模糊失败。
|
||
|
||
### Current Creator Errors
|
||
|
||
- 当前页面不是受支持的抖音博主页或单视频页：报错并提示手动传链接或 `aweme_id`
|
||
- 当前页面虽然像博主页，但未加载出可用作品数据：提示用户先完成页面操作后重试
|
||
|
||
### Single Video Errors
|
||
|
||
- 输入既不是合法视频 URL，也不是合法 `aweme_id`：报错并退出
|
||
- 视频标识无法解析：报错并退出
|
||
|
||
### Browser Attachment Errors
|
||
|
||
- 调试端口不可用：提示先运行登录脚本并确认浏览器仍在运行
|
||
|
||
### Creator URL Errors
|
||
|
||
- 传入 URL 不是受支持的抖音博主主页：报错并退出
|
||
|
||
## Non-Goals
|
||
|
||
本次需求明确不包含以下内容：
|
||
|
||
- 任意网页抓取
|
||
- 非抖音站点抓取
|
||
- 自动替用户点击页面筛选器
|
||
- 自动抓完整个博主全部历史作品
|
||
- 自动搜索博主
|
||
- 自动在抖音站内执行复杂导航流程
|
||
|
||
## Terminology
|
||
|
||
### `aweme`
|
||
|
||
抖音接口中的作品对象，可以理解为一条内容或一个视频作品实体。
|
||
|
||
### `aweme_id`
|
||
|
||
抖音作品的唯一标识。
|
||
|
||
### `current visible videos`
|
||
|
||
指当前页面已经加载出来，并能够通过当前页面对应接口响应获得的作品集合，而不是博主的全量历史作品。
|
||
|
||
## TDD Requirements
|
||
|
||
本需求后续实现必须使用 TDD。
|
||
|
||
### Mandatory Process
|
||
|
||
1. 先写失败测试
|
||
2. 先验证测试是因为功能未实现而失败
|
||
3. 再写最小实现让测试通过
|
||
4. 最后再做必要重构
|
||
|
||
### Required Test Areas
|
||
|
||
至少覆盖以下测试：
|
||
|
||
- `creator-url` 模式下，合法博主主页 URL 能被识别并生成正确抓取目标
|
||
- 默认零参数模式下，当前页面是博主主页时可抓取
|
||
- 默认零参数模式下，当前页面是单视频页时可抓取
|
||
- 默认零参数模式下，当前页面不是支持页面时明确报错并提示手动输入
|
||
- `single-video` 模式支持视频 URL
|
||
- `single-video` 模式支持 `aweme_id`
|
||
- 创作者抓取默认只处理当前已加载内容，不自动继续翻页
|
||
- 手动输入目标无法识别时的报错路径
|
||
- 浏览器端口不可用时的报错路径
|
||
|
||
## Acceptance Criteria
|
||
|
||
需求完成后，应满足以下验收标准：
|
||
|
||
1. 用户在最常见场景下可以直接执行 `./.venv/bin/python Douyin.py`
|
||
2. 系统可以自动识别当前浏览器活动标签页是博主主页还是单视频页
|
||
3. 用户仍可以手动指定博主主页 URL、单视频 URL 或 `aweme_id`
|
||
4. 当目标是博主时，默认只抓当前页面已加载作品
|
||
5. 当前页面不受支持时，系统会明确提示手动传入链接或 `aweme_id`
|
||
6. 关键失败场景都有明确报错
|
||
7. 实现过程遵循 TDD，并有对应自动化测试覆盖
|