# README And Beginner Guide Requirements

## Goal

为当前抖音视频爬取项目补齐两层面向用户的文档，使一个不懂代码的 Mac 用户也能按照步骤执行，并最终成功下载出抖音视频。

本次文档需求包含两部分：

- 仓库根目录的 `README.md`
- `externaldocs/` 下的详细图文操作手册

本需求文档只定义文档目标、范围、结构、截图策略和约束，不直接修改实现代码。

## Target Audience

目标读者是：

- 使用 macOS 的用户
- 不懂代码
- 不熟悉 Python
- 不熟悉虚拟环境
- 但已经把项目放到了本地机器上

本次文档不负责指导用户如何 `git clone` 或下载项目源码到本地。

## Documentation Strategy

采用双层文档结构：

### 1. Root `README.md`

`README.md` 作为导航版首页，职责是：

- 简要说明项目是什么
- 说明项目能做什么
- 说明项目不能做什么
- 告诉用户从哪里开始
- 引导用户查看详细图文手册

`README.md` 不承担完整教学职责，不写成超长操作文档。

### 2. Detailed Guide In `externaldocs/`

详细图文手册作为主操作文档，职责是：

- 面向完全不会代码的用户
- 从环境准备开始写
- 一步一步带到成功下载出视频
- 给出执行命令、预期结果和失败时的处理方式

## Scope

### Included

详细图文手册必须覆盖以下内容：

1. 项目简介
2. 使用前准备
3. 如何确认本机已安装 Python
4. 如何打开终端
5. 如何进入项目目录
6. 如何创建或使用虚拟环境
7. 如何安装依赖
8. 如何启动登录浏览器
9. 如何在浏览器中完成抖音登录和验证码
10. 如何运行抓取命令
11. 如何确认抓取成功
12. 下载结果保存在哪里
13. 常见错误及处理办法

### Excluded

本次文档明确不包含以下内容：

- 如何从远端拉取项目代码到本地
- Git 基础教学
- 任意网页抓取教学
- 非 Mac 平台的安装说明
- 抖音接口原理深度分析

## README Requirements

`README.md` 必须满足以下要求：

1. 用非技术语言介绍项目用途
2. 明确说明这是一个“登录浏览器后附着抓取”的工具
3. 简短说明当前项目的主要能力
4. 简短说明当前项目的限制
5. 提供“最快开始”入口
6. 链接到 `externaldocs/` 下的详细图文手册

### Recommended README Sections

- 项目简介
- 适用人群
- 当前支持的能力
- 快速开始
- 详细使用说明
- 常见注意事项

## Detailed Guide Requirements

详细图文手册必须写成严格的步骤式说明，适合完全不会代码的读者照做。

### Writing Style

- 不使用不必要术语
- 每一步只做一件事
- 每一步都给出要执行的命令
- 每一步都给出“执行后应该看到什么”
- 若这一步常见失败，则紧跟“如果失败怎么办”

### Required Workflow Coverage

详细手册必须按以下顺序组织主流程：

1. 确认 Python 是否已安装
2. 打开终端
3. 进入项目目录
4. 创建或启用虚拟环境
5. 安装依赖
6. 启动登录浏览器
7. 在浏览器中完成抖音登录
8. 运行抓取命令
9. 查看终端成功提示
10. 在本地查看下载出来的 mp4 文件

## Screenshot Strategy

本次截图必须重新拍摄，不直接复用旧图。

### Principles

- 只截关键步骤
- 每张图只服务一个步骤
- 截图内容要与最终文档步骤严格一致
- 优先保证“能照着做”，而不是“图多”

### Required Screenshot Topics

至少应考虑覆盖以下截图：

1. 项目目录结构
2. 打开终端并进入项目目录
3. 安装依赖命令
4. 运行 `login_douyin.py`
5. 浏览器登录后的状态
6. 运行抓取命令
7. 成功下载后的 `video/` 目录

### Screenshot Placement

- `README.md` 只放少量必要截图或不放截图
- 主要截图集中放在详细图文手册中

## Success Signals In The Guide

文档里必须明确告诉用户如何判断是否成功，至少包括：

- 终端中会出现哪些关键信息
- 抓取完成后会看到哪些成功提示
- 本地哪个目录里能看到下载结果
- 下载出的文件是什么格式

## Common Error Handling

详细图文手册必须包含至少以下常见错误的处理建议：

1. 系统找不到 `python` 或 `.venv`
2. 依赖安装失败
3. Chrome 调试端口未就绪
4. 抖音登录未完成或验证码未通过
5. 运行抓取后没有下载出视频
6. 看不到 `video/` 目录或目录为空

## TDD Constraint

本次文档需求本身不要求用 TDD 编写文档。

但如果为了让文档步骤成立而需要修改代码，则后续代码改动必须遵循 TDD：

1. 先写失败测试
2. 确认测试因功能未实现而失败
3. 再写最小实现让测试通过
4. 最后再重构

## Acceptance Criteria

该需求完成后，应满足以下标准：

1. 仓库首页有清晰的 `README.md`
2. `README.md` 能让用户快速理解项目并找到详细手册
3. `externaldocs/` 下存在一份完整的面向小白的图文操作手册
4. 一个不会代码的 Mac 用户可以按手册独立完成操作
5. 手册能从环境准备一路带到视频下载成功
6. 手册包含关键截图、预期结果和常见错误处理