# 抖音推荐流视频抓取设计文档

## 背景

当前系统支持抓取指定博主主页或单视频。现需扩展支持抓取抖音推荐流（For You页面）当前可见的视频。

## 目标

- 支持抓取抖音推荐流（`https://www.douyin.com/`）的视频
- 记录每个视频对应的博主信息
- 支持滚动加载，最多抓取50条
- 视频统一保存到 `video/` 目录
- 保持现有两步式工作流不变

## 方案选择

采用**方案B：新建推荐流专用抓取函数**

理由：
- 逻辑清晰，推荐流和博主页完全解耦
- 便于后续分别维护
- 工作量适中，可快速实现验证

## 详细设计

### 1. 目标识别扩展

新增推荐流URL识别模式：

```python
RECOMMENDATION_URL_PATTERN = re.compile(
    r"^https?://www\.douyin\.com/?(?:\?.*)?$"
)
```

目标类型扩展为三种：
- `creator` - 博主主页（现有）
- `single-video` - 单视频（现有）
- `recommendation` - 推荐流（新增）

### 2. 核心流程

```
用户执行 ./.venv/bin/python Douyin.py
    ↓
读取当前浏览器页面URL
    ↓
判断页面类型：
    - 推荐流 → 执行 collect_recommendations()
    - 博主页 → 执行 collect_videos()（现有）
    - 单视频 → 执行 collect_single_video()（现有）
    - 其他 → 报错提示
```

### 3. collect_recommendations() 函数

**参数：**
- `max_videos`: 最大抓取数量（默认50）
- `timeout`: 单次等待接口响应秒数（默认10）
- `output_dir`: 输出目录（默认 `video/`）
- `browser_port`: 浏览器调试端口（默认9223）

**行为：**
1. 打开或切换到推荐流页面
2. 启动监听，目标接口：`web/aweme/post/` 或推荐流专用接口
3. 循环直到收集够 `max_videos` 条或无法继续加载：
   - 等待接口响应
   - 解析视频列表，提取：标题、视频ID、视频URL、博主信息
   - 过滤已下载（去重）
   - 下载视频
   - 向下滚动加载更多
4. 返回实际下载数量

### 4. 数据解析增强

新增博主信息提取字段：

```python
{
    "title": "视频标题",
    "video_id": "aweme_id",
    "video_url": "下载链接",
    "author_name": "博主昵称",
    "author_id": "博主ID",
}
```

### 5. 文件名格式

**推荐流视频：**
```
[博主昵称]视频标题-aweme_id.mp4
```
示例：`[张三]搞笑视频-7619989983668240802.mp4`

**博主页视频（保持现有）：**
```
视频标题-aweme_id.mp4
```

### 6. 命令行参数

**新增参数：**
```bash
--max-videos 50    # 推荐流最大抓取数量（默认50）
```

**使用示例：**
```bash
# 零参数，自动识别当前页面
./.venv/bin/python Douyin.py

# 显式指定推荐流（可选）
./.venv/bin/python Douyin.py "https://www.douyin.com/"

# 自定义抓取数量
./.venv/bin/python Douyin.py --max-videos 30
```

### 7. 错误处理

- **推荐流页面未加载数据**：提示用户先滚动加载内容
- **滚动后无新数据**：正常结束，返回已下载数量
- **达到最大数量**：正常结束
- **其他错误**：复用现有错误处理机制

### 8. 测试覆盖（TDD）

必须覆盖以下测试场景：

- [ ] 推荐流URL识别测试
- [ ] 推荐流页面解析测试（模拟API响应含博主信息）
- [ ] 滚动加载逻辑测试
- [ ] 最大数量限制测试
- [ ] 文件名构建测试（含博主名）
- [ ] 博主信息提取测试
- [ ] 去重逻辑测试

## 非目标

- 自动登录抖音
- 自动过验证码
- 抓取非推荐流页面（如话题页、搜索页）
- 自动筛选视频内容
- 抓取超过50条视频（如需更多，需用户手动调整参数）

## 验收标准

1. 用户可以在推荐流页面执行 `./.venv/bin/python Douyin.py` 抓取视频
2. 系统能自动识别当前页面是推荐流
3. 支持滚动加载，最多抓取50条
4. 文件名包含博主昵称
5. 所有测试通过
6. 关键失败场景有明确报错

## 实现步骤

1. 编写测试（TDD）
2. 实现推荐流URL识别
3. 实现 `collect_recommendations()` 函数
4. 增强数据解析（提取博主信息）
5. 修改文件名构建逻辑
6. 更新命令行参数
7. 运行全部测试
8. 提交代码