hot_comment_radar/docs/FeatureSummary.md

FeatureSummary.md：小红书 / 抖音热榜评论抓取 + AI 分析报告工具

1. 文档信息

• 文档阶段：FeatureSummary（产品功能文档）
• 需求来源：docs/RequirementsDoc.md、docs/PRD.md
• API Spike 依据：docs/API-Spike-Xiaohongshu.md、docs/API-Spike-Douyin.md
• 项目类型：学习型小工具 / 全栈流程演示项目
• MVP 周期：约 4 天（单人开发）
• 当前版本目标：将 PRD 中的产品需求拆解为功能模块、优先级、验收点与后续技术文档衔接事项

---

2. 功能总览

MVP 核心流程：

用户手动触发任务
→ 选择平台（小红书 / 抖音）
→ 获取热点榜单
→ 按热点拆分相关内容条目
→ 抓取内容条目一级评论
→ AI 评论级结构化分析
→ 生成热点级与内容条目级报告
→ 页面查看
→ 导出 Markdown / CSV

功能模块：

1. 任务创建与任务状态管理
2. 平台选择与抓取参数配置
3. 小红书热点、笔记与评论抓取
4. 抖音热点、视频与评论抓取
5. 数据存储与原始响应保留
6. AI 评论级结构化分析
7. 热点级汇总报告
8. 内容条目级分析报告
9. 页面查看
10. 导出
11. 异常处理与基础容错
12. 配置、安全与部署

---

3. 优先级定义

• P0：MVP 必须实现，缺失会导致主流程无法验收。
• P1：MVP 建议实现，可提升可用性或排障效率，但不应阻塞主流程。
• P2：后续版本考虑，当前 FeatureSummary 仅记录为边界，不纳入 4 天 MVP。

---

4. P0 功能列表

F01 任务创建与状态管理

功能目标：

• 用户可以从页面手动创建一次抓取任务；
• 系统记录任务平台、创建时间、任务状态、错误原因与基础统计信息；
• 任务状态支持运行中、成功、失败。

功能范围：

• 支持手动触发，不支持定时触发；
• 创建任务后前端不需要等待整个抓取和 AI 分析流程同步完成；
• 同一用户可重复创建任务，多次任务视为独立执行；
• 任务最终状态规则：
  • 没有任何内容条目成功完成抓取和分析时，任务失败；
  • 至少 1 条内容条目成功完成抓取和分析时，任务可标记成功，并展示失败内容条目数或错误摘要。
• AI 分析质量不扩展任务状态模型，使用独立字段记录：
  • analysis_success_rate：任务内成功生成情绪分类和方向标签的评论占比；
  • analysis_status：AI 分析质量状态，可取值为正常、分析不足；
  • 当 analysis_success_rate < 80% 时，任务状态仍可按内容条目处理结果标记成功，但 analysis_status 标记为分析不足。
• 任务数据模型须包含：
  • total_items_count：任务内计划或实际纳入处理的内容条目总数；
  • processed_items_count：已完成抓取与分析处理的内容条目数；
  • successful_items_count：成功完成抓取与分析的内容条目数。
  • analysis_success_rate；
  • analysis_status。

核心验收：

• 用户可以在页面创建任务；
• 任务创建后可在任务列表看到记录；
• 任务完成后状态能更新为成功或失败；
• AI 分析成功率低于 80% 时，任务列表可展示分析不足提示；
• 失败时页面能展示简要错误原因。

F02 平台选择与抓取规模配置

功能目标：

• 用户可以选择抓取平台；
• 用户可以在任务创建页面调整 MVP 抓取规模；
• 系统按用户配置或默认规模执行抓取。

功能范围：

• 支持平台：小红书、抖音；
• 任务创建页面提供抓取规模配置项：
  • 热点关键词数量上限：默认 5，取值范围 1–10；
  • 每热点内容条目数上限：默认 5，取值范围 1–10；
  • 每内容条目评论数上限：默认 50，取值范围 10–100。
• 默认约 1,250 条评论 / 平台 / 任务；
• 具体上限值可由 DevelopmentPlan 结合平台 API 限制最终确认，但 MVP 页面须提供配置入口。

