1.0.0-rc1 Docs

docs/gui/settings.md

@@ -1,107 +1,167 @@
 # Settings
 
-Die Seite `Settings` steuert alle Betriebsparameter von Ripster: Pfade, Tools, Queue-Limits, Metadatenquellen, Automatisierung.
+Die Seite `Settings` ist das zentrale Kontrollpanel für Laufzeitverhalten, Automatisierung und Expertenfunktionen.
 
 ## Tab-Überblick
 
-| Tab | Hauptzweck |
+| Tab | Zweck |
 |---|---|
-| `Konfiguration` | globale und profilspezifische Laufzeitsettings |
-| `Scripte` | einzelne Skripte verwalten und testen |
-| `Skriptketten` | mehrstufige Abläufe aus Skript/Warten |
-| `Encode-Presets` | wiederverwendbare HandBrake-Profile für Review |
-| `Cronjobs` | zeitgesteuerte Ausführung von Skript/Kette |
+| `Konfiguration` | Alle fachlichen Settings (Pfade, Tools, Laufwerk, Metadaten, Monitoring, Benachrichtigungen, Converter) |
+| `Scripte` | Einzelne Bash-Skripte pflegen, testen und sortieren |
+| `Skriptketten` | Mehrstufige Sequenzen aus `Skript` und `Warten` bauen und testen |
+| `Encode-Presets` | Benutzer-Presets und Standard-Zuordnungen für Blu-ray/DVD-Workflows |
+| `Cronjobs` | Zeitgesteuerte Jobs auf Basis Skript/Skriptkette |
 
 ## Tab `Konfiguration`
 
-### Bedienprinzip
+### Bedienlogik
 
-1. Werte ändern.
-2. `Änderungen speichern`.
-3. erst danach sind Werte für neue Aktionen wirksam.
+1. Felder ändern.
+2. `Änderungen speichern` klicken.
+3. Erst dann werden Änderungen persistiert und für neue Pipeline-Schritte wirksam.
 
-Zusätzliche Bedienhilfen:
+Aktionen in der Toolbar:
 
-- `Neu laden` verwirft lokale Formzustände
-- `Änderungen verwerfen` setzt auf zuletzt gespeicherten Stand
-- `PushOver Test` validiert Benachrichtigungszugang sofort
+- `Änderungen speichern`: schreibt nur geänderte Felder als Bulk-Update.
+- `Änderungen verwerfen`: setzt den Formularzustand auf zuletzt geladen/zum Server gespeicherten Stand zurück.
+- `Neu laden`: lädt Kategorien + Werte erneut vom Backend.
+- `PushOver Test`: sendet eine Testnachricht mit aktuellen PushOver-Werten.
+- `Coverarts prüfen`: startet die manuelle Coverart-Recovery.
+- `Expertenmodus`: wird sofort gespeichert (nicht Teil des normalen Bulk-Speicherns).
 
-### Was wirkt unmittelbar, was erst bei neuem Job?
+### Wichtige UI-Verhalten
 
-- Queue-/Parallelität wirkt auf neue Queue-Entscheidungen und Pump-Läufe.
-- Tool-/Pfad-/Template-Änderungen wirken vollständig auf neu gestartete Schritte.
-- Bereits laufende Prozesse übernehmen Änderungen in der Regel nicht rückwirkend.
+- Jede Einstellung zeigt `Gespeichert` oder `Ungespeichert` direkt am Feld.
+- Pflichtfelder sind mit `*` markiert.
+- Bei Validierungsfehlern wird pro Feld ein Fehlertext angezeigt und Speichern blockiert.
+- Tool-Kommandos (`makemkv_command`, `mediainfo_command`, `handbrake_command`, `ffmpeg_command`, `ffprobe_command`, `cdparanoia_command`, `mkvmerge_command`) sind im Formular schreibgeschützt markiert.
+- Einige Felder sind abhängig vom Expertenmodus sichtbar.
 
-### Welche Bereiche im Alltag kritisch sind
+### Kategorie `Pfade`: Besondere Interaktion
 
-| Bereich | Kritisch für |
-|---|---|
-| `Pfade` | wo RAW, finale Ausgaben, Converter/Audiobook-Dateien landen |
-| `Tools` | ob Analyze/Rip/Encode ausführbar sind |
-| `Metadaten` | Film-/Serienzuordnung und Episode-Mapping |
-| `Queue-Limits` | Durchsatz und Reihenfolgeverhalten |
-| `Monitoring` | Sichtbarkeit von Last und Speicherengpässen |
-| `Benachrichtigungen` | PushOver-Ereignisse je Pipelinephase |
+Die Pfad-Kategorie hat eine eigene Darstellung:
+
+- Tabelle `Effektive Pfade`: zeigt die aktuell tatsächlich aufgelösten Laufzeitpfade inkl. Fallbacks.
+- Accordion je Bereich (`Blu-ray`, `DVD`, `CD / Audio`, `Audiobook`, `Converter`, `Downloads`, optional `Externe Speicher`, `Logs`).
+- Für Pfadfelder mit Owner-Pendant (`*_owner`) erscheint direkt darunter das Feld `Eigentümer (user:gruppe)`.
+- Owner-Felder sind deaktiviert, solange der zugehörige Pfad leer ist.
+
+### Spezial-Editoren in der Konfiguration
+
+- `drive_devices`: JSON-Array wird über UI-Editor gepflegt (Pfad + MakeMKV-Index je Laufwerk).
+- `external_storage_paths`: Liste aus `Name` + `Pfad` (für Anzeige freier externer Speicher).
+- `converter_scan_extensions`: Checkbox-Raster der erlaubten Endungen; mindestens eine Endung muss aktiv bleiben.
+- `makemkv_registration_key`: zusätzlicher Betakey-Hinweis mit `übernehmen`-Button.
+
+### Laufwerks-Infobox innerhalb `Laufwerk`
+
+In der Kategorie `Laufwerk` wird eine Live-Tabelle erkannter optischer Laufwerke angezeigt:
+
+- `Neu einlesen` lädt Laufwerksinfos neu.
+- Im Expertenmodus: `Freigeben` pro Laufwerk und `Alle Laufwerke freigeben`.
 
 ## Tab `Scripte`
 
 Funktionen:
 
