6cc703ada2
项目从单体结构重构为 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>
498 lines
29 KiB
Markdown
498 lines
29 KiB
Markdown
# Muse Creative Hotspots — 功能摘要
|
||
|
||
## 文档信息
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 版本 | v1.0 |
|
||
| 创建日期 | 2026-03-02 |
|
||
| 来源文档 | PRD.md |
|
||
|
||
## 1. 功能总览
|
||
|
||
### 1.1 功能统计
|
||
|
||
| 类别 | 数量 |
|
||
|------|------|
|
||
| 功能模块 | 5 个 |
|
||
<!-- MODIFIED: 原内容为 "P0: 10, P1: 5, P2: 1, 总计: 16"。F-007~F-009 升 P0，F-011 升 P0，新增 F-017(P1) -->
|
||
| 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. 提供收藏按钮 |
|
||
| **输出** | 站内详情页面 |
|
||
| **异常情况** | 详情数据加载失败 → 显示错误提示 + 重试按钮；原文链接失效 → 提示"原文可能已被删除" |
|
||
<!-- MODIFIED: 明确 video_url 的展示方式 -->
|
||
| **边界说明** | 不包含站内视频播放器（视频内容通过"查看原文"按钮跳转原平台播放，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 秒内忽略重复点击）；刷新中再次点击 → 忽略 |
|
||
<!-- MODIFIED: 标注单平台刷新为设计决策而非 PRD 约束 -->
|
||
| **边界说明** | 【设计决策】不包含单平台独立刷新（刷新所有已启用平台，PRD 未明确此约束，后续可按需调整）；手动刷新会重置自动刷新倒计时 |
|
||
|
||
---
|
||
|
||
### 2.3 模块 C — 收藏/书签系统
|
||
|
||
**模块职责**: 允许用户收藏感兴趣的内容，构建个人灵感库。
|
||
|
||
#### 功能列表
|
||
|
||
| ID | 功能 | 描述 | 优先级 | 关联场景 |
|
||
|----|------|------|--------|----------|
|
||
<!-- MODIFIED: 原内容为 "P1"，PRD MVP 验收标准要求"收藏功能可用"，升级为 P0 以匹配 MVP 纳入 -->
|
||
| 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 | - |
|
||
<!-- MODIFIED: 原内容为 "P1"，根据 PRD 第8节 MVP 验收标准"设置页可配置 API Key 和刷新间隔"升级为 P0 -->
|
||
| F-011 | 刷新间隔设置 | 自定义自动刷新频率 | P0 | US-001 |
|
||
| F-012 | 平台管理 | 启用/禁用各平台 | P1 | US-002 |
|
||
| F-013 | 展示数量设置 | 配置每平台默认展示数量 | P2 | US-003 |
|
||
<!-- NEW START -->
|
||
| F-017 | API 调用量统计 | 展示当日 API 调用次数及成本估算 | P1 | - |
|
||
<!-- NEW END -->
|
||
|
||
#### 功能契约详情
|
||
|
||
**F-010: API Key 配置**
|
||
|
||
| 契约项 | 说明 |
|
||
|--------|------|
|
||
| **触发条件** | 用户进入设置页面 |
|
||
| **输入** | 用户输入的 TikHub API Key 字符串 |
|
||
| **处理逻辑** | 1. 提供文本输入框供用户粘贴 API Key；2. 保存时验证 Key 格式（非空检查）；3. 存储到本地（加密或 env）；4. API 代理层读取此 Key 发起请求 |
|
||
| **输出** | API Key 保存成功/失败提示 |
|
||
<!-- MODIFIED: 原异常情况"Key 无效（API 返回 401）"与边界"保存时不测试连通性"矛盾，明确 401 在请求内容时触发 -->
|
||
| **异常情况** | Key 为空 → 提示必填；Key 无效 → 首次请求内容时 API 返回 401，引导用户检查 Key 配置 |
|
||
| **边界说明** | 保存时仅做非空校验，不测试 API 连通性（无效 Key 在实际请求时暴露）；不包含多 Key 轮换；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 的请求参数 |
|
||
| **输出** | 新的展示数量配置生效 |
|
||
| **异常情况** | 无特殊异常 |
|
||
| **边界说明** | 不支持每个平台独立设置不同数量（全局统一）；更改后需等待下次刷新才生效 |
|
||
|
||
<!-- NEW START -->
|
||
**F-017: API 调用量统计**
|
||
|
||
| 契约项 | 说明 |
|
||
|--------|------|
|
||
| **触发条件** | 用户进入设置页面或首页工具栏查看 |
|
||
| **输入** | API 代理层的请求计数器数据 |
|
||
| **处理逻辑** | 1. API 代理层（F-014）每次转发请求时累加计数器；2. 按日期维度统计调用次数；3. 根据 $0.001/请求 计算估算成本；4. 在设置页面或工具栏展示"今日调用: N 次（≈$X.XX）" |
|
||
| **输出** | 当日 API 调用次数 + 成本估算显示 |
|
||
| **异常情况** | 计数器数据丢失（页面刷新）→ 重新从 0 计数并提示"本次会话统计" |
|
||
| **边界说明** | 仅统计当前会话/当日数据，不做历史统计；计数存储于内存或 localStorage；成本为估算值，不保证与实际账单一致 |
|
||
<!-- NEW END -->
|
||
|
||
---
|
||
|
||
### 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. 功能依赖矩阵
|
||
|
||
<!-- MODIFIED: 修正 F-002/F-003 依赖方向；新增 F-017 行列 -->
|
||
| 功能 | 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 | 目标 |
|
||
|------|----------|--------|------|
|
||
<!-- MODIFIED: MVP 纳入 F-011；v1.1 纳入 F-017；v2.0 暗色模式无功能 ID 故移除描述 -->
|
||
| **MVP** | 3平台内容获取、卡片展示、筛选排序、详情页、自动/手动刷新、收藏系统、API Key配置、刷新间隔设置、API代理层 | F-001 ~ F-011, F-014 ~ F-016 | 跑通核心链路：抖音+TikTok+小红书热点聚合浏览 |
|
||
| **v1.1** | 平台管理、API调用量统计、新增5个P1平台适配器 | F-012, F-017 + P1平台适配 | 扩展至8个平台，完善运维功能 |
|
||
| **v2.0** | 展示数量设置、剩余9个P2平台适配器 | F-013 + P2平台适配 | 全平台覆盖17个平台 |
|
||
|
||
---
|
||
|
||
## 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[]` |
|
||
<!-- NEW START -->
|
||
| F-017 | API (GET) | `GET /api/stats` — 获取当日 API 调用次数及成本估算 |
|
||
<!-- NEW END -->
|
||
|
||
---
|
||
|
||
## 附录：用户场景映射
|
||
|
||
| 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 |
|