核心验收：

• 用户创建任务时可以明确选择小红书或抖音；
• 用户创建任务时可以查看并调整抓取规模配置；
• 前端对抓取规模配置做范围校验，非法值不能提交；
• 任务记录保存所选平台；
• 未调整配置时，系统按默认规模抓取数据。

F03 小红书抓取链路

功能目标：

• 根据小红书热榜获取相关笔记，并抓取笔记一级评论。

已验证链路：

fetch_hot_list
→ data.data.items[].title
→ search_notes(keyword = hot.title)
→ note.id
→ get_note_comments(note_id)
→ comments

功能范围：

• 获取小红书热榜；
• 从热榜条目读取真实热榜标题；
• 使用热榜标题搜索相关笔记；
• 优先选择 comments_count > 0 的笔记；
• 若 comments_count > 0 的笔记不足目标数量，补充选取 comments_count = 0 的笔记至目标数；
• 若平台返回总笔记数本身不足目标数，以实际可用数量为准，不视为任务失败；
• 使用笔记 ID 抓取一级评论；
• 若单次评论 API 返回评论数不足目标值，继续翻页请求；
• 评论翻页终止条件：达到目标评论数、API 返回数据为空，或达到最大翻页轮次；
• 最大翻页轮次建议 5 次，最终由 DevelopmentPlan 结合 API 特性确认；
• 翻页期间遇到限流时，沿用 F11 的指数退避策略；
• 小红书内容条目统一称为笔记，不区分图文笔记和视频笔记。

核心验收：

• 系统能展示小红书 Top 5 热点；
• 每个热点最多展示 5 条相关笔记；
• 每条成功获取的笔记能抓取最多 50 条一级评论；
• 评论至少保留评论内容和所属笔记关系；
• 字段缺失时不阻塞整体流程。

F04 抖音抓取链路

功能目标：

• 根据抖音热点榜单获取相关视频，并抓取视频一级评论。

已验证链路：

fetch_creator_hot_spot_billboard
→ hot.title
→ fetch_video_search_v2(keyword = hot.title)
→ aweme_info.aweme_id
→ fetch_video_comments(aweme_id)
→ comments

功能范围：

• 获取抖音热点榜单；
• 从热点榜单读取热点标题；
• 使用热点标题搜索相关视频；
• 从搜索结果读取视频 aweme_id；
• 使用 aweme_id 抓取一级评论；
• 若单次评论 API 返回评论数不足目标值，继续翻页请求；
• 评论翻页终止条件：达到目标评论数、API 返回数据为空，或达到最大翻页轮次；
• 最大翻页轮次建议 5 次，最终由 DevelopmentPlan 结合 API 特性确认；
• 翻页期间遇到限流时，沿用 F11 的指数退避策略；
• 抖音内容条目为视频。

核心验收：

• 系统能展示抖音 Top 5 热点；
• 每个热点最多展示 5 条相关视频；
• 每条成功获取的视频能抓取最多 50 条一级评论；
• 评论至少保留评论内容和所属视频关系；
• 字段缺失时不阻塞整体流程。

F05 数据存储与原始响应保留

功能目标：

• 保存任务、热点、内容条目、评论、AI 分析结果与报告所需数据；
• 保留原始 API 响应，便于排障和后续字段调整。

功能范围：

• 任务数据：
  • 任务 ID；
  • 平台；
  • 创建时间；
  • 状态；
  • 错误原因；
  • 已获取热点数；
  • 已获取内容条目数；
  • total_items_count；
  • processed_items_count；
  • successful_items_count。
• 热点数据：
  • 平台；
  • 任务 ID；
  • 排名；
  • 热点 ID；
  • 热点标题或摘要；
  • 热度值或榜单指标；
  • 原始 API 响应。
• 内容条目数据：
  • 平台；
  • 任务 ID；
  • 所属热点 ID；
  • 内容条目 ID；
  • 内容条目类型；
  • 标题或内容摘要；
  • URL；
  • 抓取状态或分析状态；
  • 原始 API 响应。
