# 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 负责汇总多方审阅意见，形成修订建议；
- 用户确认修订后的主文档后，方可进入下一阶段文档编写。

---