0.14.0-4 Docs

2026-04-21 14:52:30 +00:00
parent c27a81cdb1
commit ccd6c3ab2a
29 changed files with 999 additions and 691 deletions
@@ -1,53 +1,58 @@
 # Downloads

-Die Downloads-Seite ermöglicht es, Ausgabedateien aus abgeschlossenen Jobs als ZIP-Archiv herunterzuladen.
+Auf `Downloads` werden ZIP-Archive für Historie-Artefakte erstellt und bereitgestellt.

---
+## Was heruntergeladen werden kann

-## Überblick
+Ein Download-Eintrag referenziert immer einen Historie-Job und genau ein Ziel:

-Jobs, die in der Historie abgeschlossen sind, können in die Download-Queue eingereiht werden. Ripster erstellt daraus ein ZIP-Archiv, das direkt im Browser heruntergeladen werden kann.
+- `RAW`
+- `Output`

---
+Erzeugt wird ein ZIP-Archiv im Download-Verzeichnis des Backends.

-## Download-Queue
+## Statusmodell

-Die Queue zeigt alle aktuellen Download-Einträge mit ihrem Status:
-
-| Status | Beschreibung |
+| Status | Bedeutung |
 |---|---|
-| **Ausstehend** | In der Queue, ZIP-Erstellung noch nicht gestartet |
-| **Wird verarbeitet** | ZIP-Archiv wird gerade erstellt |
-| **Bereit** | ZIP fertig, Download-Button verfügbar |
-| **Fehlgeschlagen** | Fehler bei der ZIP-Erstellung |
+| `queued` | Eintrag erstellt, wartet auf Verarbeitung |
+| `processing` | ZIP wird gerade gebaut |
+| `ready` | Archiv fertig, Download-Link aktiv |
+| `failed` | Erzeugung oder Zugriff fehlgeschlagen |

---
+## Eintrag anlegen

-## Download einreihen
+Startpunkt ist die `Historie`:

-Downloads können über die **Historie** eingereiht werden:
+1. Job öffnen.
+2. Download einreihen.
+3. Ziel (`RAW` oder `Output`) wählen.
+4. Status in `Downloads` verfolgen.

-1. Job in der Historie öffnen
-2. **Download einreihen** wählen
-3. Ziel auswählen: `RAW-Dateien` oder `Ausgabedateien`
-4. Den Eintrag in der Downloads-Queue verfolgen
+## Wichtige Laufzeitdetails

---
+- Wenn bereits ein passendes, aktuelles Archiv existiert, kann der Eintrag wiederverwendet werden.
+- Nach Backend-Neustart werden unterbrochene `queued`/`processing`-Einträge geprüft und fortgesetzt.
+- Fehlt eine erwartete ZIP-Datei bei `ready`, wird der Eintrag auf `failed` gesetzt.

-## Download starten
+## Download auslösen

-Sobald der Status **Bereit** angezeigt wird, kann die ZIP-Datei mit dem Download-Button heruntergeladen werden.
+Bei Status `ready`:

-ZIP-Dateinamen folgen dem Muster: `Job_<id>_<target>.zip`
+- Download-Button lädt die ZIP direkt aus `/api/downloads/:id/file`.

---
+## Einträge entfernen

-## Einträge löschen
+`Löschen` entfernt:

-Abgeschlossene oder fehlerhafte Einträge können einzeln gelöscht werden. Die dazugehörige ZIP-Datei wird dabei ebenfalls vom Server entfernt.
+- Queue-Metadaten
+- zugehörige Archivdatei

---
+Nicht erlaubt:

-## Echtzeit-Updates
+- Löschen während `queued`/`processing`

-Die Downloads-Seite aktualisiert sich automatisch per WebSocket (`DOWNLOADS_UPDATED`). Statusänderungen (z. B. von `Wird verarbeitet` zu `Bereit`) werden ohne Seiten-Reload angezeigt.
+## Echtzeitaktualisierung
+
+Die Seite reagiert auf `DOWNLOADS_UPDATED` per WebSocket.
+Dadurch sind Statuswechsel ohne Reload sichtbar.