Abschluss-Dokumentation V3.1: betrieb.md, Bedienanleitung, Freigabedokument

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/betrieb.md

@@ -425,7 +425,27 @@ Die Anwendung verwendet eine exklusive Lock-Datei, um parallele Instanzen zu ver
 Wenn bereits eine Instanz läuft, beendet sich die neue Instanz sofort mit Exit-Code `1`.
 
 Der Pfad der Lock-Datei ist über `runtime.lock.file` konfigurierbar.
-Ohne Konfiguration wird `pdf-umbenenner.lock` im Arbeitsverzeichnis verwendet.
+
+### Pfadauflösung der Lock-Datei
+
+| Pfadtyp | Verhalten |
+|---|---|
+| **Absoluter Pfad** | Wird direkt verwendet. Schlägt das Anlegen der Lock-Datei fehl, bricht der Start mit einer klaren Fehlermeldung ab – kein Fallback. |
+| **Relativer oder unkonfigurierter Pfad** | Zweistufige Auflösung: (1) relativ zum Verzeichnis der JAR-Datei (`CodeSource.getLocation()`), (2) Fallback auf das Benutzerverzeichnis (`user.home`). Erst wenn auch `user.home` fehlschlägt, bricht der Start ab. |
+
+Fehlende übergeordnete Verzeichnisse werden automatisch angelegt.
+
+Der tatsächlich verwendete absolute Pfad der Lock-Datei wird beim Start auf INFO-Level geloggt, z. B.:
+
+```
+Lock-Datei: C:\Users\Funny\Documents\pdf-umbenenner.lock
+```
+
+Diese Auflösungslogik gilt sowohl für den GUI- als auch für den headless Start.
+
+> **Empfehlung für den MSI-Betrieb:** Da das Installationsverzeichnis `C:\Program Files\`
+> schreibgeschützt ist, muss `runtime.lock.file` als absoluter Pfad auf ein beschreibbares
+> Verzeichnis zeigen (z. B. `C:/ProgramData/PDF KI Renamer/pdf-umbenenner.lock`).
 
 ---
 
@@ -435,11 +455,50 @@ Die SQLite-Datei enthält:
 
 - **Dokument-Stammsätze**: Gesamtstatus, Fehlerzähler, letzter Zieldateiname, Zeitstempel
 - **Versuchshistorie**: Jeder Verarbeitungsversuch mit Modell, Prompt-Identifikator,
-  KI-Rohantwort, Reasoning, Datum, Titel und Fehlerstatus
+  KI-Rohantwort, Reasoning, Datum, Titel, Fehlerstatus und Fehlerdetails
 
 Die Datenbank ist die führende Wahrheitsquelle für Bearbeitungsstatus und Nachvollziehbarkeit.
 Sie muss nicht manuell verwaltet werden – das Schema wird beim Start automatisch initialisiert.
 
+### Fehlerursache im Verlauf-Tab
+
+Verarbeitungsversuche mit Status `FAILED_FINAL`, `FAILED_RETRYABLE` oder
+`SKIPPED_FINAL_FAILURE` speichern eine nutzerverständliche Fehlerursache
+(`failure_details`). Diese wird im Verlauf-Tab im Detailbereich des jeweiligen
+Dokuments angezeigt. Ältere Einträge ohne Fehlerdetails zeigen einen Platzhaltertext.
+Fehlerdetails werden auf 1000 Zeichen begrenzt und enthalten keine rohen
+Provider-Meldungen oder API-Schlüssel.
+
+### Neue Datenbank anlegen
+
+Über den Menüpunkt **Datenbank → Neue Datenbank anlegen...** kann aus der GUI
+heraus eine neue, leere SQLite-Datenbank erstellt und sofort aktiviert werden,
+ohne die Anwendung neu zu starten.
+
+**Ablauf:**
+
+1. Dateidialog öffnet (Filter: `*.sqlite` und `*.db`); Zieldatei wählen oder eingeben.
+2. Sicherheitsprüfung: aktive und gewählte Datei werden normalisiert verglichen
+   (case-insensitive unter Windows). Bei Übereinstimmung erscheint eine Fehlermeldung.
+3. Bei bereits existierender Fremddatei: Bestätigungsdialog „Die Datei existiert bereits.
+   Überschreiben?"
+4. Neue SQLite-Datei wird als temporäre Datei erzeugt, Flyway führt alle Migrationsskripte
+   auf neuesten Stand aus, dann Verbindungstest.
+5. Nach erfolgreichem Test: atomarer Move zur Zieldatei.
+6. Aktive Datenbankverbindung der Anwendung wechselt zur neuen DB.
+7. Der Verlauf-Tab lädt neu und zeigt „Noch keine Verarbeitungen vorhanden."
+8. Die Statuszeile aktualisiert den DB-Pfad.
+
+> **Wichtig:** Die Konfigurationsdatei wird durch den Wechsel automatisch als geändert
+> markiert. **Konfiguration speichern**, damit die neue Datenbank beim nächsten Start
+> der Anwendung verwendet wird.
+
+**Fehlerfall:** Schlägt ein Schritt fehl, bleibt die bisherige Datenbank unverändert
+in Betrieb. Die temporäre Datei wird gelöscht. Ein Fehlerdialog erscheint.
+
+Der Menüpunkt ist nur aktiv, wenn kein Verarbeitungslauf läuft.
+Der headless Betrieb ist von dieser Funktion nicht betroffen.
+
 ---
 
 ## Build und Packaging