wxs 6cc703ada2 feat: monorepo 重构 + 新增 5 个平台适配器

项目从单体结构重构为 pnpm monorepo (shared/backend/frontend)，
新增 YouTube、Instagram、Twitter/X、哔哩哔哩、微博 5 个平台适配器，
包含完整的单元测试和 E2E 测试覆盖。

- 完成 T-031~T-044: 5 个适配器实现、注册、配置和测试
- 重构前后端分离: Hono 后端 + Next.js 前端
- 151 个单元测试 + 21 个 Mock E2E + 25 个真实 E2E
- 适配器基于真实 TikHub API 响应结构实现

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-03 15:43:25 +08:00

29 KiB

Raw Blame History

Muse Creative Hotspots — 功能摘要

文档信息

项目	内容
版本	v1.0
创建日期	2026-03-02
来源文档	PRD.md

1. 功能总览

1.1 功能统计

类别	数量
功能模块	5 个

| P0 功能 | 14 个 | | P1 功能 | 2 个 | | P2 功能 | 1 个 | | 功能总计 | 17 个 |

1.2 功能架构图

┌─────────────────────────────────────────────────────────────────────────────┐
│                       Muse Creative Hotspots（秒思创意热点）                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐          │
│  │ A. 热点内容聚合   │  │ B. 数据刷新管理   │  │ C. 收藏/书签系统  │          │
│  │ ──────────────── │  │ ──────────────── │  │ ──────────────── │          │
│  │ • F-001 内容获取  │  │ • F-005 自动刷新  │  │ • F-007 内容收藏  │          │
│  │ • F-002 卡片展示  │  │ • F-006 手动刷新  │  │ • F-008 收藏管理  │          │
│  │ • F-003 筛选排序  │  │                  │  │ • F-009 数据持久化 │          │
│  │ • F-004 详情页    │  │                  │  │                  │          │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘          │
│                                                                             │
│  ┌──────────────────┐  ┌──────────────────┐                                │
│  │ D. 设置管理       │  │ E. API 代理层     │                                │
│  │ ──────────────── │  │ ──────────────── │                                │
│  │ • F-010 Key配置   │  │ • F-014 请求代理  │                                │
│  │ • F-011 刷新间隔  │  │ • F-015 数据模型  │                                │
│  │ • F-012 平台管理  │  │ • F-016 平台适配  │                                │
│  │ • F-013 数量设置  │  │                  │                                │
│  │ • F-017 调用统计  │  │                  │                                │
│  └──────────────────┘  └──────────────────┘                                │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

1.3 模块依赖关系

┌──────────────────┐
│ E. API 代理层     │ ◀─── 所有数据请求的底层基础
│ F-014/F-015/F-016│
└───────┬──────────┘
        │ 被依赖
        ▼
┌──────────────────┐       ┌──────────────────┐
│ A. 热点内容聚合   │ ◀──── │ B. 数据刷新管理   │
│ F-001~F-004      │       │ F-005/F-006      │
└───────┬──────────┘       └──────────────────┘
        │ 被依赖                     ▲
        ▼                           │ 读取配置
┌──────────────────┐       ┌──────────────────┐
│ C. 收藏/书签系统  │       │ D. 设置管理       │
│ F-007~F-009      │       │ F-010~F-013      │
└──────────────────┘       └──────────────────┘
                                    │ 提供 API Key
                                    ▼
                           ┌──────────────────┐
                           │ E. API 代理层     │
                           └──────────────────┘

依赖说明：

模块 E 是基础设施层，模块 A/B 依赖其提供数据
模块 B 触发模块 A 的数据重新获取
模块 C 依赖模块 A 提供可收藏的内容
模块 D 为模块 B（刷新间隔）和模块 E（API Key）提供配置

2. 功能清单

2.1 模块 A — 热点内容聚合浏览

模块职责: 从各平台获取热点内容并以卡片信息流形式展示，支持筛选、排序和详情查看。

功能列表

ID	功能	描述	优先级	关联场景
F-001	内容获取	获取各平台官方热榜/推荐内容	P0	US-001/002/003
F-002	卡片信息流展示	瀑布流/网格卡片布局展示内容	P0	US-001/004
F-003	内容筛选与排序	按平台切换、按数据指标排序	P0	US-002/003
F-004	内容详情页	站内详情页展示完整内容信息	P0	US-001/003/004

功能契约详情

F-001: 内容获取