• 评论数据：
  • 评论 ID；
  • 所属热点；
  • 所属内容条目；
  • 评论内容；
  • 作者基础信息；
  • 点赞数；
  • 评论时间；
  • 情绪倾向；
  • 方向标签；
  • 可选简短理由；
  • 原始评论 API 响应；
  • 可选 AI 原始响应。

核心验收：

• 任务、热点、内容条目、评论之间有关联关系；
• 原始评论内容必须保留；
• AI 分析结果能追溯到原始评论；
• 同一任务内，同一内容条目下同一评论 ID 不重复入库，或重复抓取时更新已有记录。

F06 AI 评论级结构化分析

功能目标：

• 对已抓取评论生成结构化分析结果，支撑评论明细展示和报告统计。

功能范围：

• 对每条评论输出：
  • 情绪倾向：正向、负向、中性；
  • 方向标签：AI 自动生成的开放标签，每条评论可有 1~3 个标签；
  • 简短理由：可选字段。
• 不预设固定标签字典；
• 近义标签合并不作为 MVP 强制要求；
• AI 分析建议按批量处理思路实现，具体批量大小由 DevelopmentPlan 确认；
• 具体批量大小和并发策略依赖 AI 服务选型结果，由 DevelopmentPlan 确认；
• Prompt 须强制要求 LLM 返回严格 JSON Array 结构，禁止混入自然语言说明；
• 后端须对 LLM 输出做 JSON Schema 校验；
• 解析失败时触发重试，最多 N 次，N 由 DevelopmentPlan 结合所选 AI 服务确认，建议 3 次；
• AI 返回无法解析或缺失必填字段时，单条评论标记为未知、空标签或分析失败，不阻塞其他评论。
• 任务完成后统计 analysis_success_rate；低于 80% 时写入 analysis_status = 分析不足，但不改变任务成功 / 失败状态。

核心验收：

• 已抓取评论能生成情绪分类；
• 已抓取评论能生成方向标签，或在无法判断时给出空标签 / 未知标签；
• 评论明细页能展示评论内容、情绪和标签；
• 单条 AI 分析失败不会导致整个任务崩溃。

F07 热点级汇总报告

功能目标：

• 为每个热点生成一份轻量汇总报告，展示该热点下所有内容条目的整体评论情况。

功能范围：

• 报告基于该热点下所有已分析内容条目的评论级结构化结果聚合生成；
• MVP 阶段建议采用预生成型报告：任务完成后由后台生成并存库，用户访问报告页时读取已生成结果；
• 若 DevelopmentPlan 改为实时聚合，须明确响应延迟、重复计算和缓存策略；
• 报告至少包含：
  • 热点基础信息；
  • 内容条目数量；
  • 总评论样本数量；
  • 正向、负向、中性评论数量和占比；
  • Top 5 方向标签及数量；
  • 典型评论若干；
  • AI 生成的简短热点总结。
• 情绪分布和标签分布由评论级结构化结果计算；
• 方向标签按字面值聚合，不要求语义近义标签自动归并；
• 热点总结建议不超过 300 字；
• 不做平台级日报或跨热点汇总。

核心验收：

• 每个已完成分析的热点可查看热点级汇总报告；
• 报告中的内容条目数、样本数、情绪数量和占比与评论明细一致；
• 报告可以导出为 Markdown。

F08 内容条目级分析报告

功能目标：

• 为每条内容条目生成一份分析报告，展示单条视频 / 笔记的评论反馈。

功能范围：

• 报告至少包含：
  • 样本评论数量；
  • 正向、负向、中性评论数量和占比；
  • 主要方向标签及占比；
  • 典型正向评论 1~2 条；
  • 典型负向评论 1~2 条；
  • 典型中性评论 1~2 条；
  • AI 生成的简短内容条目级总结。
