muse_creative_hotspots/doc/tasks.md

# Muse Creative Hotspots — 任务列表

## 文档信息

| 项目 | 内容 |
|------|------|
| 版本 | v2.0 |
| 创建日期 | 2026-03-03 |
| 架构 | 前后端分离 Monorepo（@muse/shared + @muse/backend + @muse/frontend） |

## 1. 架构概览

```
museCreativeHotspots/
├── pnpm-workspace.yaml
├── packages/
│   ├── shared/          # @muse/shared — 共享类型和平台配置
│   ├── backend/         # @muse/backend — Hono API 服务器 (port 3001)
│   └── frontend/        # @muse/frontend — Next.js 前端 (port 3000)
```

---

## 2. Phase 1 — 基础架构搭建（已完成 ✅）

**目标**: 搭建 Monorepo 骨架，共享类型系统，API 代理链路，平台适配器。

| ID | 任务 | 包 | 状态 |
|----|------|----|------|
| T-001 | Monorepo 初始化 (pnpm workspace + 三个包) | root | ✅ |
| T-002 | TypeScript 类型定义 (ContentItem, Platform, PlatformAdapter) | @muse/shared | ✅ |
| T-003 | 平台配置 (MVP_PLATFORMS, getPlatformConfig) | @muse/shared | ✅ |
| T-004 | TikHub API 客户端与限流 (tikhubFetch, waitForSlot) | @muse/backend | ✅ |
| T-005 | 平台适配器 — 抖音 | @muse/backend | ✅ |
| T-006 | 平台适配器 — TikTok | @muse/backend | ✅ |
| T-007 | 平台适配器 — 小红书 | @muse/backend | ✅ |
| T-008 | 适配器注册表 (getAdapter, getSupportedPlatforms) | @muse/backend | ✅ |
| T-009 | Hono API 路由 — 热榜 (GET /:platform) | @muse/backend | ✅ |
| T-010 | Hono API 路由 — 详情 (GET /:platform/detail) | @muse/backend | ✅ |
| T-011 | Hono API 路由 — 设置 (GET /, POST /) | @muse/backend | ✅ |

---

## 3. Phase 2 — 核心功能实现（已完成 ✅）

**目标**: 前端页面、组件、数据查询、状态管理。

| ID | 任务 | 包 | 状态 |
|----|------|----|------|
| T-012 | Zustand Store — settings (apiKey, refreshInterval, persist) | @muse/frontend | ✅ |
| T-013 | Zustand Store — favorites (addFavorite, removeFavorite, persist) | @muse/frontend | ✅ |
| T-014 | TanStack Query 集成 (useContentQuery, useDetailQuery) | @muse/frontend | ✅ |
| T-015 | API_BASE_URL 前缀 (所有 fetch 指向 backend 3001) | @muse/frontend | ✅ |
| T-016 | 内容卡片组件 (ContentCard + ContentGrid + CardSkeleton) | @muse/frontend | ✅ |
| T-017 | 平台 Tab 切换 (PlatformTabs) | @muse/frontend | ✅ |
| T-018 | 排序功能 (SortToolbar) | @muse/frontend | ✅ |
| T-019 | 内容详情页 (DetailPanel + DetailSkeleton) | @muse/frontend | ✅ |
| T-020 | 收藏按钮组件 (FavoriteButton) | @muse/frontend | ✅ |
| T-021 | 首页页面组装 (page.tsx) | @muse/frontend | ✅ |
| T-022 | 设置页面 (settings/page.tsx) | @muse/frontend | ✅ |
| T-023 | 收藏夹页面 (favorites/page.tsx) | @muse/frontend | ✅ |
| T-024 | 全局布局 (layout.tsx + Header + QueryProvider) | @muse/frontend | ✅ |

---

## 4. Phase 3 — 测试与验证（已完成 ✅）

**目标**: 各包独立测试，80% 覆盖率阈值。

| ID | 任务 | 包 | 状态 |
|----|------|----|------|
| T-025 | 共享包测试 (platforms.test.ts) | @muse/shared | ✅ |
| T-026 | 后端单元测试 — 限流器、API 客户端 | @muse/backend | ✅ |
| T-027 | 后端单元测试 — 适配器 (douyin, tiktok, xiaohongshu) | @muse/backend | ✅ |
| T-028 | 后端集成测试 — Hono 路由 (app.request 风格) | @muse/backend | ✅ |
| T-029 | 前端单元测试 — stores (favorites, settings) | @muse/frontend | ✅ |
| T-030 | 前端单元测试 — format.ts | @muse/frontend | ✅ |

---

## 5. Phase 4 — 新增平台适配器（已完成 ✅）

**目标**: 新增 YouTube、Instagram、Twitter/X、哔哩哔哩、微博 5 个平台的适配器、配置和测试。

| ID | 任务 | 包 | 状态 |
|----|------|----|------|
| T-031 | 平台适配器 — YouTube | @muse/backend | ✅ |
| T-032 | 平台适配器 — Instagram | @muse/backend | ✅ |
| T-033 | 平台适配器 — Twitter/X | @muse/backend | ✅ |
| T-034 | 平台适配器 — 哔哩哔哩 | @muse/backend | ✅ |
| T-035 | 平台适配器 — 微博 | @muse/backend | ✅ |
| T-036 | 适配器注册表更新 (8 个平台) | @muse/backend | ✅ |
| T-037 | 共享包平台配置更新 (MVP_PLATFORMS 8 项) | @muse/shared | ✅ |
| T-038 | YouTube 适配器单元测试 | @muse/backend | ✅ |
| T-039 | Instagram 适配器单元测试 | @muse/backend | ✅ |
| T-040 | Twitter/X 适配器单元测试 | @muse/backend | ✅ |
| T-041 | 哔哩哔哩适配器单元测试 | @muse/backend | ✅ |
| T-042 | 微博适配器单元测试 | @muse/backend | ✅ |
| T-043 | E2E Mock 测试更新 (fixtures + home.spec) | e2e/ | ✅ |
| T-044 | E2E 真实测试更新 (新平台切换) | e2e-real/ | ✅ |

---

## 6. 启动方式

```bash
# 安装依赖
pnpm install

# 同时启动前后端
pnpm dev

# 仅启动后端 (port 3001)
pnpm --filter @muse/backend dev

# 仅启动前端 (port 3000)
pnpm --filter @muse/frontend dev

# 运行全部测试
pnpm test

# 运行单包测试
pnpm --filter @muse/backend test
pnpm --filter @muse/frontend test
pnpm --filter @muse/shared test
```

---

## 7. 关键设计决策

1. **shared 包不构建**: 直接导出 `.ts` 源文件，消费方各自编译
2. **app.ts 与 index.ts 分离**: app.ts 只导出 Hono 实例，测试可直接 import
3. **NEXT_PUBLIC_ 前缀**: 前端 API URL 使用此前缀确保客户端可读
4. **CORS 中间件**: 后端配置 CORS 允许前端跨域调用
5. **API 路由前缀**: 保持 `/api/tikhub/...` 和 `/api/settings` 路径不变

---

## 8. 未来计划 (v1.1+)

| 功能 | 描述 |
|------|------|
| F-012 平台管理 | 前端可启用/禁用平台 |
| F-013 展示数量设置 | 用户自定义每页展示数量 |
| F-017 API 调用量统计 | 后端统计 API 调用次数 |
| Docker 部署 | 容器化部署方案 |
| E2E 测试 | Playwright 端到端测试 |