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>

CLAUDE.md

@@ -0,0 +1,102 @@
+# CLAUDE.md
+
+本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。
+
+## 常用命令
+
+### 后端 (Python/FastAPI)
+
+```bash
+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)
+
+```bash
+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 格式化
+```
+
+### 全栈开发
+
+```bash
+# 使用提供的脚本同时启动后端和前端
+./scripts/dev.sh start      # 启动两者，日志输出到 .dev-runtime/
+./scripts/dev.sh stop       # 停止两者
+./scripts/dev.sh restart
+./scripts/dev.sh status
+```
+
+### Pre-commit 钩子
+
+```bash
+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` 脚本）。