# Music Workshop

音乐文件智能整理工具 - 通过元数据匹配、去重、自动入库，将散乱的音乐文件整理成规范的媒体库。

## 功能特性

- 🎵 **元数据匹配**：支持 AcoustID、MusicBrainz、网易云、QQ 音乐、Spotify 等多源匹配
- 🔧 **缺失元数据补全**：可视化编辑 title/artist/album_artist，实时预览入库路径
- 🗑️ **智能去重**：基于音频指纹和元数据的重复检测，支持保留/替换/重命名策略
- 📂 **自动整理入库**：按 `Artist/Album/Track - Title.ext` 规范路径组织文件
- 🖥️ **Web UI**：React + Tailwind CSS，提供异常队列处理和批量操作界面
- 📊 **任务跟踪**：实时 WebSocket 推送，查看任务执行进度和日志

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | React 18, Vite, Tailwind CSS, Lucide Icons |
| 后端 | Python 3.11+, FastAPI, SQLite, Mutagen |
| 匹配引擎 | AcoustID, MusicBrainz, 网易云 API, QQ 音乐 API, Spotify API |
| 音频处理 | FFmpeg, Chromaprint (音频指纹) |

## 项目结构

```
MusicWorkshop/
├── backend/               # FastAPI 后端服务
│   ├── app/
│   │   ├── services/      # 拆分后的服务模块（预览/执行/编排）
│   │   ├── exception_service.py
│   │   ├── matcher.py
│   │   ├── preprocessor.py
│   │   ├── repair_runner.py
│   │   └── ...
│   ├── tests/             # 单元测试
│   └── pyproject.toml     # ruff/black 配置
├── frontend/              # React 前端应用
│   ├── src/
│   │   ├── api/           # API 调用封装
│   │   ├── components/    # 可复用组件
│   │   └── pages/         # 页面组件
│   ├── .eslintrc.json     # ESLint 配置
│   ├── .prettierrc        # Prettier 配置
│   └── package.json
├── scripts/               # 辅助脚本
├── .pre-commit-config.yaml # Git hooks 配置
└── README.md
```

## 快速开始

### 环境要求

- Node.js 18+
- Python 3.11+
- FFmpeg (用于音频处理)
- Chromaprint (用于音频指纹)

### 安装依赖

```bash
# 后端
cd backend
pip install -r requirements.txt

# 前端
cd frontend
npm install
```

### 配置

1. 复制 `backend/.env.example` 为 `backend/.env`
2. 填写 API 密钥（AcoustID、MusicBrainz、网易云等）
3. 设置输入/输出目录路径

### 启动服务

```bash
# 后端 (开发模式)
cd backend
uvicorn app.main:app --reload --port 8000

# 前端 (开发模式)
cd frontend
npm run dev
```

访问 `http://localhost:5173` 打开 Web UI。

## 代码规范

本项目使用以下工具保证代码质量：

### 前端

```bash
cd frontend
npm run lint        # 检查代码规范
npm run lint:fix    # 自动修复
npm run format      # 格式化代码
```

### 后端

```bash
cd backend
ruff check .        # 检查代码规范
black .             # 格式化代码
```

### Git Hooks (pre-commit)

```bash
pre-commit install  # 安装 Git hooks
pre-commit run --all-files  # 手动运行所有检查
```

## API 文档

启动后端服务后访问 `http://localhost:8000/docs` 查看自动生成的 OpenAPI 文档。

## 测试

```bash
# 后端单元测试
cd backend
pytest

# 前端 (待补充)
cd frontend
npm test
```

## 许可证

[MIT](LICENSE)

## 贡献指南

欢迎提交 Issue 和 Pull Request。请确保代码通过 lint 检查和单元测试。

---

🤖 Generated with [Claude Code](https://claude.com/claude-code)