feat(api): upload queue with quota, tus intake, processing and import (M5.5)

- Migration 00008: upload_batches, upload_files, upload_quota.
- Quota reserved under a row lock when a batch is created; every status
  change goes through one transition that frees space in the same
  transaction. SHA-256 duplicates are rejected before any upload.
- tus 1.0.0 core (HEAD/PATCH) for the author only; offset is the real
  staging file size, data beyond the declared size is refused (ADR-015).
- Processing worker: ffprobe checks, SHA-256 verification, exact and
  Chromaprint duplicates against library and queue, metadata from tags
  or the dropped folder path, possible_duplicate on metadata match, and
  the target path from write_template reusing existing folder spelling.
- Import worker: edited tags written with ffmpeg stream copy, file
  written by storage-agent, point scan of the new file, imported status;
  idempotent and resumed after restart. Stale uploads expire after 24 h,
  orphan staging files are removed at startup.
- API: quota, precheck, batches, my uploads, withdraw, admin list,
  metadata edit, bulk review, retry and queue settings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/api.md

@@ -135,8 +135,8 @@
 | GET | `/uploads/quota` | moderator, admin | `{limit_bytes, used_bytes, per_user_limit_bytes, user_used_bytes, max_file_bytes}` |
 | POST | `/uploads/precheck` | moderator, admin | `{files:[{client_id, size, sha256, tags:{artist,title,album,duration_ms}}]}` → для каждого `accepted` / `duplicate` (+ `track`) / `too_large`; ничего не резервирует |
 | POST | `/uploads` | moderator, admin | Создать пачку `{comment, files:[{client_id, name, rel_path, size, sha256}]}` → резерв квоты; `{batch_id, files:[{client_id, upload_file_id, tus_url} | {client_id, rejected: code}]}`; при нехватке места — `uploads.queue_full` для не поместившихся |
-| tus | `/uploads/files/{upload_file_id}` | автор | Resumable-загрузка (`HEAD`/`PATCH`) |
-| GET | `/uploads/mine?status=&cursor=` | moderator, admin | Мои предложения |
+| tus | `/uploads/files/{upload_file_id}` | автор | Resumable-загрузка (`HEAD`/`PATCH`, ядро tus 1.0.0 — ADR-015) |
+| GET | `/uploads/mine?status=&cursor=` | moderator, admin | Мои предложения (`status` — через запятую) |
 | DELETE | `/uploads/files/{id}` | автор | Отозвать (`withdrawn`), только до решения |
 | GET | `/admin/uploads?status=&author=&possible_duplicate=&cursor=` | admin | Очередь, сгруппированная по пачкам |
 | GET | `/admin/uploads/files/{id}/stream?sig=` | admin | Прослушивание из staging |
@@ -144,6 +144,7 @@
 | PATCH | `/admin/uploads/batches/{id}` | admin | Правка общих полей для всех файлов пачки (исполнитель, альбом, год, обложка) |
 | POST | `/admin/uploads/review` | admin | `{file_ids:[], decision: "approve"|"reject", reason?}` — массовое решение |
 | POST | `/admin/uploads/files/{id}/retry` | admin | Повторить импорт после `import_failed` |
+| GET · PATCH | `/admin/settings/uploads` | admin | Лимиты очереди и хранилище по умолчанию |
 | GET | `/admin/audit?cursor=` | admin |
 
 ## Внутренние API

docs/decisions.md