-- anlegen, bearbeiten, löschen
-- testen (`Test`)
-- sortieren
+- Skript anlegen (Inline-Editor)
+- Skript bearbeiten (Dialog)
+- Skript löschen (mit Bestätigung)
+- Skript testen
+- Reihenfolge per Drag-and-Drop ändern
 
-Testausführung liefert:
+Testergebnis enthält:
 
+- Erfolg/Fehler
 - Exit-Code
+- Timeout-Info
 - Dauer
 - stdout/stderr
 
-Wichtig:
-
-- Nur erfolgreiche Skripte sollten in produktive Pre-/Post-Listen übernommen werden.
-
 ## Tab `Skriptketten`
 
-Ketten bestehen aus Schritten:
+Skriptketten bestehen aus Schritten:
 
 - `Skript`
-- `Warten`
+- `Warten (Sekunden)`
 
-Typischer Einsatz:
+Funktionen:
 
-- externe Hooks vor/nach Encode
-- gestaffelte Abläufe mit Pausen
+- Ketten anlegen/bearbeiten/löschen
+- Reihenfolge der Ketten per Drag-and-Drop
+- Kette testen
+- Schritte in der Kette per Drag-and-Drop neu anordnen
 
-In der Queue erscheinen Ketten als eigene Einträge und werden dort ausgeführt.
+Im Ketteneditor:
+
+- linke Palette (`Systemblöcke`, `Scripte`)
+- rechte Canvas mit Drop-Zonen
+- pro Warte-Schritt konfigurierbare Sekunden
 
 ## Tab `Encode-Presets`
 
-Ein Preset bündelt:
+Bereiche:
 
-- optionales HandBrake-Preset (`-Z`)
-- optionale Extra-Args
-- Medienziel (Universell/Blu-ray/DVD/Sonstiges)
+1. `Standard-Zuordnungen` (Slots)
+2. `Preset-Liste` (CRUD)
 
-Im Ripper-Review kannst du Presets pro Job auswählen, statt Parameter jedes Mal neu zu setzen.
+### Standard-Zuordnungen
+
+Es gibt vier persistente Slots:
+
+- `bluray_movie`
+- `bluray_series`
+- `dvd_movie`
+- `dvd_series`
+
+Die Auswahl ist medientyp-kompatibel gefiltert. Nicht kompatible oder fehlende bereits gespeicherte IDs werden weiterhin sichtbar gemacht, damit bestehende Zuordnungen nachvollziehbar bleiben.
+
+### Preset-Inhalt
+
+Ein Preset umfasst:
+
+- Name
+- Medientyp (`all`, `bluray`, `dvd`)
+- HandBrake-Preset (`-Z`)
+- Extra Args
+- optionale Beschreibung
 
 ## Tab `Cronjobs`
 
 Funktionen:
 
-- Cronjob anlegen und bearbeiten
-- Quelle wählen (`Skript` oder `Skriptkette`)
-- Cron-Ausdruck prüfen
+- Cronjob erstellen/bearbeiten/löschen
+- Debounced Validierung des Cron-Ausdrucks
+- Quelle wählen: `Skript` oder `Skriptkette`
+- Aktiv- und PushOver-Toggle je Job
 - `Jetzt ausführen`
-- Job-Logs ansehen
-- Aktivierung/Pushover toggeln
+- Lauf-Logs öffnen
 
-Empfehlung:
+Die Seite zeigt zusätzlich Live-Status laufender Cron-Aktivitäten (Runtime Activities).
 
-1. Skript/Kette manuell testen.
-2. Dann Cron aktivieren.
-3. Erste automatische Läufe aktiv im Runtime-Status kontrollieren.
+## Expertenbereich: Activation Bytes Cache
 
-## Verbindung zur Einstellungsreferenz
+Der Activation-Bytes-Block wird nur im Expertenmodus angezeigt und nur wenn Einträge vorhanden sind.
 
-Die vollständige Wirkung jeder einzelnen Einstellung steht in [Einstellungsreferenz](../configuration/settings-reference.md).
+Er zeigt:
+
+- AAX-Checksum
+- Activation Bytes
+- Speicherzeitpunkt
+
+## Validierungshinweise für Template-Felder
+
+Template-Felder akzeptieren nur:
+
+- Buchstaben/Ziffern
+- Leerzeichen
+- `_` und `-`
+- Platzhalter in `{...}` bzw. `${...}`
+- `/` für Ordnertrennung
+
+Nicht erlaubt sind z. B. unvollständige geschweifte Klammern oder sonstige Sonderzeichen.
+
+## Siehe auch
+
+- [Einstellungsreferenz](../configuration/settings-reference.md)
+- [Ripper](ripper.md)