feat: 初始化项目，添加文档

2026-07-01 16:59:59 +08:00
commit 289d7e2c82
9 changed files with 4447 additions and 0 deletions
@@ -0,0 +1,265 @@
+# API-Spike-Xiaohongshu.md：小红书热榜到评论抓取链路验证
+
+## 1. 文档信息
+
+- 文档阶段：API Spike 验证
+- 验证平台：小红书
+- API 服务：TikHub API
+- 验证目标：确认「小红书热榜 → 热点相关笔记 → 单篇笔记一级评论」链路可跑通
+- 验证结论：链路已跑通，可作为 MVP 阶段小红书评论抓取方案
+
+---
+
+## 2. 最终跑通链路
+
+MVP 阶段小红书抓取采用以下链路：
+
+1. 获取小红书热榜。
+2. 从热榜列表中读取真实热榜标题。
+3. 使用热榜标题作为关键词搜索小红书笔记。
+4. 从搜索结果中优先选择 `comments_count > 0` 的笔记。
+5. 使用笔记 `note_id` 获取单篇笔记一级评论。
+
+链路表达：
+
+```text
+fetch_hot_list
+→ data.data.items[].title
+→ search_notes(keyword = hot.title)
+→ note.id
+→ get_note_comments(note_id)
+→ comments
+```
+
+---
+
+## 3. 接口一：获取小红书热榜
+
+### 3.1 接口信息
+
+```http
+GET https://api.tikhub.io/api/v1/xiaohongshu/web_v2/fetch_hot_list
+```
+
+### 3.2 MVP 请求参数
+
+该接口 MVP 阶段不需要额外请求参数。
+
+### 3.3 MVP 需要字段
+
+真实热榜条目位于：
+
+```text
+data.data.items[]
+```
+
+热榜条目需要读取：
+
+```text
+id
+title
+score
+rank_change
+type
+word_type
+```
+
+字段用途：
+
+- `id`：热榜条目原始 ID，作为热点原始标识保存。
+- `title`：热榜标题，用于后续关键词搜索笔记。
+- `score`：热榜热度值。
+- `rank_change`：排名变化。
+- `type`：热榜条目类型。
+- `word_type`：热榜标签，如「热」或「无」。
+
+注意：
+
+```text
+data.data.title
+```
+
+是热榜模块标题，例如「搜索发现」，不应作为热榜条目使用。
+
+---
+
+## 4. 接口二：通过热榜标题搜索相关笔记
+
+### 4.1 接口信息
+
+```http
+GET https://api.tikhub.io/api/v1/xiaohongshu/app_v2/search_notes
+```
+
+### 4.2 MVP 请求参数
+
+```text
+keyword=<热榜标题>
+page=1
+sort=general
+note_type=0
+```
+
+参数含义：
+
+- `keyword`：热榜标题，来自 `data.data.items[].title`。
+- `page=1`：第一页搜索结果。
+- `sort=general`：综合排序。
+- `note_type=0`：不限笔记类型。
+
+### 4.3 MVP 需要字段
+
+搜索结果中的笔记信息位于：
+
+```text
+data.data.items[].note
+```
+
+笔记条目需要读取：
+
+```text
+id
+title
+desc
+type
+user
+liked_count / nice_count
+comments_count
+collected_count
+shared_count
+timestamp / update_time
+```
+
+字段用途：
+
+- `id`：笔记 ID，用于后续评论抓取。
+- `title`：笔记标题。
+- `desc`：笔记正文或摘要。
+- `type`：笔记类型，如图文或视频。
+- `user`：作者基础信息。
+- `liked_count` 或 `nice_count`：点赞数。
+- `comments_count`：评论数，用于优先选择有评论的笔记。
+- `collected_count`：收藏数。
+- `shared_count`：分享数。
+- `timestamp` 或 `update_time`：发布时间或更新时间。
+
+---
+
+## 5. 接口三：获取单篇笔记一级评论
+
+### 5.1 接口信息
+
+```http
+GET https://api.tikhub.io/api/v1/xiaohongshu/app_v2/get_note_comments
+```
+
+### 5.2 MVP 请求参数
+
+```text
+note_id=<笔记 id>
+cursor=
+index=0
+pageArea=UNFOLDED
+sort_strategy=latest_v2
+```
+
+参数含义：
+
+- `note_id`：笔记 ID，来自搜索结果中的 `data.data.items[].note.id`。
+- `cursor`：评论分页游标，第一页为空。
+- `index=0`：第一页索引。
+- `pageArea=UNFOLDED`：评论展开区域。
+- `sort_strategy=latest_v2`：按最新评论排序。
+
+### 5.3 MVP 需要字段
+
+评论列表位于：
+
+```text
+data.data.comments[]
+```
+
+评论条目需要读取：
+
+```text
+id / comment_id
+content / text
+user_info / user
+like_count
+create_time
+```
+
+字段用途：
+
+- `id` 或 `comment_id`：评论 ID，用于去重和关联。
+- `content` 或 `text`：评论正文。
+- `user_info` 或 `user`：评论作者基础信息。
+- `like_count`：评论点赞数。
+- `create_time`：评论发布时间。
+
+---
+
+## 6. 已验证样例
+
+本次验证中，小红书链路已成功跑通以下样例：
+
+```text
+热榜标题：耗时三年拍下古诗词里的中国
+搜索笔记：张岱笔下的江南夜色，一字入画
+note_id：6a4319410000000217023ee7
+评论 ID：6a433517000000001403b657
+评论内容：都很美啊！[点赞R]
+```
+
+该样例证明：
+
+1. 可以获取小红书真实热榜条目。
+2. 可以基于热榜标题搜索到相关笔记。
+3. 可以从笔记搜索结果中获取 `note_id`。
+4. 可以基于 `note_id` 获取笔记一级评论。
+
+---
+
+## 7. MVP 开发结论
+
+小红书侧 MVP 抓取链路采用：
+
+```text
+热榜接口
+→ 热榜标题关键词搜索笔记
+→ 笔记评论接口
+```
+
+开发阶段应注意：
+
+1. 热榜真实条目应从 `data.data.items[]` 读取，不要使用外层模块标题。
+2. 搜索结果不要无脑取第一条，应优先选择 `comments_count > 0` 的笔记。
+3. 笔记评论接口返回空评论时不一定是接口失败，可能是该笔记本身无评论。
+4. 外部 API 字段映射应保持可调整，并保留原始 JSON 响应用于排障。
+
+MVP 阶段建议默认抓取规模：
+
+```text
+Top 5 热榜
+× 每个热榜最多 5 篇笔记
+× 每篇笔记最多 50 条一级评论
+```
+
+正式实现中应支持配置：
+
+```text
+hot_limit
+note_limit_per_hot
+comment_limit_per_note
+```
+
+---
+
+## 8. 后续文档衔接
+
+本 API Spike 结果用于支撑后续文档：
+
+1. `FeatureSummary.md`：拆解小红书抓取相关功能模块。
+2. `DevelopmentPlan.md`：设计后端服务、任务流程、数据模型和异常处理。
+3. `TDD`：围绕字段映射、分页、空评论、去重和任务状态编写测试。
+4. `Tasks`：拆分具体开发任务。