@@ -187,3 +187,19 @@ Valence — грубая оценка (лад + яркость); `mood_*`, `arou
 **Последствия.** Анализ работает на любом CPU без моделей. Контексты используют энергию, темп, танцевальность
 и valence; настроения «весёлое» / «грустное» пока приблизительны. Переход на Essentia — новая версия
 `analyzer_ver`: воркер сам ставит пересчёт всех треков.
+
+---
+
+## ADR-015. Приём загрузок — ядро tus своими силами, без tusd
+
+**Контекст.** ADR-012 предполагал `tusd` как библиотеку. Но файл очереди создаёт `POST /uploads` вместе с резервом
+квоты и проверкой дублей, а права (только автор, только `uploading`) проверяет `api`. От tus остаётся только ядро
+протокола: `HEAD` (сколько принято) и `PATCH` (следующий кусок с `Upload-Offset`).
+
+**Решение.** Ядро tus 1.0.0 — в `internal/uploads/tus.go` (~200 строк): смещение — фактический размер файла в staging,
+один `PATCH` на файл одновременно, данные сверх заявленного размера не принимаются, куски до 64 МБ. Расширения
+creation / termination / checksum не нужны. Клиент — `tus-js-client` с готовым `uploadUrl` из ответа `POST /uploads`.
+
+**Последствия.** Нет новой зависимости и отдельного хранилища состояния tus; квота и права — в одной транзакции
+с созданием файла. Целостность проверяется после приёма: SHA-256 файла сверяется с заявленным клиентом.
+

docs/uploads.md

@@ -175,6 +175,29 @@
 - Автор видит статусы в «Мои предложения» (раздел админки модератора), бейдж с числом решений с последнего визита.
 - Админ видит бейдж «N на рассмотрении» в сайдбаре.
 
+## Реализация (`services/api/internal/uploads`)
+
+- Таблицы — миграция `00008_uploads.sql`; смещение tus — `upload_files.received_bytes`, отпечаток Chromaprint файла
+  очереди — `upload_files.fingerprint` (дубли внутри очереди ловятся так же, как с библиотекой).
+- Квота: `Store.CreateBatch` резервирует под `SELECT … FOR UPDATE` строки `upload_quota`; любая смена статуса идёт через
+  `transition` — место освобождается в той же транзакции, если новый статус его не занимает (таблица раздела 2).
+- Приём — ядро tus (ADR-015): `HEAD` / `PATCH /api/v1/uploads/files/{id}`, только автор и только в `uploading`.
+  Принят целиком → `processing`.
+- Обработка (`worker.go`, по одному файлу): размер → `ffprobe` (5 с – 3 ч) → SHA-256 (сверка с заявленным) →
+  дубль по SHA-256 → Chromaprint против библиотеки и очереди (длительность ±5 с, `library.Similarity` ≥ 0.75) →
+  метаданные (теги → путь из папки по регэкспам целевого хранилища → имя файла) → совпадение метаданных
+  (`possible_duplicate`) → путь по `write_template` с переиспользованием существующих папок → `pending_review`.
+  Если путь не строится (нет хранилища / шаблона / поля), файл всё равно ждёт рассмотрения, причина — в `status_reason`.
+- Хранилище: выбранное админом → `default_source_id` из настроек → единственное с `accepts_uploads`.
+- Импорт: правленые метаданные → копия с тегами (`ffmpeg -map 0 -c copy -metadata …`, FLAC/MP3/M4A/Ogg/Opus) →
+  `storage-agent` `POST /internal/files` → `Scanner.ScanFile` (точечный скан) → `imported`, связь `media_files.upload_file_id`.
+  Повторяемо: если по пути уже лежит файл с тем же хэшем, запись пропускается. Прерванный импорт при старте
+  возвращается в `approved`.
+- Очистка: раз в 10 минут `uploading` старше 24 ч → `expired`; при старте — удаление файлов staging без записи в БД.
+- Настройки: `GET` / `PATCH /admin/settings/uploads` (ключ `uploads.settings` в `app_settings`).
+- Пока не сделано: `allow_quality_upgrade`, правка «на всю пачку» (`PATCH /admin/uploads/batches/{id}`),
+  прослушивание из staging, отдельная обложка пачки, ночная сверка счётчика квоты, экраны веба.
+
 ## 11. Очистка
 - `uploading` старше 24 ч → `expired`, файлы удаляются.
 - Записи завершённых загрузок (`imported`, `rejected`, …) хранятся 180 дней для истории, без файлов.