0.12.0-17 Misc fixes

2026-03-30 19:15:23 +00:00
parent 5284dd2a43
commit c67ac593de
29 changed files with 1596 additions and 117 deletions
@@ -0,0 +1,290 @@
+# Converter API
+
+Endpunkte für den Datei-Converter: Datei-Explorer, Upload, Job-Verwaltung.
+
+Basis-Pfad: `/api/converter`
+
+---
+
+## Scan & Explorer
+
+### `GET /api/converter/tree`
+
+Vollständiger Verzeichnisbaum des `converter_raw_dir` (FS-basiert, keine DB).
+
+**Response:**
+
+```json
+{
+  "tree": [
+    {
+      "name": "filme",
+      "relPath": "filme",
+      "isDir": true,
+      "children": [
+        {
+          "name": "film.mkv",
+          "relPath": "filme/film.mkv",
+          "isDir": false,
+          "size": 10485760
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+### `GET /api/converter/browse?parent=relPath`
+
+DB-basierter Datei-Explorer. Gibt Einträge für einen Unterordner zurück.
+
+**Query-Parameter:**
+
+| Parameter | Typ | Beschreibung |
+|---|---|---|
+| `parent` | string | Relativer Pfad zum Unterordner (leer = Root) |
+
+**Response:**
+
+```json
+{
+  "entries": [
+    {
+      "id": 1,
+      "rel_path": "filme/film.mkv",
+      "is_dir": false,
+      "size": 10485760,
+      "job_id": null
+    }
+  ],
+  "rawDir": "/data/output/converter-raw"
+}
+```
+
+---
+
+### `POST /api/converter/scan`
+
+Manuellen Scan des `converter_raw_dir` auslösen. Aktualisiert `converter_scan_entries` in der DB.
+
+**Response:**
+
+```json
+{ "result": { "added": 3, "removed": 1 } }
+```
+
+---
+
+## Jobs erstellen
+
+### `POST /api/converter/jobs/from-selection`
+
+Jobs aus im Datei-Explorer ausgewählten Dateien erstellen.
+
+**Body:**
+
+```json
+{
+  "relPaths": ["filme/film.mkv", "musik/track.flac"],
+  "audioMode": "individual"
+}
+```
+
+| Feld | Typ | Beschreibung |
+|---|---|---|
+| `relPaths` | string[] | Relative Pfade der ausgewählten Dateien |
+| `audioMode` | string | `individual` (ein Job pro Datei) oder `shared` (ein gemeinsamer Job) |
+
+**Response:**
+
+```json
+{ "jobs": [{ "id": 42, "status": "READY_TO_START" }] }
+```
+
+---
+
+### `POST /api/converter/create-jobs`
+
+Jobs aus DB-Scan-Einträgen erstellen.
+
+**Body:**
+
+```json
+{
+  "entries": [
+    { "relPath": "filme/film.mkv", "converterMediaType": "video" }
+  ]
+}
+```
+
+---
+
+### `POST /api/converter/upload`
+
+Dateien hochladen (Multipart, max. 50 Dateien).
+
+**Form-Felder:**
+
+| Feld | Typ | Beschreibung |
+|---|---|---|
+| `files` | File[] | Hochzuladende Dateien |
+| `folderName` | string | (Optional) Ziel-Unterordner |
+
+**Response:**
+
+```json
+{
+  "folders": [{ "folderRelPath": "upload-2026-03-30", "fileCount": 2 }]
+}
+```
+
+---
+
+## Job-Verwaltung
+
+### `GET /api/converter/jobs`
+
+Alle Converter-Jobs zurückgeben.
+
+**Response:**
+
+```json
+{ "jobs": [{ "id": 42, "status": "READY_TO_START", "title": "film.mkv" }] }
+```
+
+---
+
+### `GET /api/converter/jobs/:jobId`
+
+Einzelnen Converter-Job abrufen.
+
+---
+
+### `POST /api/converter/jobs/:jobId/config`
+
+Konfigurationsentwurf für einen Job speichern (persistiert in `encode_plan_json`).
+
+**Body:** Partielles Konfig-Objekt (Ausgabeformat, Presets, Metadaten, Track-Auswahl).
+
+---
+
+### `POST /api/converter/jobs/:jobId/assign-files`
+
+Dateien einem bestehenden (noch nicht gestarteten) Job hinzufügen.
+
+**Body:**
+
+```json
+{ "relPaths": ["musik/track2.flac"] }
+```
+
+---
+
+### `POST /api/converter/jobs/:jobId/remove-file`
+
+Datei aus einem Job entfernen (per relativer Pfad).
+
+**Body:**
+
+```json
+{ "relPath": "musik/track2.flac" }
+```
+
+---
+
+### `POST /api/converter/jobs/:jobId/remove-input`
+
+Datei aus einem Job entfernen (per absolutem Eingabepfad).
+
+**Body:**
+
+```json
+{ "inputPath": "/data/output/converter-raw/musik/track2.flac" }
+```
+
+---
+
+### `POST /api/converter/jobs/:jobId/start`
+
+Job mit finaler Konfiguration starten.
+
+**Body:**
+
+```json
+{
+  "converterMediaType": "video",
+  "outputFormat": "mkv",
+  "userPreset": "H.264 MKV 1080p30",
+  "trackSelection": {},
+  "handBrakeTitleId": 1,
+  "audioFormatOptions": {}
+}
+```
+
+---
+
+### `POST /api/converter/jobs/:jobId/cancel`
+
+Laufenden Job abbrechen.
+
+---
+
+### `DELETE /api/converter/jobs/:jobId`
+
+Job aus der DB löschen.
+
+---
+
+## Datei-Operationen
+
+Alle Datei-Operationen arbeiten direkt auf dem Dateisystem (ohne DB-Aktualisierung). Ein anschließender Scan-Aufruf synchronisiert die DB.
+
+### `DELETE /api/converter/files`
+
+Datei oder Ordner löschen.
+
+**Body:**
+
+```json
+{ "relPath": "filme/film.mkv" }
+```
+
+---
+
+### `POST /api/converter/files/rename`
+
+Datei oder Ordner umbenennen.
+
+**Body:**
+
+```json
+{ "relPath": "filme/film.mkv", "newName": "film-neu.mkv" }
+```
+
+---
+
+### `POST /api/converter/files/move`
+
+Datei oder Ordner verschieben.
+
+**Body:**
+
+```json
+{ "relPath": "filme/film.mkv", "targetParentRelPath": "archiv" }
+```
+
+`targetParentRelPath = ""` verschiebt in das Root-Verzeichnis.
+
+---
+
+### `POST /api/converter/files/folder`
+
+Neuen Ordner anlegen.
+
+**Body:**
+
+```json
+{ "parentRelPath": "filme", "name": "neu" }
+```
@@ -0,0 +1,143 @@
+# Downloads API
+
+Endpunkte für die Download-Queue. Ausgabedateien aus der Job-Historie können als ZIP heruntergeladen werden.
+
+Basis-Pfad: `/api/downloads`
+
+---
+
+## `GET /api/downloads`
+
+Liste aller Download-Einträge plus Zusammenfassung.
+
+**Response:**
+
+```json
+{
+  "items": [
+    {
+      "id": "dl-42-raw",
+      "jobId": 42,
+      "target": "raw",
+      "status": "ready",
+      "archiveName": "Job_42_raw.zip",
+      "outputPath": null,
+      "createdAt": "2026-03-30T10:00:00.000Z",
+      "updatedAt": "2026-03-30T10:01:00.000Z",
+      "errorMessage": null
+    }
+  ],
+  "summary": {
+    "total": 3,
+    "pending": 1,
+    "processing": 0,
+    "ready": 1,
+    "failed": 1
+  }
+}
+```
+
+**Status-Werte:**
+
+| Status | Beschreibung |
+|---|---|
+| `pending` | In der Queue, noch nicht gestartet |
+| `processing` | ZIP wird gerade erstellt |
+| `ready` | ZIP fertig, Download verfügbar |
+| `failed` | Fehler bei der Erstellung |
+
+---
+
+## `GET /api/downloads/summary`
+
+Nur die Zusammenfassung der Download-Queue (ohne Item-Liste).
+
+**Response:**
+
+```json
+{
+  "summary": {
+    "total": 3,
+    "pending": 1,
+    "processing": 0,
+    "ready": 1,
+    "failed": 1
+  }
+}
+```
+
+---
+
+## `POST /api/downloads/history/:jobId`
+
+Job-Ausgabe in die Download-Queue einreihen.
+
+**Parameter:**
+
+| Parameter | Typ | Beschreibung |
+|---|---|---|
+| `jobId` | number | ID des Jobs in der Historie |
+
+**Body:**
+
+```json
+{
+  "target": "raw",
+  "outputPath": null
+}
+```
+
+| Feld | Typ | Default | Beschreibung |
+|---|---|---|---|
+| `target` | string | `raw` | `raw` (RAW-Dateien) oder `movie` (Ausgabedateien) |
+| `outputPath` | string | `null` | Optionaler expliziter Ausgabepfad |
+
+**Response (201 Created):**
+
+```json
+{
+  "created": true,
+  "id": "dl-42-raw",
+  "status": "pending",
+  "summary": { "total": 1, "pending": 1, "processing": 0, "ready": 0, "failed": 0 }
+}
+```
+
+Ist der Eintrag bereits vorhanden, wird `201` durch `200` ersetzt und `created: false` zurückgegeben.
+
+---
+
+## `GET /api/downloads/:id/file`
+
+Fertige ZIP-Datei herunterladen.
+
+**Parameter:**
+
+| Parameter | Typ | Beschreibung |
+|---|---|---|
+| `id` | string | Download-ID (z. B. `dl-42-raw`) |
+
+**Response:** Datei-Download (`Content-Disposition: attachment`).
+
+Schlägt fehl mit `404`, wenn kein Download-Eintrag mit dieser ID existiert oder die Datei noch nicht bereit ist.
+
+---
+
+## `DELETE /api/downloads/:id`
+
+Download-Eintrag löschen (auch fertige ZIP-Dateien werden vom Dateisystem entfernt).
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "summary": { "total": 2, "pending": 0, "processing": 0, "ready": 2, "failed": 0 }
+}
+```
+
+---
+
+## WebSocket
+
+Statusänderungen werden über `DOWNLOADS_UPDATED` in Echtzeit gemeldet. Vollständige Dokumentation: [WebSocket Events](websocket.md#downloads_updated).
@@ -54,11 +54,35 @@ API-Prefix: `/api`

    [:octicons-arrow-right-24: Cron API](crons.md)

-   :material-lightning-bolt: **WebSocket Events**
+-   :material-swap-horizontal: **Converter API**

    ---

-    Pipeline-, Queue-, Disk-, Settings-, Cron- und Monitoring-Events.
+    Datei-Explorer, Upload, Job-Verwaltung für den Converter.
+
+    [:octicons-arrow-right-24: Converter API](converter.md)
+
+-   :material-download: **Downloads API**
+
+    ---
+
+    Download-Queue für Ausgabedateien aus der Job-Historie.
+
+    [:octicons-arrow-right-24: Downloads API](downloads.md)
+
+-   :material-lightning-bolt: **Runtime Activities API**
+
+    ---
+
+    Laufende und abgeschlossene Aktivitäten (Skripte, Ketten, Cron, Tasks).
+
+    [:octicons-arrow-right-24: Runtime Activities](runtime-activities.md)
+
+-   :material-websocket: **WebSocket Events**
+
+    ---
+
+    Pipeline-, Queue-, Disk-, Settings-, Cron-, Converter- und Download-Events.

    [:octicons-arrow-right-24: WebSocket](websocket.md)

@@ -242,6 +242,48 @@ Wird ausgelöst, wenn eine Aktivität gestartet, aktualisiert oder abgeschlossen

 Vollständige Feldbeschreibung: [Runtime Activities API](runtime-activities.md).

+### CONVERTER_SCAN_UPDATE
+
+Wird nach einem Scan des Converter-Eingangsordners gesendet (manuell oder per Polling).
+
+```json
+{
+  "type": "CONVERTER_SCAN_UPDATE",
+  "payload": {
+    "entryCount": 12
+  }
+}
+```
+
+### DOWNLOADS_UPDATED
+
+Wird bei jeder Statusänderung in der Download-Queue gesendet.
+
+```json
+{
+  "type": "DOWNLOADS_UPDATED",
+  "payload": {
+    "reason": "ready",
+    "item": {
+      "id": "dl-1",
+      "jobId": 42,
+      "status": "ready",
+      "archiveName": "Job_42_movie.zip",
+      "createdAt": "2026-03-30T10:00:00.000Z"
+    },
+    "summary": {
+      "total": 3,
+      "pending": 1,
+      "processing": 0,
+      "ready": 1,
+      "failed": 1
+    }
+  }
+}
+```
+
+Mögliche `reason`-Werte: `queued`, `processing`, `ready`, `failed`, `deleted`.
+
 ---

 ## Reconnect-Verhalten