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>
62 KiB
62 KiB
Muse Creative Hotspots — UI 设计文档
文档信息
| 项目 | 内容 |
|---|---|
| 版本 | v1.0 |
| 创建日期 | 2026-03-02 |
| 来源文档 | DevelopmentPlan.md, FeatureSummary.md, PRD.md |
1. 设计概述
1.1 设计原则
| 原则 | 说明 |
|---|---|
| 简约现代 | 参考 Notion/Linear 风格，大量留白，信息层次清晰 |
| 内容优先 | 卡片封面图和数据指标是核心，UI 元素不喧宾夺主 |
| 平台可识别 | 平台图标采用官方配色，用户可快速辨别内容来源 |
| 状态完备 | 每个页面覆盖默认、加载中、空状态、错误四种状态 |
| 响应式 | 桌面端优先，CSS Grid 自适应屏幕宽度 |
1.2 页面总览
| 页面ID | 页面名称 | 路由 | 描述 | 对应功能 | 优先级 |
|---|---|---|---|---|---|
| P-001 | 首页 | / |
热点内容卡片信息流，含平台 Tab、排序、刷新 | F-001, F-002, F-003, F-005, F-006 | P0 |
| P-002 | 详情页 | /detail/[platform]/[id] |
单条内容完整信息展示 | F-004, F-007 | P0 |
| P-003 | 收藏夹 | /favorites |
已收藏内容的网格展示与管理 | F-007, F-008, F-009 | P0 |
| P-004 | 设置页 | /settings |
API Key 配置、刷新间隔设置 | F-010, F-011 | P0 |
1.3 页面导航图
┌──────────────────┐
│ P-001 │
│ 首页 │
│ (默认入口页面) │
└───────┬──────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ P-002 │ │ P-003 │ │ P-004 │
│ 详情页 │ │ 收藏夹 │ │ 设置页 │
│ 点击卡片进入 │ │ Header导航进入 │ │ Header ⚙ 进入 │
└────────┬───────┘ └────────┬───────┘ └────────────────┘
│ │
│ ┌─────────────┘
│ │ 点击收藏卡片
▼ ▼
┌────────────────┐
│ P-002 │
│ 详情页(复用) │
└────────────────┘
导航说明:
- Header 常驻所有页面，提供全局导航（Logo 回首页、收藏夹入口、设置入口）
- 首页 → 详情页：点击任意内容卡片
- 首页 → 收藏夹：点击 Header 收藏入口
- 首页 → 设置页：点击 Header ⚙ 图标
- 收藏夹 → 详情页：点击收藏的内容卡片
- 详情页 → 返回上一页：浏览器 Back / 返回按钮
2. 页面设计
2.1 P-001: 首页
页面信息
| 属性 | 值 |
|---|---|
| 页面ID | P-001 |
| 路由 | / |
| 对应功能 | F-001, F-002, F-003, F-005, F-006 |
| 入口 | 应用默认页面；Header Logo 点击 |
| 出口 | P-002（点击卡片）、P-003（Header 收藏）、P-004（Header 设置） |
页面布局 — ASCII 原型图
┌──────────────────────────────────────────────────────────────────────────┐
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Header │ │
│ │ │ │
│ │ Muse [全部] [抖音] [TikTok] [小红书] [♡ 收藏] [⚙] │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────────────────────────┤
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Toolbar │ │
│ │ │ │
│ │ 排序: [▼ 播放量] [↓ 降序] [🔄 刷新] 上次: 10:30 │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │
│ │ │ 封面图 │ │ │ │ 封面图 │ │ │ │ 封面图 │ │ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │
│ │ └─────────────┘ │ │ └─────────────┘ │ │ └─────────────┘ │ │
│ │ │ │ │ │ │ │
│ │ 📱 抖音 │ │ 🎵 TikTok │ │ 📕 小红书 │ │
│ │ 标题文字截断展 │ │ Title text tr.. │ │ 标题文字截断展 │ │
│ │ 示最多两行... │ │ uncated to two.. │ │ 示最多两行... │ │
│ │ │ │ │ │ │ │
│ │ 👤 作者昵称 │ │ 👤 Author Name │ │ 👤 作者昵称 │ │
│ │ ▶1.2M ❤5.3K │ │ ▶800K ❤3.1K │ │ ❤2.1K 💬156 │ │
│ │ 💬 203 [♡] │ │ 💬 150 [♡] │ │ [♡] │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │
│ │ │ 封面图 │ │ │ │ 封面图 │ │ │ │ 封面图 │ │ │
│ │ └─────────────┘ │ │ └─────────────┘ │ │ └─────────────┘ │ │
│ │ 📱 抖音 │ │ 📕 小红书 │ │ 🎵 TikTok │ │
│ │ 标题文字... │ │ 标题文字... │ │ Title text... │ │
│ │ 👤 作者 ▶ ❤ 💬 │ │ 👤 作者 ❤ 💬 │ │ 👤 Author ▶ ❤ │ │
│ │ [♡] │ │ [♡] │ │ [♡] │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ ... 更多卡片 ... │
│ │
└──────────────────────────────────────────────────────────────────────────┘
组件清单
| 组件ID | 组件名称 | 类型 | 说明 | 交互 |
|---|---|---|---|---|
| C-001 | Header | 导航栏 | 顶部固定，含 Logo、平台 Tab、收藏入口、设置入口 | Logo 回首页；Tab 切换平台 |
| C-002 | PlatformTabs | Tab 栏 | Header 内嵌，展示"全部"+各平台 Tab | 点击切换平台，触发数据重新获取 |
| C-003 | SortToolbar | 工具栏 | 排序选择器 + 排序方向 + 刷新按钮 + 上次刷新时间 | 选择排序字段/方向；点击刷新 |
| C-004 | ContentCard | 卡片 | 单条内容：封面图、平台标识、标题、作者、数据指标、收藏按钮 | 点击进入详情页；点击 ♡ 收藏 |
| C-005 | ContentGrid | 网格容器 | CSS Grid 响应式网格 repeat(auto-fill, minmax(280px, 1fr)) |
- |
| C-006 | CardSkeleton | 骨架屏 | 数据加载时的占位动画 | - |
| C-008 | FavoriteButton | 收藏按钮 | 卡片右下角，♡ 空心/♥ 实心切换 | 点击切换收藏状态 |
交互说明
| 触发 | 动作 | 结果 |
|---|---|---|
| 点击平台 Tab | 切换 queryKey | 重新获取对应平台数据，"全部"聚合所有平台 |
| 选择排序字段/方向 | 前端内存排序（useMemo） | 卡片网格重新排列，不请求 API |
| 点击刷新按钮 | invalidateQueries + 重置自动刷新计时器 | 按钮显示 loading 旋转，完成后更新"上次刷新"时间 |
| 点击卡片（非收藏按钮区域） | 路由跳转 | 进入 /detail/[platform]/[id] 详情页 |
| 点击卡片收藏按钮 ♡ | Zustand addFavorite/removeFavorite | ♡ ↔ ♥ 状态切换，数据持久化到 localStorage |
| 自动定时刷新 | refetchInterval 触发 | 静默刷新数据，更新"上次刷新"时间 |
| 页面不可见（切换 Tab） | 暂停自动刷新 | 节省 API 调用 |
页面状态
| 状态 | 说明 | 展示 |
|---|---|---|
| 默认 | 数据加载完成 | 卡片网格正常展示 |
| 加载中 | 首次加载或切换平台 | 骨架屏（CardSkeleton x N） |
| 刷新中 | 手动/自动刷新 | 刷新按钮旋转，保留当前卡片 |
| 空状态 | 平台无数据返回 | 空状态组件 + "暂无热点内容" |
| 错误 — API Key 未配置 | 未设置 API Key | 引导提示 + "去配置" 按钮跳转设置页 |
| 错误 — 请求失败 | 网络/服务端错误 | 错误提示 + "重试" 按钮 |
| 错误 — 频率超限 | 429 响应 | 提示"请求过于频繁，请稍后重试" |
加载态原型
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │
│ │░░░░░░░░░░░░░│ │ │ │░░░░░░░░░░░░░│ │ │ │░░░░░░░░░░░░░│ │
│ │░░░░░░░░░░░░░│ │ │ │░░░░░░░░░░░░░│ │ │ │░░░░░░░░░░░░░│ │
│ │░░░░░░░░░░░░░│ │ │ │░░░░░░░░░░░░░│ │ │ │░░░░░░░░░░░░░│ │
│ └─────────────┘ │ │ └─────────────┘ │ │ └─────────────┘ │
│ ░░░░░░ │ │ ░░░░░░ │ │ ░░░░░░ │
│ ░░░░░░░░░░░░░░ │ │ ░░░░░░░░░░░░░░ │ │ ░░░░░░░░░░░░░░ │
│ ░░░░░░░░░░ │ │ ░░░░░░░░░░ │ │ ░░░░░░░░░░ │
│ ░░░░ ░░░░ ░░░░ │ │ ░░░░ ░░░░ ░░░░ │ │ ░░░░ ░░░░ ░░░░ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
空状态原型
┌──────────────────────────────────────────────────────────┐
│ │
│ ┌──────────┐ │
│ │ 📭 │ │
│ └──────────┘ │
│ │
│ 暂无热点内容 │
│ 当前平台暂时没有热门内容 │
│ │
│ [🔄 刷新试试] │
│ │
└──────────────────────────────────────────────────────────┘
API Key 未配置引导原型
┌──────────────────────────────────────────────────────────┐
│ │
│ ┌──────────┐ │
│ │ 🔑 │ │
│ └──────────┘ │
│ │
│ 请先配置 API Key │
│ 需要配置 TikHub API Key 才能获取内容 │
│ │
│ [⚙ 前往设置] │
│ │
└──────────────────────────────────────────────────────────┘
2.2 P-002: 详情页
页面信息
| 属性 | 值 |
|---|---|
| 页面ID | P-002 |
| 路由 | /detail/[platform]/[id] |
| 对应功能 | F-004, F-007 |
| 入口 | P-001（点击卡片）、P-003（点击收藏卡片） |
| 出口 | 返回上一页；外部跳转（查看原文） |
页面布局 — ASCII 原型图
┌──────────────────────────────────────────────────────────────────────────┐
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Header（同首页 C-001） │ │
│ └────────────────────────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ [← 返回] [♡ 收藏] │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌──────────────────────────────────────────┐ ┌──────────────┐ │ │
│ │ │ │ │ │ │ │
│ │ │ │ │ 平台信息 │ │ │
│ │ │ │ │ │ │ │
│ │ │ 封面图 │ │ 📱 抖音 │ │ │
│ │ │ (大图展示) │ │ │ │ │
│ │ │ │ │ 发布时间 │ │ │
│ │ │ │ │ 2026-03-01 │ │ │
│ │ │ │ │ 14:30 │ │ │
│ │ │ │ │ │ │ │
│ │ └──────────────────────────────────────────┘ └──────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ │ 内容标题（完整展示，不截断） │ │ │
│ │ └──────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ │ 作者信息 │ │ │
│ │ │ ┌────┐ │ │ │
│ │ │ │头像│ 作者昵称 │ │ │
│ │ │ └────┘ │ │ │
│ │ └──────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ │ 数据指标面板 │ │ │
│ │ │ │ │ │
│ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │
│ │ │ │ ▶ 播放量 │ │ ❤ 点赞 │ │ 💬 评论 │ │ ↗ 分享 │ │ │ │
│ │ │ │ 1,234,567│ │ 53,210 │ │ 2,031 │ │ 8,456 │ │ │ │
│ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │
│ │ │ │ │ │
│ │ └──────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ │ 标签 │ │ │
│ │ │ [#热门话题] [#创意] [#内容创作] │ │ │
│ │ └──────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ │ [🔗 查看原文] │ │ │
│ │ └──────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────┘
组件清单
| 组件ID | 组件名称 | 类型 | 说明 | 交互 |
|---|---|---|---|---|
| C-001 | Header | 导航栏 | 复用全局 Header | 同首页 |
| C-007 | DetailPanel | 信息面板 | 封面大图 + 标题 + 作者 + 数据指标 + 标签 | - |
| C-008 | FavoriteButton | 收藏按钮 | 右上角，大号 ♡/♥ | 点击切换收藏 |
交互说明
| 触发 | 动作 | 结果 |
|---|---|---|
| 点击 [← 返回] | 路由 back | 返回上一页面（首页或收藏夹） |
| 点击 [♡ 收藏] | Zustand toggle | 收藏状态切换 |
| 点击 [🔗 查看原文] | window.open | 新窗口打开原平台页面 |
| 封面图加载失败 | 显示占位图 | 灰色占位 + 平台图标 |
页面状态
| 状态 | 说明 | 展示 |
|---|---|---|
| 默认 | 详情数据加载完成 | 完整信息面板 |
| 加载中 | 请求详情 API | 骨架屏（大图区域 + 文字行） |
| 错误 | 详情加载失败 | 错误提示 + "重试" + "返回首页" 按钮 |
错误态原型
┌────────────────────────────────────────────────────────────┐
│ [← 返回] │
│ │
│ │
│ ┌──────────┐ │
│ │ ⚠️ │ │
│ └──────────┘ │
│ │
│ 内容加载失败 │
│ 请检查网络连接或稍后重试 │
│ │
│ [🔄 重试] [🏠 返回首页] │
│ │
│ │
└────────────────────────────────────────────────────────────┘
加载态原型
┌────────────────────────────────────────────────────────────┐
│ [← 返回] │
│ │
│ ┌──────────────────────────────────┐ ┌──────────────┐ │
│ │░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░░│ │
│ │░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░░│ │
│ │░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│ │░░░░░░░░░░░░░░│ │
│ │░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│ └──────────────┘ │
│ └──────────────────────────────────┘ │
│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
│ ░░░░ ░░░░░░░░░░░ │
│ ░░░░░░░░░░ ░░░░░░░░░░ ░░░░░░░░░░ ░░░░░░░░░░ │
│ ░░░░░░░░░ ░░░░░░ ░░░░░░░ │
└────────────────────────────────────────────────────────────┘
2.3 P-003: 收藏夹页面
页面信息
| 属性 | 值 |
|---|---|
| 页面ID | P-003 |
| 路由 | /favorites |
| 对应功能 | F-007, F-008, F-009 |
| 入口 | Header 收藏入口 |
| 出口 | P-002（点击卡片）；Header 导航至其他页面 |
页面布局 — ASCII 原型图
┌──────────────────────────────────────────────────────────────────────────┐
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Header（同首页 C-001） │ │
│ └────────────────────────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 我的收藏 共 12 条 │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │
│ │ │ 封面图 │ │ │ │ 封面图 │ │ │ │ 封面图 │ │ │
│ │ └─────────────┘ │ │ └─────────────┘ │ │ └─────────────┘ │ │
│ │ 📱 抖音 │ │ 🎵 TikTok │ │ 📕 小红书 │ │
│ │ 标题文字... │ │ Title text... │ │ 标题文字... │ │
│ │ 👤 作者 │ │ 👤 Author │ │ 👤 作者 │ │
│ │ ▶1.2M ❤5.3K │ │ ▶800K ❤3.1K │ │ ❤2.1K 💬156 │ │
│ │ [♥] │ │ [♥] │ │ [♥] │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │
│ │ │ 封面图 │ │ │ │ 封面图 │ │ │
│ │ └─────────────┘ │ │ └─────────────┘ │ │
│ │ ... │ │ ... │ │
│ │ [♥] │ │ [♥] │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────┘
组件清单
| 组件ID | 组件名称 | 类型 | 说明 | 交互 |
|---|---|---|---|---|
| C-001 | Header | 导航栏 | 复用全局 Header | 同首页 |
| C-005 | ContentGrid | 网格容器 | 复用首页网格布局 | - |
| C-004 | ContentCard | 卡片 | 复用首页卡片，收藏按钮为实心 ♥ | 点击进入详情；点击 ♥ 取消收藏 |
交互说明
| 触发 | 动作 | 结果 |
|---|---|---|
| 点击卡片 | 路由跳转 | 进入 /detail/[platform]/[id] |
| 点击 ♥ 取消收藏 | Zustand removeFavorite | 卡片从列表移除 |
页面状态
| 状态 | 说明 | 展示 |
|---|---|---|
| 默认 | 有收藏内容 | 卡片网格展示 |
| 空状态 | 无收藏内容 | 空状态引导 |
空状态原型
┌──────────────────────────────────────────────────────────┐
│ │
│ ┌──────────┐ │
│ │ ♡ │ │
│ └──────────┘ │
│ │
│ 还没有收藏内容 │
│ 浏览热点内容时，点击 ♡ 收藏感兴趣的内容 │
│ │
│ [去浏览热点] │
│ │
└──────────────────────────────────────────────────────────┘
2.4 P-004: 设置页面
页面信息
| 属性 | 值 |
|---|---|
| 页面ID | P-004 |
| 路由 | /settings |
| 对应功能 | F-010, F-011 |
| 入口 | Header ⚙ 图标 |
| 出口 | Header 导航至其他页面 |
页面布局 — ASCII 原型图
┌──────────────────────────────────────────────────────────────────────────┐
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Header（同首页 C-001） │ │
│ └────────────────────────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 设置 │ │
│ │ │ │
│ │ ─────────────────────────────────────────────── │ │
│ │ │ │
│ │ API 配置 │ │
│ │ │ │
│ │ TikHub API Key │ │
│ │ ┌──────────────────────────────────────────┐ │ │
│ │ │ sk-xxxxxxxxxxxxxxxxxxxx │ │ │
│ │ └──────────────────────────────────────────┘ │ │
│ │ API Key 保存在服务端，不会暴露到浏览器。 │ │
│ │ 优先使用 .env.local 中的预配置值。 │ │
│ │ │ │
│ │ [保存 API Key] │ │
│ │ │ │
│ │ ─────────────────────────────────────────────── │ │
│ │ │ │
│ │ 刷新设置 │ │
│ │ │ │
│ │ 自动刷新间隔 │ │
│ │ ┌──────────────────────────────────────────┐ │ │
│ │ │ 30 分钟 ▼ │ │ │
│ │ └──────────────────────────────────────────┘ │ │
│ │ 可选: 5 / 10 / 15 / 30 / 60 分钟 │ │
│ │ 最低 5 分钟，防止 API 成本过高。 │ │
│ │ │ │
│ │ ─────────────────────────────────────────────── │ │
│ │ │ │
│ │ 关于 │ │
│ │ │ │
│ │ Muse Creative Hotspots v1.0 │ │
│ │ 数据来源: TikHub API (api.tikhub.io) │ │
│ │ │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────┘
组件清单
| 组件ID | 组件名称 | 类型 | 说明 | 交互 |
|---|---|---|---|---|
| C-001 | Header | 导航栏 | 复用全局 Header | 同首页 |
| C-011 | ApiKeyInput | 输入框 | password 类型输入框 + 保存按钮 | 输入 Key → 点击保存 |
| C-012 | IntervalSelect | 下拉选择 | 刷新间隔选择器，选项: 5/10/15/30/60 分钟 | 选择后立即生效 |
交互说明
| 触发 | 动作 | 结果 |
|---|---|---|
| 输入 API Key + 点击保存 | POST /api/settings | 保存到服务端内存变量；成功/失败 Toast 提示 |
| 选择刷新间隔 | Zustand setRefreshInterval | 立即更新 TanStack Query refetchInterval |
| API Key 为空点击保存 | 前端校验 | 输入框红色边框 + "请输入 API Key" 提示 |
页面状态
| 状态 | 说明 | 展示 |
|---|---|---|
| 默认 | 正常展示设置表单 | 当前 Key（掩码）+ 当前间隔 |
| 保存中 | API Key 保存请求中 | 保存按钮 loading |
| 保存成功 | 保存完成 | Toast "API Key 已保存" |
| 保存失败 | 保存请求失败 | Toast "保存失败，请重试" |
3. 用户流程
3.1 内容浏览主流程
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ 打开应用 │ ──▶ │ 浏览首页 │ ──▶ │ 筛选/排序 │ ──▶ │ 查看详情 │
│ │ │ 卡片信息流│ │ 切换平台 │ │ 完整信息 │
│ P-001 │ │ P-001 │ │ P-001 │ │ P-002 │
└──────────┘ └────┬─────┘ └──────────┘ └────┬─────┘
│ │
│ API Key 未配置 │
▼ ▼
┌──────────┐ ┌──────────┐
│ 配置Key │ │ 查看原文 │
│ P-004 │ │ (外部跳转)│
└──────────┘ └──────────┘
流程步骤
| 步骤 | 页面 | 用户操作 | 系统响应 |
|---|---|---|---|
| 1 | P-001 | 打开应用 | 自动获取默认平台（全部）的热点内容 |
| 2 | P-001 | 浏览卡片信息流 | 展示卡片网格（封面图+标题+数据） |
| 3 | P-001 | 点击平台 Tab 切换 | 重新获取对应平台数据，更新卡片网格 |
| 4 | P-001 | 选择排序方式 | 前端内存排序，卡片重新排列 |
| 5 | P-001 | 点击感兴趣的卡片 | 路由跳转到详情页 |
| 6 | P-002 | 查看完整信息 | 展示大图+标题+数据面板+标签 |
| 7 | P-002 | 点击"查看原文" | 新窗口打开原平台页面 |
3.2 收藏管理流程
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ 浏览内容 │ ──▶ │ 点击收藏 │ ──▶ │ 打开收藏夹│ ──▶ │ 查看详情 │
│ P-001 │ │ ♡ → ♥ │ │ P-003 │ │ P-002 │
└──────────┘ └──────────┘ └──────────┘ └────┬─────┘
│ │
│ 也可在详情页收藏 │
▼ │
┌──────────┐ │
│ 详情页收藏│ │
│ P-002 │ ◀────────────────────────────┘
└──────────┘
流程步骤
| 步骤 | 页面 | 用户操作 | 系统响应 |
|---|---|---|---|
| 1 | P-001/P-002 | 点击卡片收藏按钮 ♡ | ♡ → ♥ 切换，存入 localStorage |
| 2 | P-003 | 点击 Header 收藏入口 | 展示所有已收藏内容的卡片网格 |
| 3 | P-003 | 点击卡片 | 跳转详情页 |
| 4 | P-003 | 点击 ♥ 取消收藏 | 卡片从收藏列表移除 |
3.3 设置配置流程
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ 点击 ⚙ │ ──▶ │ 输入Key │ ──▶ │ 保存Key │ ──▶ │ 设置间隔 │
│ P-001 │ │ P-004 │ │ P-004 │ │ P-004 │
└──────────┘ └──────────┘ └────┬─────┘ └────┬─────┘
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ 保存成功 │ │ 立即生效 │
│ Toast提示 │ │ 更新定时器│
└──────────┘ └──────────┘
流程步骤
| 步骤 | 页面 | 用户操作 | 系统响应 |
|---|---|---|---|
| 1 | P-001 | 点击 Header ⚙ 图标 | 跳转设置页 |
| 2 | P-004 | 输入 TikHub API Key | 输入框显示内容（password 掩码） |
| 3 | P-004 | 点击"保存 API Key" | POST /api/settings，成功后 Toast 提示 |
| 4 | P-004 | 选择刷新间隔（如 15 分钟） | Zustand 更新，TanStack Query refetchInterval 立即变更 |
| 5 | P-001 | 返回首页 | 使用新 Key 获取数据，按新间隔自动刷新 |
3.4 数据刷新流程
┌─────────────────────────────────────┐
│ 刷新触发 │
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ 自动刷新 │ │ 手动刷新 │ │
│ │ 定时器 │ │ 点击 🔄 │ │
│ └────┬─────┘ └────┬─────┘ │
│ │ │ │
│ └────────┬─────────┘ │
│ ▼ │
│ ┌──────────┐ │
│ │ 获取数据 │ │
│ │ F-001 │ │
│ └────┬─────┘ │
│ │ │
│ ┌────┴────┐ │
│ ▼ ▼ │
│ ┌────────┐ ┌────────┐ │
│ │ 成功 │ │ 失败 │ │
│ └───┬────┘ └───┬────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ 更新卡片 │ │ 保留旧数据│ │
│ │ 更新时间 │ │ 错误提示 │ │
│ └──────────┘ └──────────┘ │
│ │
└─────────────────────────────────────┘
4. 组件规范
4.1 全局组件
C-001: Header 导航栏
┌──────────────────────────────────────────────────────────────────────┐
│ │
│ Muse [全部] [抖音] [TikTok] [小红书] [♡ 收藏] [⚙] │
│ ─────── │
│ (当前Tab下划线高亮) │
│ │
└──────────────────────────────────────────────────────────────────────┘
说明:
- 左侧: Logo 文字 "Muse"，点击回首页
- 中部: 平台 Tab 栏（仅首页展示），当前选中 Tab 有下划线高亮
- 右侧: 收藏入口 + 设置图标
- 固定在页面顶部 (sticky top)
- 背景: 白色，底部 1px 边框线
C-001 变体: 非首页 Header（详情页、收藏夹、设置页使用）
┌──────────────────────────────────────────────────────────────────────┐
│ │
│ Muse [♡ 收藏] [⚙] │
│ │
└──────────────────────────────────────────────────────────────────────┘
说明:
- 平台 Tab 栏在非首页隐藏，Logo 与右侧图标之间保持留白
- 其余元素位置不变（Logo 左对齐，图标右对齐）
- 适用于: P-002 详情页、P-003 收藏夹、P-004 设置页
C-002: PlatformTabs 平台 Tab 栏
默认态: [全部] [抖音] [TikTok] [小红书]
─────
(选中态: 下划线 + 文字加粗)
各 Tab 含平台图标:
全部: 🌐 全部
抖音: 📱 抖音 (品牌色: #000000)
TikTok: 🎵 TikTok (品牌色: #00F2EA)
小红书: 📕 小红书 (品牌色: #FF2442)
Tab 切换时，下划线平滑滑动过渡
C-003: SortToolbar 工具栏
┌──────────────────────────────────────────────────────────────────────┐
│ │
│ 排序: [▼ 播放量] [↓ 降序] [🔄 刷新] 上次: 10:30│
│ ────────── ──────── ──────── │
│ 下拉选择 切换按钮 图标按钮 │
│ │
└──────────────────────────────────────────────────────────────────────┘
排序字段选项:
- 播放量 (play_count)
- 点赞数 (like_count)
- 评论数 (comment_count)
- 发布时间 (publish_time)
排序方向:
- ↓ 降序 (desc) — 默认
- ↑ 升序 (asc)
刷新按钮状态:
- 默认: 🔄 图标
- 刷新中: 旋转动画
- 防抖: 2 秒内重复点击忽略
4.2 业务组件
C-004: ContentCard 内容卡片
┌─────────────────────┐
│ ┌─────────────────┐ │
│ │ │ │ ← 封面图区域 (aspect-ratio: 4/3 或 3/4)
│ │ Cover Image │ │ 加载失败 → 灰色占位 + 平台图标
│ │ │ │ 使用 Next.js Image + loading="lazy"
│ └─────────────────┘ │
│ │
│ 📱 抖音 │ ← 平台图标 + 平台名 (品牌色小标签)
│ │
│ 标题文字截断展示最 │ ← 标题 (最多 2 行, line-clamp-2)
│ 多两行省略号... │
│ │
│ ┌──┐ │
│ │头│ 作者昵称 │ ← 作者头像 (24px 圆形) + 昵称
│ └──┘ │
│ │
│ ▶ 1.2M ❤ 5.3K │ ← 数据指标 (数字缩写: K/M)
│ 💬 203 [♡] │ ← 评论数 + 收藏按钮
│ │
└─────────────────────┘
宽度: minmax(280px, 1fr)
圆角: 8px (rounded-lg)
阴影: hover 时提升阴影
边框: 1px solid border色
过渡: hover 时 translateY(-2px)
收藏按钮 [♡]:
未收藏: ♡ 空心，灰色
已收藏: ♥ 实心，红色
点击区域: 足够大 (44x44px)，防止误触卡片跳转
指标展示规则: <!-- NEW -->
指标值为空（undefined）时隐藏该指标项，而非展示 0。
与 DevelopmentPlan ContentItem 类型中 play_count?: number（可选字段）一致。
Hover 行为: <!-- NEW -->
MVP 阶段: hover 仅做视觉反馈（阴影提升 + translateY(-2px)）。
v1.1 迭代: 考虑增加 hover tooltip/popover 展示更多信息（如完整标题、分享数）。
C-006: CardSkeleton 骨架屏
┌─────────────────────┐
│ ┌─────────────────┐ │
│ │░░░░░░░░░░░░░░░░░│ │ ← 封面占位 (pulse 动画)
│ │░░░░░░░░░░░░░░░░░│ │
│ │░░░░░░░░░░░░░░░░░│ │
│ └─────────────────┘ │
│ ░░░░░░░ │ ← 平台标签占位
│ ░░░░░░░░░░░░░░░░░░ │ ← 标题行占位
│ ░░░░░░░░░░░░░ │
│ ░░ ░░░░░░░░░ │ ← 作者占位
│ ░░░░ ░░░░ ░░░░ │ ← 数据指标占位
└─────────────────────┘
动画: Tailwind animate-pulse
颜色: bg-slate-200
C-008: FavoriteButton 收藏按钮
未收藏态: ♡ (text-slate-400, hover: text-red-400)
已收藏态: ♥ (text-red-500)
过渡动画: 点击时 scale 弹跳效果 (scale-110 → scale-100)
点击区域: 44px x 44px (无障碍最小触摸区域)
阻止冒泡: e.stopPropagation() 防止触发卡片跳转
C-009: EmptyState 空状态
┌──────────────────────────────────────┐
│ │
│ ┌──────────┐ │
│ │ {icon} │ │
│ └──────────┘ │
│ │
│ {主要文案} │ ← text-slate-800, 16px, medium
│ {辅助文案} │ ← text-slate-500, 14px, regular
│ │
│ [{action button}] │ ← 可选操作按钮
│ │
└──────────────────────────────────────┘
Props:
icon: ReactNode (图标)
title: string (主要文案)
description: string (辅助文案)
action?: { label: string, onClick: () => void }
C-013: Toast 通知
成功态 (右上角弹出):
┌──────────────────────────────┐
│ ✅ API Key 已保存 │
└──────────────────────────────┘
失败态 (右上角弹出):
┌──────────────────────────────┐
│ ❌ 保存失败，请重试 │
└──────────────────────────────┘
规范:
- 使用 shadcn/ui Toast 组件
- 位置: 页面右上角 (top-right)
- 自动消失时间: 3 秒
- 成功态: 绿色左边框 (border-l-4 border-green-500)
- 失败态: 红色左边框 (border-l-4 border-red-500)
- 支持手动关闭 (点击 × 按钮)
- 背景: white，阴影: shadow-lg
- 进入动画: slide-in-from-right
- 退出动画: fade-out
C-010: ErrorState 错误状态
┌──────────────────────────────────────┐
│ │
│ ┌──────────┐ │
│ │ ⚠️ │ │
│ └──────────┘ │
│ │
│ {错误描述} │ ← text-red-600
│ │
│ [🔄 重试] │ ← 主按钮
│ │
└──────────────────────────────────────┘
5. 设计规范
5.1 色彩规范
| 用途 | 色值 | Tailwind Class | 示例 |
|---|---|---|---|
| 主色 | #2563EB | blue-600 |
主按钮、链接、选中态 |
| 主色悬停 | #1D4ED8 | blue-700 |
按钮 hover |
| 成功 | #16A34A | green-600 |
保存成功提示 |
| 警告 | #D97706 | amber-600 |
频率限制提示 |
| 错误 | #DC2626 | red-600 |
错误提示、必填校验 |
| 收藏红 | #EF4444 | red-500 |
♥ 已收藏状态 |
| 文字主色 | #1E293B | slate-800 |
标题、正文 |
| 文字次色 | #64748B | slate-500 |
描述、辅助信息 |
| 文字弱色 | #94A3B8 | slate-400 |
占位文字、禁用态 |
| 背景色 | #FFFFFF | white |
页面背景 |
| 表面色 | #F8FAFC | slate-50 |
卡片背景、工具栏 |
| 边框色 | #E2E8F0 | slate-200 |
卡片边框、分割线 |
平台品牌色
| 平台 | 色值 | 用途 |
|---|---|---|
| 抖音 | #000000 | Tab 标签、平台图标背景 |
| TikTok | #00F2EA | Tab 标签、平台图标背景 |
| 小红书 | #FF2442 | Tab 标签、平台图标背景 |
5.2 字体规范
| 用途 | 字号 | 字重 | Tailwind Class |
|---|---|---|---|
| 页面标题 | 24px | Bold (700) | text-2xl font-bold |
| 区域标题 | 20px | Semibold (600) | text-xl font-semibold |
| 卡片标题 | 14px | Medium (500) | text-sm font-medium |
| 正文 | 14px | Regular (400) | text-sm |
| 数据指标 | 12px | Medium (500) | text-xs font-medium |
| 辅助文字 | 12px | Regular (400) | text-xs |
- 字体族: 系统默认字体栈 (Inter, system-ui, sans-serif)
5.3 间距规范
| 间距 | 值 | Tailwind | 用途 |
|---|---|---|---|
| xs | 4px | 1 |
图标与文字间距 |
| sm | 8px | 2 |
卡片内元素间距 |
| md | 12px | 3 |
卡片内部 padding |
| lg | 16px | 4 |
组件间距、网格 gap |
| xl | 24px | 6 |
区域间距 |
| 2xl | 32px | 8 |
页面 padding |
5.4 圆角规范
| 元素 | 圆角 | Tailwind |
|---|---|---|
| 卡片 | 8px | rounded-lg |
| 按钮 | 6px | rounded-md |
| 输入框 | 6px | rounded-md |
| 头像 | 50% | rounded-full |
| 平台标签 | 4px | rounded |
5.5 阴影规范
| 场景 | 阴影 | Tailwind |
|---|---|---|
| 卡片默认 | 0 1px 2px rgba(0,0,0,0.05) | shadow-sm |
| 卡片悬停 | 0 4px 6px rgba(0,0,0,0.1) | shadow-md |
| Header | 0 1px 3px rgba(0,0,0,0.1) | shadow-sm |
| 弹窗/Toast | 0 10px 15px rgba(0,0,0,0.1) | shadow-lg |
5.6 响应式断点
| 断点 | 宽度 | Tailwind | 布局说明 |
|---|---|---|---|
| Mobile | < 640px | sm: |
单栏，卡片全宽 |
| Tablet | 640px - 1024px | md: / lg: |
2 列卡片网格 |
| Desktop | 1024px - 1280px | xl: |
3 列卡片网格 |
| Wide | > 1280px | 2xl: |
4-5 列卡片网格 |
网格响应式规则:
CSS Grid: grid-template-columns: repeat(auto-fill, minmax(280px, 1fr))
< 640px: 1 列 (卡片宽度 100%)
640-960: 2 列
960-1240: 3 列
1240-1520: 4 列
> 1520: 5 列
6. 页面与功能映射
| 功能ID | 功能名称 | 所在页面 | 主要组件 |
|---|---|---|---|
| F-001 | 内容获取 | P-001 | TanStack Query (数据层) |
| F-002 | 卡片信息流展示 | P-001 | C-005 ContentGrid + C-004 ContentCard |
| F-003 | 内容筛选与排序 | P-001 | C-002 PlatformTabs + C-003 SortToolbar |
| F-004 | 内容详情页 | P-002 | C-007 DetailPanel |
| F-005 | 自动定时刷新 | P-001 | C-003 SortToolbar (时间显示) |
| F-006 | 手动刷新 | P-001 | C-003 SortToolbar (刷新按钮) |
| F-007 | 内容收藏 | P-001, P-002 | C-008 FavoriteButton |
| F-008 | 收藏夹管理 | P-003 | C-005 ContentGrid + C-004 ContentCard |
| F-009 | 收藏数据持久化 | P-003 | Zustand persist (数据层) |
| F-010 | API Key 配置 | P-004 | C-011 ApiKeyInput |
| F-011 | 刷新间隔设置 | P-004 | C-012 IntervalSelect |
| F-014 | API 请求代理 | - | 后端 API Route (无 UI) |
| F-015 | 统一数据模型 | - | TypeScript 类型 (无 UI) |
| F-016 | 平台适配器 | - | 后端适配器 (无 UI) |