# 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` 脚本）。