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

3.6 KiB

Raw Permalink Blame History

CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在本仓库中工作时提供指引。

常用命令

# 开发 — 同时启动前端 (3000) 和后端 (3001)
pnpm dev

# 构建所有包
pnpm build

# 单元测试（所有包，Vitest）
pnpm test                          # 运行一次
pnpm test:watch                    # 监听模式
pnpm test:coverage                 # 含覆盖率（阈值 80%）

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

# 运行单个测试文件
npx vitest run packages/backend/src/lib/tikhub.test.ts

# 代码检查（仅前端）
pnpm lint

# E2E 测试（Playwright，mock 后端）
pnpm test:e2e                      # 无头模式
pnpm test:e2e:ui                   # 交互式 UI

# E2E 测试（真实后端 + TikHub API，仅在明确要求时运行）
pnpm test:e2e:real

架构

pnpm monorepo，包含三个包：

packages/
  frontend/   @muse/frontend   Next.js 16 (App Router, React 19)  → localhost:3000
  backend/    @muse/backend    Hono 4 on Node                     → localhost:3001
  shared/     @muse/shared     类型定义与平台配置

请求链路：浏览器 → Next.js 前端 → Hono 后端 → TikHub API (api.tikhub.io)

前端通过 CORS 直接请求后端（不经过 Next.js API Routes 代理）。API 基础地址来自环境变量 NEXT_PUBLIC_API_URL。

后端

入口：src/index.ts → src/app.ts（Hono + CORS 中间件）
路由：/api/tikhub/:platform（热门内容）、/api/tikhub/:platform/detail（内容详情）、/api/settings（API Key 管理）
适配器：src/lib/adapters/{douyin,tiktok,xiaohongshu,youtube,instagram,twitter,bilibili,weibo}.ts — 各自实现 PlatformAdapter 接口，将平台特定响应标准化为 ContentItem（共 8 个平台）
限流：src/lib/rate-limiter.ts 滑动窗口限流，10 请求/秒
API Key：运行时 Key（通过 POST /api/settings 设置）优先于 process.env.TIKHUB_API_KEY；后端不会自动加载 .env（未使用 dotenv）

前端

状态管理：Zustand store + localStorage 持久化 — settings（API Key、刷新间隔）和 favorites（收藏列表）
数据获取：TanStack React Query — useContentQuery（热门列表）和 useDetailQuery（单条详情，带缓存查找）
页面：/（首页，含平台标签页 + 排序）、/detail/[platform]/[id]、/favorites、/settings
样式：Tailwind CSS v4、shadcn/ui 组件、Lucide 图标、Sonner toast 提示

Shared（共享包）

导出 Platform 类型、ContentItem 接口、PlatformAdapter 接口、MVP_PLATFORMS 配置数组和 getPlatformConfig() 函数。

关键模式

平台适配器是集成边界 — 新增平台只需在 packages/backend/src/lib/adapters/ 下创建适配器并在 index.ts 中注册
前端组件使用 data-testid 属性作为 E2E 选择器（如 content-grid、content-card、favorite-btn、platform-tab-{id}、sort-select、sort-order）
e2e/ 中的 E2E 测试通过 page.route() mock 所有 /api/tikhub/ 请求 — 仅测试前端逻辑
e2e-real/ 中的 E2E 测试走真实后端和 TikHub API — 必须串行运行（workers: 1）以避免共享状态污染
覆盖率配置在各包的 vitest.config.ts 中；前端仅覆盖 src/lib/** 和 src/stores/**

环境变量

后端 .env：

TIKHUB_API_KEY=...
CORS_ORIGIN=http://localhost:3000
PORT=3001

前端 .env.local：

NEXT_PUBLIC_API_URL=http://localhost:3001

3.6 KiB Raw Permalink Blame History Unescape Escape