契约项	说明
触发条件	1. 页面首次加载；2. 自动定时刷新触发；3. 手动点击刷新按钮；4. 切换平台 Tab
输入	平台标识（platform）、展示数量（count，默认 20-50）、API Key（从设置读取）
处理逻辑	1. 通过 API 代理层调用 TikHub 对应平台端点；2. 适配器将原始数据转换为统一 ContentItem；3. 缓存结果供前端展示
输出	ContentItem[] 数组，包含 title、cover_url、author_name、play_count、like_count 等标准字段
异常情况	API Key 无效 → 提示配置；请求超时 → 显示重试按钮；频率超限（10 req/s）→ 排队等待；平台未启用 → 跳过
边界说明	不包含内容的全文/完整视频获取；不做内容缓存持久化（刷新后替换）；不支持分页加载更多

F-002: 卡片信息流展示

契约项	说明
触发条件	内容数据加载完成（F-001 返回结果）
输入	ContentItem[] 数组
处理逻辑	1. 按瀑布流/网格布局渲染卡片；2. 每张卡片展示：封面图/缩略图、标题（截断）、平台图标+名称、关键数据（播放量/点赞/评论/分享）、发布时间、作者头像+昵称；3. 支持 hover 预览更多信息
输出	可视化的卡片网格界面
异常情况	封面图加载失败 → 显示占位图；数据为空 → 显示空状态提示
边界说明	不包含视频内联播放；不包含无限滚动（展示固定 Top N）；卡片内标题截断展示，完整内容在详情页

F-003: 内容筛选与排序

契约项	说明
触发条件	用户点击平台 Tab 切换或选择排序方式
输入	筛选条件：platform（平台标识 / "all"）；排序条件：sortBy（play_count / like_count / comment_count / publish_time）+ sortOrder（asc / desc）
处理逻辑	1. 按平台筛选：切换 Tab 时过滤或重新请求对应平台数据；2. 按指标排序：前端对当前列表重新排序；3. "全部"视图聚合所有已启用平台的内容
输出	重新排列后的 ContentItem[] → 更新卡片信息流
异常情况	某平台数据为空 → Tab 上标注"暂无数据"；排序字段缺失 → 该条目排到末尾
边界说明	不包含关键词搜索功能；不包含多条件组合筛选；排序为前端内存排序，不重新请求 API

F-004: 内容详情页

契约项	说明
触发条件	用户点击内容卡片
输入	ContentItem 的完整数据（或 contentId + platform 用于请求详情 API）
处理逻辑	1. 展示完整内容信息（标题、描述、标签）；2. 展示完整数据指标面板（播放/点赞/评论/分享）；3. 展示作者信息（头像+昵称）；4. 提供"查看原文"按钮（跳转原平台页面）；5. 提供收藏按钮
输出	站内详情页面
异常情况	详情数据加载失败 → 显示错误提示 + 重试按钮；原文链接失效 → 提示"原文可能已被删除"

| 边界说明 | 不包含站内视频播放器（视频内容通过"查看原文"按钮跳转原平台播放，video_url 不直接嵌入播放）；不包含评论区展示；不包含相关推荐 |

2.2 模块 B — 数据刷新管理

模块职责: 管理内容数据的自动定时刷新和手动触发刷新机制。

功能列表

ID	功能	描述	优先级	关联场景
F-005	自动定时刷新	按设定间隔自动获取最新内容	P0	US-001/002
F-006	手动刷新	用户点击按钮立即刷新内容	P0	US-001/002

功能契约详情

F-005: 自动定时刷新

契约项	说明
触发条件	页面加载后自动启动定时器
输入	刷新间隔（从设置读取，默认 30 分钟）
处理逻辑	1. 启动定时器（setInterval / TanStack Query refetchInterval）；2. 到达间隔时间后自动调用 F-001 重新获取所有已启用平台的内容；3. 刷新时更新"上次刷新时间"显示
输出	更新后的内容列表 + 更新刷新时间戳
异常情况	刷新失败 → 保留上一次数据，显示刷新失败提示；页面后台（不可见）→ 暂停刷新节省 API 调用
边界说明	不包含增量更新（每次全量替换）；不包含推送通知新内容；最小间隔限制 5 分钟（防止 API 滥用）

F-006: 手动刷新

契约项	说明
触发条件	用户点击工具栏刷新按钮 🔄
输入	当前选中平台（或"全部"）
处理逻辑	1. 触发 F-001 重新获取内容；2. 刷新按钮显示 loading 状态；3. 完成后重置自动刷新计时器；4. 更新"上次刷新时间"
输出	更新后的内容列表 + loading 状态反馈
异常情况	连续快速点击 → 防抖处理（2 秒内忽略重复点击）；刷新中再次点击 → 忽略

| 边界说明 | 【设计决策】不包含单平台独立刷新（刷新所有已启用平台，PRD 未明确此约束，后续可按需调整）；手动刷新会重置自动刷新倒计时 |