• 情绪分布和标签分布由评论级结构化结果计算；
• MVP 阶段建议采用预生成型报告：任务完成后由后台生成并存库，用户访问报告页时读取已生成结果；
• 若 DevelopmentPlan 改为实时聚合，须明确响应延迟、重复计算和缓存策略；
• 方向标签按字面值聚合，MVP 展示 Top 5 标签及数量；
• 典型评论默认按情绪分组后按点赞数降序选取；
• 如果点赞数字段不可用，按抓取顺序选取；
• 内容条目级总结建议不超过 200 字。

核心验收：

• 每条已完成分析的内容条目可查看内容条目级报告；
• 报告中的样本数、情绪数量和占比与评论明细一致；
• 报告可以导出为 Markdown。

F09 页面查看

功能目标：

• 用户可以在 Web 页面完成任务创建、状态查看、结果浏览和导出操作。

页面范围：

• 任务列表 / 首页；
• 热点与内容条目列表页；
• 热点级汇总报告页；
• 内容条目详情页；
• 评论明细展示区域。

页面能力：

• 任务列表 / 首页：
  • 平台选择；
  • 抓取规模配置表单区域；
  • 配置项输入范围提示与非法值校验；
  • 手动触发按钮；
  • 刷新任务列表按钮；
  • 任务创建时间；
  • 任务状态；
  • AI 分析状态或分析成功率；
  • 成功 X / 共 Y 条内容条目；
  • 任务基础信息；
  • 错误原因；
  • 可选基础进度。
• 热点与内容条目列表页：
  • 平台；
  • 抓取时间或任务标识；
  • 任务状态和错误原因；
  • AI 分析状态或分析成功率；
  • 成功 X / 共 Y 条内容条目；
  • 热点排名；
  • 热点标题或摘要；
  • 内容条目标题或摘要；
  • 内容条目类型；
  • 分析状态；
  • 进入热点级报告和内容条目详情的入口。
• 热点级汇总报告页：
  • 热点基础信息；
  • 内容条目数量；
  • 样本数量；
  • 情绪分布；
  • Top 5 方向标签；
  • 典型评论；
  • 简短热点总结；
  • Markdown 导出入口。
• 内容条目详情页：
  • 热点基础信息；
  • 内容条目基础信息；
  • 内容条目级分析报告；
  • 评论明细；
  • Markdown 报告导出入口；
  • CSV 评论明细导出入口。

核心验收：

• 用户可以从任务进入热点与内容条目列表；
• 用户可以进入热点级汇总报告；
• 用户可以进入内容条目详情；
• 用户可以在详情中同时查看统计结果和原始评论；
• 任务运行中时，用户可通过手动刷新按钮更新任务状态；
• 任务列表展示任务创建时间，供用户判断任务执行时长；
• 导出入口清晰可见。

F10 导出

功能目标：

• 用户可以将报告和评论明细导出为文件，用于本地分析、分享或归档。

功能范围：

• 热点级汇总报告导出为 Markdown；
• 内容条目级分析报告导出为 Markdown；
• 内容条目评论明细导出为 CSV。
• CSV 使用 UTF-8-SIG 编码，确保国内用户通过 Excel 直接打开时中文字符正常显示；
• CSV 文件命名格式为 {platform}_{task_id}_{hotspot_keyword}.csv；
• hotspot_keyword 超过 20 字符时截断并附加省略号，避免文件名过长。

核心字段：

• Markdown 热点级汇总报告：
  • 热点基础信息；
  • 内容条目数量；
  • 评论样本量；
  • 情绪分布；
  • 方向标签分布；
  • 典型评论；
  • 热点总结。
• Markdown 内容条目级报告：
  • 所属热点信息；
  • 内容条目基础信息；
  • 评论样本量；
  • 情绪分布；
  • 方向标签分布；
  • 典型评论；
  • 内容条目总结。
• CSV 内容条目评论明细：
  • 平台；
  • 抓取日期或任务标识；
  • 热点信息；
  • 内容条目信息；
  • 评论 ID；
  • 评论内容；
  • 情绪倾向；
  • 方向标签；
  • 点赞数；
  • 评论时间。

核心验收：

• 用户能下载 CSV 评论明细；
• 用户能下载 Markdown 热点级汇总报告；
• 用户能下载 Markdown 内容条目级报告；
• 导出内容与页面展示一致。

