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

2026-07-01 16:59:59 +08:00
commit 289d7e2c82
9 changed files with 4447 additions and 0 deletions
@@ -0,0 +1,235 @@
+# API-Spike-Douyin.md：抖音热点到评论抓取链路验证
+
+## 1. 文档信息
+
+- 文档阶段：API Spike 验证
+- 验证平台：抖音
+- API 服务：TikHub API
+- 验证目标：确认「抖音热点榜单 → 热点相关视频 → 单个视频一级评论」链路可跑通
+- 验证结论：链路已跑通，可作为 MVP 阶段抖音评论抓取方案
+
+---
+
+## 2. 最终跑通链路
+
+MVP 阶段抖音抓取采用以下链路：
+
+1. 获取抖音创作者热点榜单。
+2. 从热点榜单中读取热点标题。
+3. 使用热点标题作为关键词搜索抖音视频。
+4. 从搜索结果中读取视频 `aweme_id`。
+5. 使用 `aweme_id` 获取单个视频一级评论。
+
+链路表达：
+
+```text
+fetch_creator_hot_spot_billboard
+→ hot.title
+→ fetch_video_search_v2(keyword = hot.title)
+→ aweme_info.aweme_id
+→ fetch_video_comments(aweme_id)
+→ comments
+```
+
+---
+
+## 3. 接口一：获取抖音热点榜单
+
+### 3.1 接口信息
+
+```http
+GET https://api.tikhub.io/api/v1/douyin/creator/fetch_creator_hot_spot_billboard
+```
+
+### 3.2 MVP 请求参数
+
+```text
+billboard_tag=0
+hot_search_type=1
+```
+
+参数含义：
+
+- `billboard_tag=0`：获取全部热点标签。
+- `hot_search_type=1`：获取热点总榜。
+
+### 3.3 MVP 需要字段
+
+热点条目需要读取：
+
+```text
+query_id
+title
+rank
+category
+hot_score
+```
+
+字段用途：
+
+- `query_id`：热点 ID，作为热点原始标识保存。
+- `title`：热点标题，用于后续关键词搜索视频。
+- `rank`：热点排名。
+- `category`：热点分类。
+- `hot_score`：热点热度值。
+
+---
+
+## 4. 接口二：通过热点标题搜索相关视频
+
+### 4.1 接口信息
+
+```http
+POST https://api.tikhub.io/api/v1/douyin/search/fetch_video_search_v2
+```
+
+### 4.2 MVP 请求体
+
+```json
+{
+  "keyword": "<热点标题>",
+  "cursor": 0,
+  "sort_type": "0",
+  "publish_time": "0",
+  "filter_duration": "0",
+  "content_type": "1",
+  "search_id": "",
+  "backtrace": ""
+}
+```
+
+参数含义：
+
+- `keyword`：热点标题，来自热点榜单条目的 `title`。
+- `cursor=0`：第一页搜索结果。
+- `sort_type=0`：综合排序。
+- `publish_time=0`：不限发布时间。
+- `filter_duration=0`：不限视频时长。
+- `content_type=1`：搜索视频内容。
+
+### 4.3 MVP 需要字段
+
+视频条目需要读取：
+
+```text
+aweme_info.aweme_id
+aweme_info.desc
+aweme_info.author
+aweme_info.statistics
+aweme_info.create_time
+```
+
+字段用途：
+
+- `aweme_id`：视频作品 ID，用于后续评论抓取。
+- `desc`：视频标题或描述。
+- `author`：作者基础信息。
+- `statistics`：视频互动数据，如评论数、点赞数等。
+- `create_time`：视频发布时间。
+
+---
+
+## 5. 接口三：获取单个视频一级评论
+
+### 5.1 接口信息
+
+```http
+GET https://api.tikhub.io/api/v1/douyin/app/v3/fetch_video_comments
+```
+
+### 5.2 MVP 请求参数
+
+```text
+aweme_id=<视频 aweme_id>
+cursor=0
+count=20
+```
+
+参数含义：
+
+- `aweme_id`：视频作品 ID，来自视频搜索结果。
+- `cursor=0`：第一页评论。
+- `count=20`：按接口建议保持默认值。
+
+### 5.3 MVP 需要字段
+
+评论条目需要读取：
+
+```text
+cid / comment_id
+text
+user
+digg_count
+create_time
+```
+
+字段用途：
+
+- `cid` 或 `comment_id`：评论 ID，用于去重和关联。
+- `text`：评论正文。
+- `user`：评论作者基础信息。
+- `digg_count`：评论点赞数。
+- `create_time`：评论发布时间。
+
+---
+
+## 6. 已验证样例
+
+本次验证中，抖音链路已成功跑通以下样例：
+
+```text
+热点标题：2026年广州中考开考
+热点 query_id：2552790
+视频 aweme_id：7657020050364189986
+视频描述：15.1万名考生报名参加广州中考，广州首次启用智能安检门和无线电作弊防控设备
+评论 ID：7657143740201812773
+评论内容：湖南已放假，广东还在中考中。高考与中考不是全国统一的吗？
+```
+
+该样例证明：
+
+1. 可以获取抖音热点榜单。
+2. 可以基于热点标题搜索到相关视频。
+3. 可以从视频搜索结果中获取 `aweme_id`。
+4. 可以基于 `aweme_id` 获取视频一级评论。
+
+---
+
+## 7. MVP 开发结论
+
+抖音侧 MVP 抓取链路采用：
+
+```text
+热点榜单接口
+→ 热点标题关键词搜索视频
+→ 视频评论接口
+```
+
+开发阶段应将外部 API 字段映射设计为可调整结构，保留原始 JSON 响应，避免后续接口字段变化时影响核心数据追溯。
+
+MVP 阶段建议默认抓取规模：
+
+```text
+Top 5 热点
+× 每个热点最多 5 条视频
+× 每条视频最多 50 条一级评论
+```
+
+正式实现中应支持配置：
+
+```text
+hot_limit
+video_limit_per_hot
+comment_limit_per_video
+```
+
+---
+
+## 8. 后续文档衔接
+
+本 API Spike 结果用于支撑后续文档：
+
+1. `FeatureSummary.md`：拆解抖音抓取相关功能模块。
+2. `DevelopmentPlan.md`：设计后端服务、任务流程、数据模型和异常处理。
+3. `TDD`：围绕字段映射、分页、去重和任务状态编写测试。
+4. `Tasks`：拆分具体开发任务。