2.3 模块 C — 收藏/书签系统

模块职责: 允许用户收藏感兴趣的内容，构建个人灵感库。

功能列表

ID	功能	描述	优先级	关联场景

| F-007 | 内容收藏 | 将任意内容卡片添加到收藏夹 | P0 | US-001/004 | | F-008 | 收藏夹管理 | 独立页面查看和管理收藏内容 | P0 | US-004 | | F-009 | 收藏数据持久化 | 收藏数据本地持久化存储 | P0 | US-004 |

功能契约详情

F-007: 内容收藏

契约项	说明
触发条件	用户在卡片上或详情页中点击收藏按钮
输入	ContentItem 完整数据
处理逻辑	1. 检查是否已收藏（防重复）；2. 已收藏 → 取消收藏；未收藏 → 添加到收藏列表；3. 更新收藏按钮状态（实心/空心）；4. 触发 F-009 持久化存储
输出	收藏状态变更 + 视觉反馈（按钮状态切换）
异常情况	存储空间不足 → 提示清理旧收藏
边界说明	不包含收藏分类/文件夹功能；不包含收藏备注；不包含收藏分享

F-008: 收藏夹管理

契约项	说明
触发条件	用户点击导航中的"收藏"入口
输入	本地存储的收藏列表
处理逻辑	1. 从本地存储读取收藏列表；2. 以卡片网格形式展示所有收藏内容；3. 支持取消收藏（删除）；4. 点击卡片可跳转详情页
输出	收藏内容列表页面
异常情况	收藏为空 → 显示空状态引导
边界说明	不包含收藏搜索；不包含收藏排序；不包含收藏导出；MVP 阶段不支持云同步

F-009: 收藏数据持久化

契约项	说明
触发条件	收藏列表发生变更（添加/删除）
输入	完整的收藏列表数据
处理逻辑	1. 使用 Zustand persist 中间件；2. 将收藏数据序列化存储到 localStorage；3. 页面加载时自动恢复收藏状态
输出	持久化的收藏数据
异常情况	localStorage 不可用 → 降级为内存存储（关闭页面丢失）；数据损坏 → 重置收藏列表并提示
边界说明	MVP 仅支持 localStorage，不包含 IndexedDB；不包含数据库后端存储；不包含跨设备同步

2.4 模块 D — 设置管理

模块职责: 提供应用配置界面，允许用户自定义 API 认证、刷新策略和平台偏好。

功能列表

ID	功能	描述	优先级	关联场景
F-010	API Key 配置	配置 TikHub API Key	P0	-

| F-011 | 刷新间隔设置 | 自定义自动刷新频率 | P0 | US-001 | | F-012 | 平台管理 | 启用/禁用各平台 | P1 | US-002 | | F-013 | 展示数量设置 | 配置每平台默认展示数量 | P2 | US-003 |

| F-017 | API 调用量统计 | 展示当日 API 调用次数及成本估算 | P1 | - |

功能契约详情

F-010: API Key 配置

契约项	说明
触发条件	用户进入设置页面
输入	用户输入的 TikHub API Key 字符串
处理逻辑	1. 提供文本输入框供用户粘贴 API Key；2. 保存时验证 Key 格式（非空检查）；3. 存储到本地（加密或 env）；4. API 代理层读取此 Key 发起请求
输出	API Key 保存成功/失败提示

F-011: 刷新间隔设置

契约项	说明
触发条件	用户在设置页面调整刷新间隔
输入	刷新间隔值（分钟），可选范围：5 / 10 / 15 / 30 / 60
处理逻辑	1. 提供下拉选择或滑块控件；2. 保存后立即更新 F-005 的定时器间隔；3. 持久化存储设置
输出	新的刷新间隔生效
异常情况	无特殊异常
边界说明	最小 5 分钟（API 成本控制）；不支持自定义任意分钟数

F-012: 平台管理

契约项	说明
触发条件	用户在设置页面切换平台开关
输入	平台标识 + 启用/禁用状态
处理逻辑	1. 展示所有支持的平台列表，每个平台配有开关；2. 切换开关后持久化设置；3. 禁用的平台不再出现在首页 Tab 栏中；4. 禁用平台的数据不再自动刷新
输出	平台启用状态更新
异常情况	至少保留一个平台启用 → 否则提示
边界说明	不包含平台顺序自定义；不包含自定义添加新平台

F-013: 展示数量设置