F11 异常处理与基础容错

功能目标：

• 保证单个热点、内容条目或评论分析失败时，尽量不影响整批任务继续执行。

功能范围：

• 错误信息展示：
  • API 请求失败；
  • 平台 API 请求被限流（HTTP 429）；
  • API 响应异常；
  • AI 调用失败或超时；
  • 数据入库失败。
• 容错行为：
  • 单个热点或内容条目抓取 / 分析失败时记录错误；
  • 收到 429 响应时，采用指数退避策略重试，建议等待间隔为 1s → 2s → 4s；
  • 超过最大重试次数后将该条目标记为失败，继续处理后续条目，不阻断整批任务；
  • 尝试继续处理剩余热点或内容条目；
  • AI 单条解析失败时，该评论标记为未知或分析失败；
  • 用户输入非法抓取规模配置值时，前端提示具体字段错误并阻止提交；
  • 不新增“部分成功”或“部分失败”任务状态；当 AI 结构化成功率不足但仍有可查看结果时，统一使用 analysis_status 标记分析不足。

核心验收：

• 单个内容条目失败不直接终止整个任务；
• 任务失败时可看到失败状态和简要错误原因；
• 错误原因至少包含失败阶段和错误类型；
• 至少 1 条内容条目成功完成抓取和分析时，任务可产生可查看结果。

F12 配置、安全与部署

功能目标：

• 支持本机或组内服务器部署；
• 敏感配置不进入代码仓库。

功能范围：

• 使用 Docker Compose 统一编排所需组件；
• 支持浏览器访问 Web 页面；
• API Key、AI Key 等通过环境变量或未纳入版本控制的配置文件管理；
• 默认用于内部环境，不面向公网开放；
• MVP 默认不做登录和权限控制。

核心验收：

• 系统可以通过 Docker Compose 启动；
• 启动后可在浏览器访问；
• 敏感配置不写入代码仓库。

---

5. P1 功能列表

P1 功能不应阻塞 MVP 主流程，但可在时间允许时实现。

F13 基础进度展示

功能范围：

• 展示已处理内容条目数 / 总内容条目数；
• 可展示成功内容条目数 / 失败内容条目数；
• 前端进度展示直接复用 F01 的 processed_items_count、total_items_count 和 successful_items_count 字段；
• 禁止前后端各自独立实现进度计数逻辑；
• 不做复杂进度条和阶段级任务编排。

F14 前端自动刷新

功能范围：

• 任务运行中时，前端可用简单轮询刷新任务状态；
• P0 已提供手动刷新兜底，P1 在此基础上实现自动轮询；
• 若未实现自动轮询，用户通过刷新按钮或页面刷新查看最新状态。

F15 开发调试信息入口

功能范围：

• 在内容条目详情页可选展示原始 JSON；
• 仅用于开发和排障；
• 不作为正式用户功能。

---

6. P2 / 当前不纳入范围

以下能力不纳入当前 4 天 MVP：

• 定时自动抓取任务；
• 任务并发控制、分布式锁、复杂任务调度；
• 自动补跑、任务阶段粒度展示、单条内容条目单独重试；
• Top 50 及以上热点抓取；
• 单条内容条目 200 条及以上评论抓取；
• 平台级每日汇总报告；
• 跨热点聚合 Top 话题和平台层总结；
• 登录鉴权；
• 多用户与角色权限管理；
• 操作审计；
• Excel 导出；
• 用户侧正式 JSON 导出；
• 二级评论抓取；
• 评论回复、自动发布、私信运营；
• 长期趋势分析；
• 品牌专题分析；
• 关键词筛选热点；
• 移动端适配；
• 复杂 BI 大屏；
• 评论人工标注校正工作台；
• 自动形成运营建议或营销动作；
• 外部分享链接、公开访问和权限控制。

---

7. 功能依赖关系

F02 平台选择与抓取规模配置
→ F01 任务创建与状态管理
→ F03 小红书抓取链路 / F04 抖音抓取链路
→ F05 数据存储与原始响应保留
→ F06 AI 评论级结构化分析
→ F07 热点级汇总报告 / F08 内容条目级分析报告
→ F09 页面查看
→ F10 导出

