feat: finish the upload, playback, and test gaps from the docs

Quality upgrades, batch covers, staging preview, and resume after reload are in the queue. Loudness and crossfade work on web and Android, and the documented checks now have suites.

Co-authored-by: Cursor <cursoragent@cursor.com>

api/openapi.yaml

@@ -451,6 +451,35 @@ paths:
                 $ref: "#/components/schemas/UploadFilePage"
         default:
           $ref: "#/components/responses/Problem"
+  /api/v1/uploads/unseen:
+    get:
+      operationId: unseenUploadDecisions
+      tags: [uploads]
+      summary: Сколько решений по своим предложениям с прошлого визита (moderator, admin)
+      responses:
+        "200":
+          description: Число
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [count]
+                properties:
+                  count:
+                    type: integer
+                    minimum: 0
+        default:
+          $ref: "#/components/responses/Problem"
+  /api/v1/uploads/seen:
+    post:
+      operationId: markUploadsSeen
+      tags: [uploads]
+      summary: Отметить свои предложения просмотренными
+      responses:
+        "204":
+          description: Отмечено
+        default:
+          $ref: "#/components/responses/Problem"
   /api/v1/uploads/files/{id}:
     parameters:
       - $ref: "#/components/parameters/EntityId"
@@ -535,6 +564,65 @@ paths:
                 $ref: "#/components/schemas/UploadFile"
         default:
           $ref: "#/components/responses/Problem"
+  /api/v1/admin/uploads/files/{id}/stream:
+    get:
+      operationId: streamUpload
+      tags: [uploads]
+      security: []
+      summary: Прослушать файл из staging (подпись, как у стрима трека)
+      description: Ссылку даёт `stream_url` файла очереди. Range поддерживается.
+      parameters:
+        - $ref: "#/components/parameters/EntityId"
+        - name: exp
+          in: query
+          required: true
+          schema:
+            type: integer
+            format: int64
+        - name: sig
+          in: query
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Аудио из staging
+          content:
+            audio/*:
+              schema:
+                type: string
+                format: binary
+        default:
+          $ref: "#/components/responses/Problem"
+  /api/v1/admin/uploads/batches/{id}:
+    parameters:
+      - $ref: "#/components/parameters/EntityId"
+    patch:
+      operationId: updateUploadBatch
+      tags: [uploads]
+      summary: Правка метаданных и обложки на всю пачку (admin)
+      description: Исполнитель, альбом и год применяются к файлам в pending_review и import_failed. Обложка встраивается при импорте.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UploadBatchPatch"
+      responses:
+        "200":
+          description: Обновлённые файлы пачки
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [items]
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/UploadFile"
+        default:
+          $ref: "#/components/responses/Problem"
   /api/v1/admin/uploads/review:
     post:
       operationId: reviewUploads
@@ -1620,6 +1708,9 @@ components:
                 type: string
               duration_ms:
                 type: integer
+              album:
+                type: string
+                maxLength: 500
     UploadPrecheckResult:
       type: object
       required: [files]
@@ -1733,7 +1824,7 @@ components:
           nullable: true
     UploadFile:
       type: object
-      required: [id, batch_id, batch_comment, author, status, original_name, client_rel_path, size_bytes, received_bytes, format, codec, bitrate, sample_rate, bit_depth, duration_ms, tags, metadata, metadata_edited, matched_artist_id, matched_album_id, duplicate_of_track_id, duplicate_level, possible_duplicate, target_source_id, target_rel_path, status_reason, reviewed_at, created_at, updated_at, tus_url]
+      required: [id, batch_id, batch_comment, author, status, original_name, client_rel_path, size_bytes, received_bytes, format, codec, bitrate, sample_rate, bit_depth, duration_ms, tags, metadata, metadata_edited, matched_artist_id, matched_album_id, duplicate_of_track_id, duplicate_level, possible_duplicate, quality_upgrade, target_source_id, target_rel_path, status_reason, reviewed_at, created_at, updated_at, tus_url, stream_url]
       properties:
         id:
           type: string
@@ -1807,6 +1898,9 @@ components:
           enum: [sha256, metadata, fingerprint, null]
         possible_duplicate:
           type: boolean
+        quality_upgrade:
+          type: boolean
+          description: Тот же трек, но лучшего качества — ждёт решения, если включён allow_quality_upgrade
         target_source_id:
           type: string
           format: uuid
@@ -1832,6 +1926,10 @@ components:
           type: string
           nullable: true
           description: Только автору и пока файл в статусе uploading
+        stream_url:
+          type: string
+          nullable: true
+          description: Подписанная ссылка прослушивания из staging; null, если файла уже нет
     UploadFilePage:
       type: object
       required: [items, next_cursor]
@@ -1851,6 +1949,23 @@ components:
         target_source_id:
           type: string
           format: uuid
+    UploadBatchPatch:
+      type: object
+      description: Пустые поля не меняют файлы. cover_base64 null снимает обложку пачки.
+      properties:
+        artist:
+          type: string
+          maxLength: 500
+        album:
+          type: string
+          maxLength: 500
+        year:
+          type: integer
+          nullable: true
+        cover_base64:
+          type: string
+          nullable: true
+          description: JPEG, PNG или WebP, не больше 8 МБ после декодирования
     UploadReviewRequest:
       type: object
       required: [file_ids, decision]
@@ -1890,7 +2005,7 @@ components:
                   - $ref: "#/components/schemas/Problem"
     UploadSettings:
       type: object
-      required: [queue_limit_bytes, per_user_limit_bytes, max_file_bytes, default_source_id]
+      required: [queue_limit_bytes, per_user_limit_bytes, max_file_bytes, default_source_id, allow_quality_upgrade]
       properties:
         queue_limit_bytes:
           type: integer
@@ -1906,6 +2021,9 @@ components:
           type: string
           format: uuid
           nullable: true
+        allow_quality_upgrade:
+          type: boolean
+          description: Тот же трек в лучшем качестве идёт на рассмотрение, а не в дубли
     UploadSettingsPatch:
       type: object
       description: Лимит на пользователя и хранилище по умолчанию передаются всегда (null — выключить / не задано).
@@ -1929,6 +2047,8 @@ components:
           format: uuid
           nullable: true
           description: null — без хранилища по умолчанию
+        allow_quality_upgrade:
+          type: boolean
     HealthStatus:
       type: object
       required: [status]
@@ -2036,7 +2156,7 @@ components:
           description: Где в топбаре веба поиск (по умолчанию center)
         search_collapse:
           type: boolean
-          description: Сворачивать поиск в кнопку с лупой без фокуса (по умолчанию true)
+          description: Сворачивать поиск в кнопку с лупой без фокуса (по умолчанию false)
         home_activities:
           type: boolean
           description: Показывать на главной веба выбор занятия (по умолчанию true)