契约项	说明
触发条件	用户在设置页面调整展示数量
输入	每平台展示数量（默认 20，可选 10 / 20 / 30 / 50）
处理逻辑	1. 提供数量选择控件；2. 保存后下次刷新时按新数量请求；3. 影响 F-001 的请求参数
输出	新的展示数量配置生效
异常情况	无特殊异常
边界说明	不支持每个平台独立设置不同数量（全局统一）；更改后需等待下次刷新才生效

F-017: API 调用量统计

契约项	说明
触发条件	用户进入设置页面或首页工具栏查看
输入	API 代理层的请求计数器数据
处理逻辑	1. API 代理层（F-014）每次转发请求时累加计数器；2. 按日期维度统计调用次数；3. 根据 $0.001/请求计算估算成本；4. 在设置页面或工具栏展示"今日调用: N 次（≈$X.XX）"
输出	当日 API 调用次数 + 成本估算显示
异常情况	计数器数据丢失（页面刷新）→ 重新从 0 计数并提示"本次会话统计"
边界说明	仅统计当前会话/当日数据，不做历史统计；计数存储于内存或 localStorage；成本为估算值，不保证与实际账单一致

2.5 模块 E — API 代理层

模块职责: 通过 Next.js API Routes 代理 TikHub 请求，隐藏 API Key 并统一数据格式。

功能列表

ID	功能	描述	优先级	关联场景
F-014	API 请求代理	通过服务端代理 TikHub API 请求	P0	-
F-015	统一数据模型	所有平台数据映射为 ContentItem	P0	-
F-016	平台适配器	各平台 API 调用与数据格式转换	P0	-

功能契约详情

F-014: API 请求代理

契约项	说明
触发条件	前端发起内容获取请求
输入	平台标识、请求类型（热榜/详情）、请求参数
处理逻辑	1. Next.js API Route 接收前端请求；2. 从环境变量/设置读取 API Key；3. 构建 TikHub API 请求（Bearer Token 认证）；4. 转发请求并返回结果；5. 遵守 10 req/s 频率限制
输出	TikHub API 原始响应数据
异常情况	API Key 未配置 → 返回 401 + 提示配置；TikHub 返回错误 → 透传错误信息；请求超时 → 返回超时错误；频率超限 → 排队或返回 429
边界说明	不包含响应缓存（由 TanStack Query 在前端处理）；不包含请求日志记录；代理层仅做转发，不做业务逻辑

F-015: 统一数据模型

契约项	说明
触发条件	适配器处理 API 响应时
输入	各平台原始 API 响应数据
处理逻辑	定义统一 ContentItem 类型，包含：title、cover_url、video_url、author_name、author_avatar、play_count、like_count、comment_count、share_count、publish_time、platform、original_url、tags
输出	标准化的 ContentItem 对象
异常情况	必填字段缺失 → 使用默认值（如"未知作者"）；数据类型不匹配 → 类型转换或置空
边界说明	ContentItem 为只读展示模型，不包含编辑能力；字段定义以 PRD 4.3 为准

F-016: 平台适配器

契约项	说明
触发条件	F-001 调用内容获取时
输入	平台标识 + API 原始响应
处理逻辑	1. 根据平台标识选择对应适配器；2. 适配器调用平台特定的 TikHub API 端点；3. 将原始响应字段映射为 ContentItem（参照 PRD 中各平台的字段映射规则）；4. MVP 实现抖音/TikTok/小红书三个适配器
输出	ContentItem[] 标准化数组
异常情况	平台无适配器 → 返回空数组 + 日志警告；API 端点变更 → 适配器更新
边界说明	每个适配器独立实现，互不影响；新增平台只需新增适配器，无需修改已有代码

3. 功能依赖矩阵

功能	F-001	F-002	F-003	F-004	F-005	F-006	F-007	F-008	F-009	F-010	F-011	F-012	F-013	F-014	F-015	F-016	F-017
F-001 内容获取	-											✓	✓	✓	✓	✓
F-002 卡片展示	✓	-	✓
F-003 筛选排序	✓		-
F-004 详情页	✓			-										✓	✓	✓
F-005 自动刷新	✓				-						✓
F-006 手动刷新	✓					-
F-007 内容收藏	✓						-		✓
F-008 收藏管理								-	✓
F-009 数据持久化									-
F-010 Key配置										-
F-011 刷新间隔											-
F-012 平台管理												-
F-013 数量设置													-
F-014 请求代理										✓				-
F-015 数据模型															-
F-016 平台适配														✓	✓	-
F-017 调用统计														✓			-

说明：

✓ 表示行功能依赖列功能
空白表示无依赖
- 表示自身

4. 功能流程图

