hot_comment_radar/docs/RequirementsDoc.md

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

---