MusicWorkshop/CLAUDE.md

CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。

常用命令

后端 (Python/FastAPI)

cd backend

# 安装依赖（使用虚拟环境）
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt   # 最小运行环境
# 或完整开发环境：pip install ruff black pytest

# 运行开发服务器
uvicorn app.main:app --reload --port 8000

# 代码检查与格式化
ruff check .          # 代码检查
black .               # 格式化

# 运行测试
pytest                # 所有测试
pytest tests/test_matcher.py -v   # 单个测试文件
pytest -k "test_function_name"    # 按名称运行单个测试

前端 (React/Vite)

cd frontend

npm install
npm run dev           # 启动开发服务器（端口 5173）
npm run build         # 生产构建
npm run preview       # 预览构建产物
npm run lint          # ESLint 检查
npm run lint:fix      # 自动修复 lint 问题
npm run format        # Prettier 格式化

全栈开发

# 使用提供的脚本同时启动后端和前端
./scripts/dev.sh start      # 启动两者，日志输出到 .dev-runtime/
./scripts/dev.sh stop       # 停止两者
./scripts/dev.sh restart
./scripts/dev.sh status

Pre-commit 钩子

pre-commit install
pre-commit run --all-files

架构概览

后端核心 (backend/app/)

• main.py – FastAPI 应用，包含 CORS、WebSocket 端点 (/ws/tasks/{task_id})、配置/任务/媒体库/异常/修复的 REST 路由。
• task_runner.py – 编排异步流程：扫描 → 预处理 → 匹配 → 后处理。通过 TaskStreamManager 发送进度。
• repair_runner.py – 处理异常修复工作流（预览/执行），用于元数据错误或缺失的条目。
• matcher.py – 多源元数据匹配（AcoustID、MusicBrainz、网易云、QQ 音乐、Spotify）。包含 provider 链式逻辑。
• preprocessor.py – 使用 Mutagen 从音频文件提取/清洗元数据。
• scanner.py – 递归扫描输入目录中的音频文件。
• library_service.py / library_postprocess.py / library_index.py – 管理整理后的媒体库：将文件移动/复制到 Artist/Album/ 结构，维护索引。
• exception_service.py – 处理匹配失败或有冲突的音轨，与主库分开存储。
• task_store.py / storage.py – SQLite 持久化，存储任务历史、配置、媒体库索引。使用原生 SQL 管理 Schema。
• task_stream.py – WebSocket 消息广播，用于实时任务更新。
• services/ – 拆分出的修复逻辑：repair_preview.py、repair_execution.py、repair_orchestrator.py。
• schemas.py – Pydantic 模型，定义 API 请求/响应结构。

前端 (frontend/src/)

• pages/ – 主视图（仪表盘、媒体库、异常、配置等）。
• components/ – 可复用 UI 组件（模态框、卡片、表单、任务进度）。
• api/ – Axios 客户端封装后端 API 调用；WebSocket 辅助函数用于实时日志。
• utils/ – 格式化、日期辅助、常量。
• App.jsx – 路由配置（React Router）。
• main.jsx – 入口文件，集成 Tailwind CSS。

其他目录

• services/metadata/ – 外部元数据 provider 集成（MusicBrainz 等 API 客户端）。
• scripts/dev.sh – 后台运行 uvicorn + npm run dev 的进程管理脚本。
• .pre-commit-config.yaml – 对暂存文件运行 ruff、black、prettier。

关键环境变量

• MUSIC_WORKSHOP_DB_PATH – 覆盖 SQLite 数据库路径（默认 backend/data/music_workshop.db）。
• 各元数据 provider 的 API 密钥：在 backend/.env 中设置（参考 .env.example）。

测试说明

• 后端测试使用 pytest；测试固件直接写在测试文件中（暂无单独的 conftest.py）。
• 运行单个测试示例：pytest tests/test_matcher.py::test_specific_function
• 前端测试尚未配置（package.json 中没有 npm test 脚本）。