liumangmang
be3c086975
- 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>
102 lines
4.0 KiB
Markdown
102 lines
4.0 KiB
Markdown
# 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` 脚本）。 |