197 lines
5.1 KiB
Markdown
197 lines
5.1 KiB
Markdown
# 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. 手册包含关键截图、预期结果和常见错误处理
|