131 lines
4.0 KiB
Markdown
131 lines
4.0 KiB
Markdown
# 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`) |