横向支撑能力：

• F11 异常处理与基础容错；
• F12 配置、安全与部署。

---

8. 关键验收清单

MVP 完成时至少需要满足：

1. 系统可通过 Docker Compose 启动，并能在浏览器访问。
2. 用户可从页面选择小红书或抖音并手动触发任务。
3. 系统可获取默认 Top 5 热点。
4. 系统可为每个热点拆分默认最多 5 条内容条目。
5. 系统可为每条内容条目抓取默认最多 50 条一级评论。
6. 任务内至少 80% 的评论成功生成情绪分类和方向标签，视为该验收项通过；低于此比例时任务状态仍遵循成功 / 失败规则，但 analysis_status 须标记为分析不足，并在页面展示提示。
7. 系统可生成热点级汇总报告。
8. 系统可生成内容条目级分析报告。
9. 页面可查看任务列表、热点列表、热点级报告、内容条目详情和评论明细。
10. 用户可导出 CSV 评论明细。
11. 用户可导出 Markdown 热点级汇总报告。
12. 用户可导出 Markdown 内容条目级报告。
13. 任务失败时，页面可展示失败状态，错误原因须至少包含失败阶段（如：数据抓取阶段 / AI 分析阶段）和错误类型（如：网络超时 / API 限流 / 解析失败）。
14. 报告统计数据与评论结构化结果一致。

---

9. 后续文档衔接

9.1 DevelopmentPlan.md 需要重点解决

• AI 服务选型须作为第一优先决策项，在架构设计开始前锁定；
• AI 服务选型需覆盖：批量接口支持能力、输出 JSON Schema 控制方式、单次 Token 上限、API 调用成本估算；
• AI 请求并发数上限与单次请求超时时间，建议并发不超过 3 个、超时 30s；
• 后台任务实现方式：简单线程 / 协程、任务队列或其他方案；
• 数据库选型与表结构设计；
• 小红书 / 抖音字段映射和兼容策略；
• 评论分页、限流、异常码与失败处理；
• AI 服务选型、批量大小、输出 schema、解析失败兜底；
• 报告生成策略：预生成或实时聚合；若采用预生成型，须同步确认报告数据的更新 / 重算触发机制；
• 报告生成逻辑和统计计算方式；
• 同一内容条目（相同 URL 或内容 ID）出现在多个热点搜索结果中时的去重策略；建议 MVP 阶段保留重复数据，并通过 task_id + hotspot_id + item_id 联合主键区分；
• 前后端 API 契约；
• Docker Compose 组件和启动验收方式；
• 是否提供 /health 健康检查端点。

9.2 UIDesign.md 需要重点解决

• 任务列表 / 首页信息结构；
• 热点与内容条目列表的信息层级；
• 热点级汇总报告展示方式；
• 内容条目详情页与评论明细布局；
• 导出入口位置；
• 任务运行中、失败、空数据状态展示。

9.3 TDD.md 需要重点覆盖

• 平台选择与任务创建；
• 小红书字段映射；
• 抖音字段映射；
• 评论去重；
• 空评论场景；
• 单个内容条目失败但任务继续；
• AI 输出解析失败；
• 情绪和标签统计一致性；
• Markdown / CSV 导出内容一致性。

9.4 Tasks.md 需要按模块拆解

• 后端任务与状态；
• 小红书抓取；
• 抖音抓取；
• 数据模型；
• AI 分析；
• 报告生成；
• 前端页面；
• 导出；
• Docker Compose；
• 测试与验收。

---

10. 审阅建议

后续三 AI 审阅 FeatureSummary.md 时，建议重点检查：

1. 是否忠实继承 RequirementsDoc.md 和 PRD.md；
2. 是否误加入当前 MVP 不需要的新功能；
3. P0 / P1 / P2 优先级是否合理；
4. 是否遗漏主流程中的关键功能模块；
5. 验收清单是否可测；
6. 是否有需要用户重新决策的问题。