4.1 核心流程：内容浏览主流程

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│ F-010    │ ──▶ │ F-014    │ ──▶ │ F-016    │ ──▶ │ F-015    │ ──▶ │ F-001    │
│ Key配置  │     │ 请求代理  │     │ 平台适配  │     │ 数据模型  │     │ 内容获取  │
└──────────┘     └──────────┘     └──────────┘     └──────────┘     └─────┬────┘
                                                                          │
                      ┌───────────────────────────────────────────────────┘
                      ▼
                ┌──────────┐     ┌──────────┐     ┌──────────┐
                │ F-002    │ ──▶ │ F-003    │ ──▶ │ F-004    │
                │ 卡片展示  │     │ 筛选排序  │     │ 详情页   │
                └──────────┘     └──────────┘     └──────────┘

4.2 数据刷新流程

┌──────────────────────────────────────────────────────────┐
│                    刷新触发                                │
│  ┌──────────┐           ┌──────────┐                     │
│  │ F-005    │           │ F-006    │                     │
│  │ 自动刷新  │           │ 手动刷新  │                     │
│  │ (定时器)  │           │ (按钮)   │                     │
│  └────┬─────┘           └────┬─────┘                     │
│       │                      │                           │
│       └──────────┬───────────┘                           │
│                  ▼                                        │
│           ┌──────────┐     ┌──────────┐                  │
│           │ F-001    │ ──▶ │ F-002    │                  │
│           │ 内容获取  │     │ 更新展示  │                  │
│           └────┬─────┘     └──────────┘                  │
│                │                                          │
│                ▼ 失败                                     │
│         ┌────────────┐                                    │
│         │ 保留旧数据  │                                    │
│         │ 显示错误提示│                                    │
│         └────────────┘                                    │
└──────────────────────────────────────────────────────────┘

4.3 收藏流程

┌──────────┐     ┌──────────┐     ┌──────────┐
│ F-002    │ ──▶ │ F-007    │ ──▶ │ F-009    │
│ 卡片展示  │     │ 点击收藏  │     │ 持久化   │
└──────────┘     └──────────┘     └──────────┘
      或                               │
┌──────────┐                           ▼
│ F-004    │ ──▶ (同上)          ┌──────────┐
│ 详情页   │                     │ F-008    │
└──────────┘                     │ 收藏管理  │
                                 └──────────┘

5. 版本规划

版本	包含功能	功能ID	目标

6. 接口契约预览

详细接口定义在 DevelopmentPlan 中，此处仅列出关键接口

功能	接口类型	简要说明
F-001	API (GET)	`GET /api/tikhub/[platform]` — 获取指定平台热榜内容
F-004	API (GET)	`GET /api/tikhub/[platform]/detail?id=xxx` — 获取内容详情
F-005	Event	TanStack Query `refetchInterval` 定时触发
F-006	Event	用户点击 → `queryClient.invalidateQueries()`
F-007	Store	Zustand `useFavoritesStore.addFavorite(item)`
F-009	Storage	Zustand persist → localStorage
F-010	API (POST)	`POST /api/settings` — 保存 API Key
F-014	API (Proxy)	Next.js API Route → TikHub API（Bearer Token）
F-016	Module	`PlatformAdapter.fetchTrending(platform)` → `ContentItem[]`

| F-017 | API (GET) | GET /api/stats — 获取当日 API 调用次数及成本估算 |

附录：用户场景映射

ID	场景	描述	关联功能
US-001	创意灵感获取	每天浏览各平台热点趋势，发现创意表达和内容形式	F-001~F-006
US-002	竞品/行业监控	跟踪特定领域在各平台的热门内容表现	F-001, F-003, F-005, F-006, F-012
US-003	数据分析研究	对比同类内容在不同平台的数据差异	F-001, F-003, F-004, F-013
US-004	内容搬运/分发	发现优质内容后进行跨平台二次创作	F-002, F-004, F-007, F-008

29 KiB Raw Blame History Unescape Escape

Muse Creative Hotspots — 功能摘要

文档信息

1. 功能总览

1.1 功能统计

1.2 功能架构图

1.3 模块依赖关系

2. 功能清单

2.1 模块 A — 热点内容聚合浏览

功能列表

功能契约详情

2.2 模块 B — 数据刷新管理

功能列表

功能契约详情

2.3 模块 C — 收藏/书签系统

功能列表

功能契约详情

2.4 模块 D — 设置管理

功能列表

功能契约详情

2.5 模块 E — API 代理层

功能列表

功能契约详情

3. 功能依赖矩阵

4. 功能流程图

4.1 核心流程：内容浏览主流程

4.2 数据刷新流程

4.3 收藏流程

5. 版本规划

6. 接口契约预览

附录：用户场景映射

29 KiB

Raw Blame History