chore: add project configs, backend repair services, docs, and code quality tooling

- 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>
2026-05-08 15:49:37 +08:00
parent 7d003ff822
commit be3c086975
17 changed files with 6389 additions and 0 deletions
@@ -0,0 +1,145 @@
+# 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)