# 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
```