# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

没事Music 是一个基于 Web 的音乐播放器应用,采用单文件 React 架构,支持多平台音乐搜索、播放和同步功能。

## 架构设计

### 前端架构 (index.html)

**单文件应用模式**:
- 所有前端代码集中在 `index.html` (~89KB)
- 使用 Babel Standalone 在浏览器端编译 JSX
- React 18 + Tailwind CSS + Font Awesome (均通过 CDN 引入)

**核心组件结构**:
```
App (主容器)
├── SideDrawer (侧边栏设置)
├── MiniPlayer (迷你播放器)
├── FullPlayer (全屏播放器)
├── PlaylistDrawer (播放列表)
└── TopListPage (排行榜页面)
```

**状态管理**:
- 使用 React Hooks (useState, useEffect, useRef, useMemo, useCallback)
- 数据持久化: localStorage (前缀 `th_`)
- 关键状态: playlist, favorites, currentSong, syncToken, syncMode

**数据规范化**:
- `normalizeSongId()`: 全局强制歌曲 ID 为字符串类型
- `normalizeSongList()`: 批量规范化歌曲列表
- `getSongDurationSeconds()`: 统一处理不同来源的时长字段 (duration/dt/time/interval/length/playTime)

### 后端架构 (sync-server/server.js)

**KV 存储服务**:
- 基于 Node.js 原生 HTTP 服务器
- 文件系统存储: `data/{token}_{key}.json`
- API 端点: `GET/POST /kv/:key?token=...`
- Token 用于用户隔离

**后台下载管理器**:
- 自动检测歌曲列表数据并触发下载
- 文件命名: `{歌手} - {歌名} [{平台}_{ID}]`
- 文件名清理: Unicode 规范化 (NFC) + 非法字符替换
- 存储路径: `MUSIC_DIR` (默认 `./music`)

### 同步策略

**两种同步模式**:
1. **私有云同步** (`syncMode: 'server'`):
   - 基于 Token 的 KV 存储
   - 增量同步: 计算本地与上次同步的差异 (added/removed)
   - 自动同步: 每 15 分钟执行一次

2. **网易云歌单同步** (`syncMode: 'netease_playlist'`):
   - 通过 TuneHub API 获取歌单
   - 导入即替换逻辑
   - 自动同步: 每 15 分钟执行一次

**同步流程**:
```
拉取远程 → 计算差异 → 合并本地(非覆盖) → 推送至私有云
```

### 外部 API 集成

**TuneHub API** (https://music-dl.sayqz.com):
- 搜索: `/api/?type=search&keyword=...&source=...`
- 歌词: `/api/?source=...&id=...&type=lrc`
- 排行榜列表: `/api/?source=...&type=toplists`
- 排行榜歌曲: `/api/?source=...&id=...&type=toplist`
- 歌单详情: `/api/?type=playlist&id=...&source=...`

**支持平台**: netease, kuwo, qq, kugou

## 部署架构

### Docker Compose

```yaml
services:
  music-canvas:      # 前端静态网站
    ports: 7481:3000

  sync-service:      # 同步服务
    ports: 7482:3001
    volumes:
      - ./data:/app/data      # KV 数据存储
      - ./music:/app/music    # 音乐文件存储
```

### Nginx 配置

- 前端: `/` → `http://127.0.0.1:7481`
- 同步 API: `/api/` → `http://127.0.0.1:7482/` (去掉 `/api` 前缀)

## 开发注意事项

### 代码修改原则

1. **ID 类型一致性**: 所有歌曲 ID 必须保持字符串类型,使用 `normalizeSongId()` 处理
2. **文件名清理**: 使用 Unicode NFC 规范化 + 非法字符替换,避免跨平台问题
3. **状态同步**: 修改 favorites/playlist 后,确保同步逻辑正确触发
4. **API 调用**: 所有外部 API 调用通过 TuneHub API,不要直接调用各平台 API

### 关键常量

```javascript
API_BASE = "https://music-dl.sayqz.com"
SYNC_API_BASE = "/api"  // 相对路径,依赖 Nginx 代理
SOURCES = ['netease', 'kuwo', 'qq', 'kugou']
```

### 本地开发

前端无需构建,直接用浏览器打开 `index.html` 即可。如需测试同步功能:
```bash
cd sync-server
node server.js  # 默认端口 3001
```

### 环境变量 (sync-server)

- `DATA_DIR`: KV 数据存储目录 (默认 `./data`)
- `MUSIC_DIR`: 音乐文件存储目录 (默认 `./music`)
- `PORT`: 服务端口 (默认 `3001`)