liumangmang
be3c086975
- Add pre-commit hooks (ruff, black, prettier) and ESLint/Prettier configs - Add backend repair services (execution, orchestration, preview) with tests - Add project documentation (CLAUDE.md, README.md, design specs and plans) - Add MissingTagsInlinePanel component for exception handling - Add pyproject.toml with ruff/black configuration Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
146 lines
3.5 KiB
Markdown
146 lines
3.5 KiB
Markdown
# 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)
|