494 lines
17 KiB
Markdown
494 lines
17 KiB
Markdown
# RequirementsDoc.md：小红书 / 抖音热榜评论抓取 + AI 分析报告工具
|
||
|
||
## 1. 文档信息
|
||
|
||
- 文档阶段：RequirementsDoc（需求规格说明）
|
||
- 项目类型：学习型小工具 / 全栈流程演示项目
|
||
- MVP 周期：约 4 天（单人开发）
|
||
- 目标用户：组内成员 / 演示使用
|
||
- 当前状态：需求已确认，小红书 / 抖音最小抓取链路已通过 API Spike 跑通
|
||
- 核心目标说明：本项目首要目标是完整跑通「热点榜单抓取 → 内容条目拆分 → 评论抓取 → 存储 → AI 分析 → 展示 → 导出」的全栈闭环流程，功能深度和规模服从于流程完整性。
|
||
|
||
---
|
||
|
||
## 2. 项目背景
|
||
|
||
组内希望有一个内部工具，用于：
|
||
|
||
- 获取小红书和抖音的热点榜单；
|
||
- 将每个热点拆分为相关内容条目，其中抖音内容条目为视频，小红书内容条目统一称为笔记；
|
||
- 抓取内容条目下的一级评论；
|
||
- 使用 AI 对评论的情绪和讨论方向进行结构化分析；
|
||
- 在 Web 页面查看分析结果，并支持导出。
|
||
|
||
现状：
|
||
|
||
- 已有小红书和抖音相关抓取 API 及 Key；
|
||
- 小红书最小链路已通过 `docs/API-Spike-Xiaohongshu.md` 验证：热榜 → 相关笔记 → 笔记一级评论；
|
||
- 抖音最小链路已通过 `docs/API-Spike-Douyin.md` 验证：热点榜单 → 相关视频 → 视频一级评论；
|
||
- 本文档只定义业务目标、范围与验收标准；
|
||
- 字段映射、分页、限流、异常码、规模稳定性等调用细节在后续技术文档和开发阶段继续确认。
|
||
|
||
---
|
||
|
||
## 3. 产品目标
|
||
|
||
### 3.1 总体目标
|
||
|
||
在 4 天单人开发周期内，完成一个可本机/局域网部署的演示型产品，体现从数据抓取到 AI 分析再到可视化与导出的完整技术链路。
|
||
|
||
### 3.2 MVP 目标
|
||
|
||
MVP 首要目标：流程跑通，而非功能完备或大规模数据处理。
|
||
|
||
需要覆盖的环节：
|
||
|
||
1. 获取小红书和抖音的热点榜单（每平台少量热点即可，具体见 5.1）。
|
||
2. 将每个热点拆分为相关内容条目，并抓取内容条目下的一级评论。
|
||
3. 使用 AI 对评论进行情绪与方向标签的结构化分析。
|
||
4. 在 Web 页面展示热点列表、热点级汇总报告、内容条目列表、内容条目详情与评论明细。
|
||
5. 支持导出评论明细、热点级汇总报告与内容条目级分析报告。
|
||
|
||
设计原则：
|
||
|
||
- 首先保证各环节功能打通；
|
||
- 规模、性能与健壮性在 MVP 阶段从简；
|
||
- 代码结构明确，便于后续扩展。
|
||
|
||
---
|
||
|
||
## 4. 用户与使用场景
|
||
|
||
### 4.1 目标用户
|
||
|
||
- 组内成员（包括开发者、产品、数据分析人员）；
|
||
- 技术演示或课堂讲解场景。
|
||
|
||
MVP 阶段：
|
||
|
||
- 不区分角色类型；
|
||
- 默认所有访问者具有相同功能权限。
|
||
|
||
### 4.2 核心使用场景
|
||
|
||
1. 用户打开系统的 Web 页面。
|
||
2. 用户选择平台（小红书 / 抖音），手动触发一次抓取任务。
|
||
3. 系统调用外部 API：
|
||
- 获取该平台的热点榜单（Top N）。
|
||
- 获取每个热点下的相关内容条目。
|
||
- 获取这些内容条目下的一级评论。
|
||
4. 系统调用 AI 对已抓取评论进行结构化分析：
|
||
- 情绪分类；
|
||
- 方向标签；
|
||
- 可选简短理由。
|
||
5. 用户在页面查看：
|
||
- 热点列表与内容条目列表（含抓取与分析状态）；
|
||
- 单个热点的汇总分析报告；
|
||
- 单个内容条目的分析报告；
|
||
- 评论明细。
|
||
6. 用户可将：
|
||
- 评论明细导出为 CSV；
|
||
- 热点级汇总报告导出为 Markdown；
|
||
- 内容条目级分析报告导出为 Markdown。
|
||
|
||
---
|
||
|
||
## 5. MVP 范围
|
||
|
||
### 5.1 热点榜单获取与内容条目拆分
|
||
|
||
功能范围：
|
||
|
||
- 支持两个平台：小红书、抖音。
|
||
- 每平台每次默认抓取 Top 5 条热点：
|
||
- 热点数量可配置到 Top 10；
|
||
- MVP 不追求 Top 50 或更大规模。
|
||
- 每个热点默认最多拆分 5 条相关内容条目：
|
||
- 内容条目数量可配置到 10 条；
|
||
- 如果某个热点下内容条目不足 5 条，则抓取全部可获得内容条目；
|
||
- MVP 不追求穷尽单个热点下所有视频/笔记。
|
||
- 抖音内容条目为视频；
|
||
- 小红书内容条目统一称为笔记，不区分图文笔记和视频笔记。
|
||
- 默认抓取规模约为：5 个热点 × 每热点 5 条内容条目 × 每条内容条目 50 条一级评论 = 1,250 条评论 / 平台 / 任务。
|
||
- 对每次抓取操作记录：
|
||
- 平台；
|
||
- 抓取执行时间（或日期）；
|
||
- 热点排名；
|
||
- 热点基础信息（如热点标题、热度值、榜单来源等，可根据 API 字段实际决定）；
|
||
- 内容条目基础信息（如标题/内容摘要、内容 ID、URL 等，可根据 API 字段实际决定）；
|
||
- 抓取状态（成功 / 失败）。
|
||
|
||
技术约束：
|
||
|
||
- 热点榜单和内容条目数据源来自已有外部 API；
|
||
- API 字段映射与数据结构以 API Spike 结果为基础，由后续技术文档继续细化。
|
||
|
||
### 5.2 评论抓取
|
||
|
||
功能范围：
|
||
|
||
- 仅抓取一级评论，不抓取二级评论或回复链。
|
||
- 每条内容条目默认最多抓取 50 条一级评论：
|
||
- 评论数量可配置到 100 条；
|
||
- 不足上限时抓取全部可获得的评论。
|
||
- 抓取顺序：
|
||
- 以 API 默认顺序为主（如时间顺序或热度顺序）；
|
||
- 不强制排序要求。
|
||
|
||
数据字段（视 API 支持情况而定）：
|
||
|
||
- 评论内容；
|
||
- 评论 ID（用于去重与关联）；
|
||
- 评论作者基础信息（如昵称或用户 ID）；
|
||
- 点赞数（如有）；
|
||
- 评论时间；
|
||
- 所属平台；
|
||
- 所属热点 ID/信息；
|
||
- 所属内容条目 ID/信息。
|
||
|
||
去重逻辑：
|
||
|
||
- 对同一内容条目重复抓取时，以评论 ID 做基本去重；
|
||
- 最简单策略为：同一内容条目同一评论 ID 不重复入库或更新已有记录。
|
||
|
||
### 5.3 任务触发
|
||
|
||
功能范围：
|
||
|
||
- MVP 仅支持用户手动触发抓取任务：
|
||
- 从前端点击按钮触发后端调用；
|
||
- 不做自动定时任务。
|
||
- 一次任务流程：
|
||
- 抓取热点榜单；
|
||
- 拆分热点下的相关内容条目；
|
||
- 抓取对应内容条目的一级评论；
|
||
- 调用 AI 分析评论；
|
||
- 生成内容条目级分析数据，供页面展示与导出。
|
||
- 不处理并发控制与多任务调度问题：
|
||
- 同一用户可重复触发任务；
|
||
- 同平台的多次任务视为独立执行，后续由开发计划决定是否覆盖或追加数据。
|
||
|
||
### 5.4 AI 评论分析
|
||
|
||
功能范围：
|
||
|
||
- 对每条评论进行结构化分析，输出结构包括：
|
||
- 情绪倾向：正向 / 负向 / 中性；
|
||
- 方向标签：AI 自动生成的开放标签，如：
|
||
- 价格争议；
|
||
- 外观种草；
|
||
- 使用体验；
|
||
- 质量吐槽；
|
||
- 求购买链接；
|
||
- 玩梗讨论；
|
||
- 等等；
|
||
- 可选简短理由：一句话解释该分类与标签的原因（非必需字段）。
|
||
|
||
标签体系：
|
||
|
||
- 不预设固定的标签字典；
|
||
- 允许模型自由生成标签；
|
||
- 标签主要用于：
|
||
- 后续统计汇总；
|
||
- 筛选典型评论。
|
||
|
||
约束说明：
|
||
|
||
- 近义标签合并不作为 MVP 强制要求：
|
||
- 如果实现方便，允许简单合并（如手动规则）；
|
||
- 未实现不影响 MVP 验收。
|
||
|
||
### 5.5 热点级汇总报告
|
||
|
||
功能范围：
|
||
|
||
- 对每个热点生成一份轻量热点级汇总报告；
|
||
- 报告基于该热点下已抓取内容条目的评论级分析结果聚合生成；
|
||
- MVP 不做平台级日报，也不做跨热点汇总报告。
|
||
|
||
报告至少包含：
|
||
|
||
1. 热点基础信息；
|
||
2. 该热点下内容条目数量；
|
||
3. 总评论样本数量；
|
||
4. 正向 / 负向 / 中性评论整体数量和占比；
|
||
5. Top 5 方向标签及数量；
|
||
6. 典型评论若干；
|
||
7. AI 生成的简短热点总结。
|
||
|
||
### 5.6 内容条目级分析报告
|
||
|
||
功能范围：
|
||
|
||
- 对每个内容条目生成一份内容条目级分析报告；
|
||
- 报告至少包含：
|
||
|
||
1. 样本评论数量；
|
||
2. 正向 / 负向 / 中性评论数量和占比；
|
||
3. 主要方向标签及占比（可按标签聚合统计）；
|
||
4. 典型评论：
|
||
- 典型正向评论 1~2 条；
|
||
- 典型负向评论 1~2 条；
|
||
- 典型中性评论 1~2 条；
|
||
- 典型的挑选可基于情绪+点赞数或由 AI 挑选；
|
||
5. AI 生成的简短内容条目级总结：
|
||
- 强调事实性统计、常见观点；
|
||
- 不要求深度运营洞察。
|
||
|
||
### 5.7 页面查看
|
||
|
||
功能范围：
|
||
|
||
- 热点与内容条目列表页：
|
||
- 展示抓取到的热点列表；
|
||
- 展示每个热点下的相关内容条目列表；
|
||
- 包含平台、热点标题、内容条目标题/摘要、抓取时间、分析状态等基本信息。
|
||
- 支持进入单个热点的汇总报告。
|
||
|
||
- 内容条目详情页：
|
||
- 展示内容条目级分析报告（见 5.6）；
|
||
- 展示评论明细列表：
|
||
- 评论内容；
|
||
- 情绪与方向标签；
|
||
- 点赞数等基础信息。
|
||
|
||
- 任务状态查看：
|
||
- 任务级状态：运行中 / 成功 / 失败；
|
||
- 每次任务的基本信息（时间、平台、热点数、内容条目数）。
|
||
|
||
UI 不要求精细设计，MVP 以简洁可用为目标。
|
||
|
||
### 5.8 导出
|
||
|
||
功能范围：
|
||
|
||
- 热点级汇总报告导出为 Markdown：
|
||
- 字段包括：热点基础信息、内容条目数量、评论样本量、情绪分布、方向标签分布、典型评论、总结；
|
||
- 以结构化 Markdown 文本输出，便于阅读和版本管理。
|
||
|
||
- 内容条目级报告导出为 Markdown：
|
||
- 字段包括：所属热点信息、内容条目基础信息、评论样本量、情绪分布、方向标签分布、典型评论、总结；
|
||
- 以结构化 Markdown 文本输出，便于阅读和版本管理。
|
||
|
||
- 内容条目评论明细导出为 CSV：
|
||
- 字段包括：平台、抓取日期/任务标识、热点信息、内容条目信息、评论内容、情绪、方向标签、点赞数、评论时间等；
|
||
- 用于后续本地分析或导入其他工具。
|
||
|
||
### 5.9 部署
|
||
|
||
部署目标：
|
||
|
||
- 使用 Docker Compose 实现一键启动：
|
||
- 后端服务；
|
||
- 前端服务；
|
||
- 数据库（如 PostgreSQL / MySQL / SQLite 服务化）；
|
||
- 支持在开发者本机或组内服务器部署；
|
||
- 通过浏览器访问 Web 页面进行操作。
|
||
|
||
具体技术选型：
|
||
|
||
- 在后续 DevelopmentPlan.md 中确定；
|
||
- MVP 要求 docker-compose.yml 能将所需组件统一编排。
|
||
|
||
---
|
||
|
||
## 6. 任务状态与异常处理（精简版）
|
||
|
||
功能范围：
|
||
|
||
- 任务状态：
|
||
- 运行中；
|
||
- 成功；
|
||
- 失败。
|
||
|
||
- 进度展示（可选，建议实现）：
|
||
- 已处理内容条目数 / 总内容条目数（例如“3 / 8”）；
|
||
- 简单数值即可，不做复杂进度条。
|
||
|
||
- 错误信息：
|
||
- 在任务详情中展示失败原因简要说明，例如：
|
||
- API 请求失败；
|
||
- API 响应异常；
|
||
- AI 调用失败或超时；
|
||
- 数据入库失败等。
|
||
|
||
- 容错行为：
|
||
- 单个热点或内容条目抓取或分析失败时：
|
||
- 记录错误；
|
||
- 尝试继续处理剩余热点或内容条目；
|
||
- 不要求严格保证“所有内容条目都成功”，但整体任务不因单个内容条目失败直接终止。
|
||
|
||
约束说明：
|
||
|
||
- 不做复杂任务编排和恢复机制；
|
||
- 不实现：
|
||
- 部分成功状态；
|
||
- 自动补跑；
|
||
- 分布式锁；
|
||
- 阶段拆分与单独重试。
|
||
|
||
---
|
||
|
||
## 7. 非功能需求
|
||
|
||
### 7.1 可用性
|
||
|
||
- 页面结构简单清晰，用户能快速理解：
|
||
- 当前有哪些抓取任务；
|
||
- 每个任务的状态；
|
||
- 热点、内容条目分析的结果与评论明细。
|
||
- 错误信息可见，方便调试与排查。
|
||
|
||
### 7.2 可维护性
|
||
|
||
- 核心流程模块化：
|
||
- 外部 API 调用；
|
||
- 数据存储；
|
||
- AI 分析；
|
||
- 报告生成；
|
||
- 前端展示与导出。
|
||
- 抓取参数可配置：
|
||
- 平台；
|
||
- 每次抓取的热点数量（Top N）；
|
||
- 单条内容条目评论上限。
|
||
- AI 提示词与输出 schema 单独管理，便于后续迭代。
|
||
|
||
### 7.3 数据质量
|
||
|
||
- 保留原始评论内容，不对原文做不可逆修改。
|
||
- AI 结构化结果（情绪、标签、理由）要与原始评论关联（如通过评论 ID）。
|
||
- 报告中的统计数据由结构化结果计算，而不是仅依赖模型自由生成的总体总结。
|
||
|
||
### 7.4 安全与配置
|
||
|
||
- API Key、AI Key 等敏感信息不写入代码仓库：
|
||
- 使用环境变量或配置文件（不纳入版本控制）。
|
||
- 系统默认用于内部环境，不开放公网访问。
|
||
- 登录鉴权：
|
||
- MVP 默认不做登录与权限控制；
|
||
- 如教学或审阅要求访问控制，再追加单管理员账号方案。
|
||
|
||
---
|
||
|
||
## 8. MVP 成功标准
|
||
|
||
必须达成的验收点：
|
||
|
||
1. 系统能通过 Docker Compose 启动，并在浏览器访问。
|
||
2. 用户可以从页面手动触发抓取任务，指定平台（小红书 / 抖音）。
|
||
3. 系统能从外部 API 获取该平台默认 Top 5 热点。
|
||
4. 系统能从每个热点拆分出相关内容条目，并对每条内容条目抓取一级评论（默认规模为 5 × 5 × 50，配置上限为 10 × 10 × 100）。
|
||
5. 系统能对评论生成：
|
||
- 情绪分类；
|
||
- 方向标签；
|
||
- （可选）简短理由。
|
||
6. 系统能生成并展示热点级汇总报告与内容条目级分析报告：
|
||
- 情绪分布；
|
||
- 标签分布；
|
||
- 典型评论；
|
||
- 简短总结。
|
||
7. 用户可以在页面查看：
|
||
- 热点列表；
|
||
- 热点级汇总报告；
|
||
- 内容条目列表；
|
||
- 内容条目详情；
|
||
- 评论明细。
|
||
8. 用户可导出：
|
||
- CSV 评论明细；
|
||
- Markdown 热点级汇总报告；
|
||
- Markdown 内容条目级分析报告。
|
||
9. 任务失败时，能看到任务状态为“失败”，并能看到简要错误原因。
|
||
|
||
质量与稳定性目标（尽力达成，不作为硬性阻塞）：
|
||
|
||
- 情绪分类与方向标签抽查时方向基本合理。
|
||
- 报告中的统计数据与评论结构化结果一致。
|
||
- 单个热点或内容条目失败不导致整批任务完全不可用。
|
||
|
||
---
|
||
|
||
## 9. 暂不纳入 MVP 的范围（Out of Scope）
|
||
|
||
以下能力明确不在 4 天 MVP 内：
|
||
|
||
- 定时自动抓取任务（如每日定时调度）。
|
||
- 任务并发控制、分布式锁、复杂任务调度。
|
||
- 自动补跑、任务阶段粒度显示（获取热点榜单、拆分内容条目、抓取评论、AI 分析等细粒度阶段）。
|
||
- 大规模批量抓取：
|
||
- Top 50 及以上热点；
|
||
- 单条内容条目 200 条及以上评论。
|
||
- 平台级每日汇总报告：
|
||
- 小红书整体 / 抖音整体的汇总分析；
|
||
- 跨热点聚合的 Top 话题、平台层总结等（降为后续 P1）。
|
||
- 多用户与角色权限管理：
|
||
- 注册、登录、角色控制、操作审计。
|
||
- 登录鉴权（除非明确教学需要）。
|
||
- Excel 导出、用户侧正式 JSON 导出。
|
||
- 二级评论抓取、评论回复功能、自动发布、私信运营。
|
||
- 长期趋势分析（跨天、跨周、跨月趋势）。
|
||
- 品牌专题分析、关键词筛选热点。
|
||
- 移动端适配、复杂 BI 大屏可视化。
|
||
- 评论人工标注校正工作台。
|
||
- 自动形成运营建议或营销动作。
|
||
- 外部分享链接、公开访问和权限控制。
|
||
|
||
---
|
||
|
||
## 10. 待确认事项
|
||
|
||
以下事项不阻塞本需求文档，在 PRD、DevelopmentPlan 或开发阶段逐步确认。小红书 / 抖音最小抓取链路已通过 API Spike 验证，后续重点是把已验证链路产品化、工程化：
|
||
|
||
1. 小红书 / 抖音热点榜单、内容条目与评论 API 的工程化细节：
|
||
- 字段映射与字段兼容策略；
|
||
- 原始 JSON 保存方式；
|
||
- 热点与内容条目的关联落库方式。
|
||
2. 评论 API 的：
|
||
- 分页策略；
|
||
- 排序规则（时间 / 热度）；
|
||
- 限流策略；
|
||
- 异常码定义。
|
||
3. AI 服务的选型：
|
||
- 提供商；
|
||
- 模型名称；
|
||
- 费用和调用速率限制；
|
||
- 是否需要批量调用或并发控制。
|
||
4. AI 输出结构的具体 schema：
|
||
- 字段名称；
|
||
- 枚举值规范（情绪、标签字段的格式约定）。
|
||
5. Docker Compose 的架构：
|
||
- 是否引入任务队列组件（如 Celery / Redis）；
|
||
- 或在 MVP 阶段采用简单同步处理。
|
||
|
||
---
|
||
|
||
## 11. 文档开发与审阅流程
|
||
|
||
采用 Spec 先行的文档驱动开发流程，文档顺序：
|
||
|
||
1. RequirementsDoc.md（当前文档）
|
||
2. PRD.md（产品需求文档）
|
||
3. FeatureSummary.md（功能拆解与优先级）
|
||
4. DevelopmentPlan.md（技术方案与实现路径）
|
||
5. UIDesign.md（关键页面与交互草图）
|
||
6. TDD.md（测试设计文档）
|
||
7. Tasks.md（任务拆解与排期）
|
||
|
||
审阅要求：
|
||
|
||
- 不直接修改主文档，每个审阅方生成独立审阅文件：
|
||
- 文件命名建议：`review-<文档名>-<审阅方>.md`。
|
||
- 审阅语言为中文，采用结构化形式。
|
||
- 审阅重点：
|
||
- 缺失需求；
|
||
- 模糊或冲突需求；
|
||
- 过度设计风险；
|
||
- 验收标准是否充分；
|
||
- 后续文档与实现的风险点。
|
||
- 审阅发现需要用户决策的问题时：
|
||
- 以问题或建议形式提出；
|
||
- 不擅自更改主文档。
|
||
- 主 AI 负责汇总多方审阅意见，形成修订建议；
|
||
- 用户确认修订后的主文档后，方可进入下一阶段文档编写。
|
||
|
||
---
|