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>
93 lines
3.6 KiB
Markdown
93 lines
3.6 KiB
Markdown
# CLAUDE.md
|
||
|
||
本文件为 Claude Code (claude.ai/code) 在本仓库中工作时提供指引。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 开发 — 同时启动前端 (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
|
||
```
|