Files

T

liumangmang be3c086975 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

3.5 KiB

Raw Permalink Blame History

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 (用于音频指纹)

安装依赖

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

# 前端
cd frontend
npm install

配置

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

启动服务

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

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

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

代码规范

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

前端

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

后端

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

Git Hooks (pre-commit)

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

API 文档

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

测试

# 后端单元测试
cd backend
pytest

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

许可证

MIT

贡献指南

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

🤖 Generated with Claude Code

3.5 KiB Raw Permalink Blame History Unescape Escape