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

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 07:45:32 +02:00
parent 735b3af09f
commit eae2472b7e
3 changed files with 370 additions and 17 deletions
@@ -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
@@ -0,0 +1,166 @@
+# Freigabedokument V3.1 – PDF-Umbenenner
+
+## Geprüfter Stand
+
+- Git-Branch: `main`
+- Versionsnummer: `3.1.[BUILD]`
+- Freigabedatum: 2026-05-06
+- **Status:** freigegeben
+
+---
+
+## Zielsetzung von V3.1
+
+V3.1 ist der konsequente Nachschlag zu V3.0: Was der Produkttest aufgedeckt hat,
+wird bereinigt. Kein großes Architektur-Feature, kein neues Maven-Modul –
+gezielter UX-Schliff und Robustheit in drei Schwerpunkten:
+
+1. **UX-Polishing** – sichtbare Schwächen aus dem V3.0-Produkttest behoben
+   (#77, #80, #81, #83, #84, #88, #91)
+2. **Verlauf-Tab reifen lassen** – Suche, Mehrfachauswahl, DB-Neuanlage
+   (#82, #86, #87)
+3. **Quick Win** – Mausrad-Zoom im PDF-Viewer als wertvoller Gebrauchskomfort
+   (#32)
+
+Die fachliche Kernverarbeitung des PDF-Umbenenners bleibt vollständig unverändert.
+Hexagonale Architektur, Modulstruktur, headless-Betrieb, `.properties`-
+Konfigurationswahrheit und Flyway-DB-Evolution bleiben unangetastet.
+
+---
+
+## Umgesetzte Issues
+
+| # | Kategorie | Beschreibung |
+|---|---|---|
+| #32 | GUI | Strg+Mausrad-Zoom in der PDF-Vorschau: Delta-Akkumulation für Trackpad-Kompatibilität, ScrollEvent bei Strg immer konsumiert, Zoom 10–500 %, Viewport-Mitte bleibt beim Zoom stabil, Fit-to-Width-Modus nach manuellem Zoom verlassen; Grab & Pan mit Handcursor im vergrößerten Zustand |
+| #77 | UX | Vollständige Bestandsaufnahme aller interaktiven Elemente auf allen Tabs; fehlende Tooltips auf allen vier Tabs ergänzt; neue Konstanten ausschließlich in `GuiTooltipTexts`; TableColumn-Header über Column-Graphic-Pattern mit Label und Tooltip (kein Skin-/Lookup-Hack) |
+| #80 | UX | Dirty-Indikator für den Konfigurations-Tab: Asterisk im Tab-Titel bei echter Nutzeränderung gegenüber Baseline-Snapshot; `loadingInProgress`-Flag verhindert unechte Dirty-State-Auslösung durch programmgesteuertes Laden; Bestätigungsdialog beim Verlassen mit ungespeicherten Änderungen; Kopplung mit DB-Pfad-Wechsel aus #87 |
+| #81 | UX | Status-ComboBox und Versuche-Tabelle zeigen lesbare deutsche Anzeigetexte statt Enum-Rohnamen; alle acht Statuswerte über `ProcessingStatusPresentation` abgebildet; Status-ComboBox mit „Alle Status" als GUI-internem Null-Filter; DB-Queries intern weiterhin mit Enum-Namen |
+| #82 | GUI | Live-Filter im Verlauf-Tab: 300 ms Debounce-Timer, Generation-Counter für Race-Condition-Schutz, veraltete Worker-Ergebnisse werden verworfen; Such-Button und Enter starten Suche sofort; Auswahl nach jeder neuen Suche vollständig geleert |
+| #83 | UX | Leere KI-Begründung im Detailbereich zeigt `promptText`-Platzhalter statt leerem Feld; kein Vermischen von Nutzdaten und UI-Platzhaltertext; TextArea bleibt sichtbar |
+| #84 | Bug | Aktionsbuttons im Verlauf-Tab werden nach Laufende ereignisgetrieben reaktiviert – unabhängig vom Terminierungsgrund (Erfolg, Fehlerabbruch, Nutzerabbruch, Leerlauf); kein manueller Workaround notwendig |
+| #86 | GUI | Mehrfachauswahl im Verlauf-Tab: `SelectionMode.MULTIPLE`, Strg+A nur bei Tabellenfokus (kein Konflikt mit Suchfeld), Schlüssel-Snapshot vor Worker-Thread-Start, Bulk-Reset und Bulk-Delete mit Bestätigungsdialog und Partial-Success-Zusammenfassung; Detailbereich zeigt Platzhalter bei Mehrfachauswahl |
+| #87 | GUI | Neuer Menüpunkt „Datenbank → Neue Datenbank anlegen...": atomarer Ablauf via Temp-Datei, Flyway auf neuesten Schema-Stand, Verbindungstest, atomarer Move mit `ATOMIC_MOVE + REPLACE_EXISTING`; normalisierter case-insensitiver Pfadvergleich; DB-Busy-Sperre; Konfig-Tab wechselt in Dirty-State; Hinweismeldung nach Wechsel |
+| #88 | UX | Fehlerursache für `FAILED_FINAL`, `FAILED_RETRYABLE` und `SKIPPED_FINAL_FAILURE` im Verlauf-Tab sichtbar; Flyway-Migration ergänzt Spalte `failure_details` in `processing_attempt`; Begrenzung auf 1000 Zeichen mit „…"-Kürzung vor Persistierung; keine rohen Provider-Meldungen oder API-Schlüssel persistiert; NULL-Einträge zeigen `promptText`-Platzhalter |
+| #91 | Robustheit | Lock-File-Pfadauflösung: absoluter Pfad direkt ohne Fallback (Abbruch bei Fehler); relativer oder unkonfigurierter Pfad zweistufig (JAR-Verzeichnis → `user.home` → Abbruch); fehlende Parent-Verzeichnisse automatisch angelegt; tatsächlich verwendeter absoluter Pfad beim Start auf INFO-Level geloggt; gilt für GUI- und headless Start |
+
+### Nachbesserung aus dem Produkttest
+
+| # | Beschreibung |
+|---|---|
+| #93 | Produkttest-Nachbesserung: Korrekturen und Feinabstimmungen nach abgeschlossenem manuellem GUI-Produkttest gegen echte KI-Provider und echte PDFs |
+
+---
+
+## Architektur-Bilanz
+
+| Neu | Anzahl | Bemerkung |
+|---|---|---|
+| Inbound-Port-Interfaces | 1 | `CreateNewDatabaseUseCase` |
+| Application-Use-Cases | 1 | `DefaultCreateNewDatabaseUseCase` |
+| Outbound-Ports | 2 | `DatabaseCreationPort`, `ActiveDatabaseContextPort` |
+| Outbound-Adapter | 2 | `SqliteDatabaseCreationAdapter`, `SqliteActiveDatabaseContextAdapter` |
+| GUI-Bridge-Interfaces | 1 | `GuiCreateNewDatabasePort` |
+| Flyway-Migration | 1 | `failure_details TEXT` in `processing_attempt` (nächste freie Versionsnummer) |
+
+Geänderte Komponenten (ausschließlich `adapter-in-gui`):
+`GuiHistoryTab`, `GuiConfigTab`, `GuiTooltipTexts`, Verlauf-Detailbereich,
+Status-ComboBox, PDF-Vorschau-Komponente, Lauf-Abschluss-Signalkette.
+
+Nicht geändert: `pdf-umbenenner-domain` (außer ggf. minimaler Erweiterung für #88),
+`pdf-umbenenner-adapter-in-cli`, headless-Verarbeitungslogik, fachliche Kernverarbeitung.
+
+---
+
+## Verbindlich verifizierte Spec-Punkte
+
+- Kein Enum-Rohname in der GUI sichtbar – alle acht Statuswerte tragen Displaytext
+- `promptText` für leere Felder: kein Vermischen von Nutzdaten und Platzhaltertext
+- Dirty-State Konfig-Tab: programmgesteuertes Laden löst kein Dirty-Flag aus
+- Live-Filter: 300 ms Debounce, Generation-Counter, Auswahl nach Suche geleert
+- Strg+A im Verlauf-Tab: nur bei Tabellenfokus (kein Konflikt mit Suchfeld)
+- Schlüssel-Snapshot vor Bulk-Worker-Thread-Start
+- DB-Anlage: normalisierter Pfadvergleich (case-insensitive, `toRealPath`/Parent-Normalisierung)
+- DB-Anlage: `ATOMIC_MOVE + REPLACE_EXISTING`; kein halb-atomarer Fallback
+- DB-Anlage: aktive DB bleibt bei Fehler vollständig unverändert
+- Lock-File: absoluter Pfad direkt; relativer Pfad zweistufig; Pfad geloggt (INFO)
+- Strg+Mausrad: ScrollEvent immer konsumiert; Delta-Akkumulation; 10–500 %
+- `failure_details`: max. 1000 Zeichen vor Persistierung; keine rohen Provider-Meldungen
+- Aktionsbuttons nach Laufende ereignisgetrieben reaktiviert (alle Terminierungsgründe)
+- Flyway ist die einzige Schema-Evolutionsquelle – kein manuelles DDL im Code
+- Code-Kommentare auf Deutsch; Logging auf Deutsch
+- JavaDoc auf allen neuen öffentlichen Ports, Use-Cases und Adapter-Methoden
+
+---
+
+## Headless-Kompatibilität
+
+Der bestehende Batch-Betrieb über `--headless` bleibt vollständig erhalten.
+Die `.properties`-Datei bleibt die einzige Konfigurationswahrheit. GUI-Code
+initialisiert den headless Pfad nicht. Keine stillen Änderungen an Retry-Semantik,
+Status-Persistenz oder fachlicher Verarbeitungslogik.
+
+Von V3.1-Änderungen betroffener headless-Pfad: Lock-File-Pfadauflösung (#91)
+und Flyway-Schemamigration für `failure_details` (#88) – beide wirken beim
+Programmstart unabhängig von GUI oder CLI.
+
+---
+
+## Datenbank-Migration
+
+Flyway ergänzt die Tabelle `processing_attempt` um die Spalte `failure_details`:
+
+```sql
+ALTER TABLE processing_attempt ADD COLUMN failure_details TEXT;
+```
+
+- Bestehende Zeilen erhalten automatisch `NULL` – kein Datenverlust.
+- Ältere Einträge ohne Fehlerdetails zeigen in der GUI einen `promptText`-Platzhalter.
+- Kein SQL-`CHECK`-Constraint (um Importdaten nicht zu blockieren).
+- Begrenzung auf 1000 Zeichen wird ausschließlich vor Persistierung im Adapter erzwungen.
+
+---
+
+## Produkttest
+
+**Produkttest: bestanden**
+
+Manueller GUI-Produkttest gegen echte KI-Provider mit echten PDFs abgeschlossen.
+Alle elf Issues und die Nachbesserung #93 wurden end-to-end verifiziert.
+
+---
+
+## Bekannte Einschränkungen
+
+Keine.
+
+---
+
+## Nicht in V3.1
+
+- Automatischer Scheduler / Quellordner-Überwachung (#22) → V3.x
+- PDF-Viewer Render-DPI (#23) → V3.2
+- F1-Hilfe (#69) → V3.2
+- Dark Mode (#70) → V3.x
+- Log-Viewer in der GUI (#72) → V3.2
+- Token- und Kosten-Tracking (#74) → V3.2
+- Excel-Export (#75) → V3.2
+- Automatische Update-Prüfung (#76) → V3.2
+- Neue Maven-Module, neue KI-Provider, Architekturbrüche
+- Änderung der fachlichen Kernverarbeitung des PDF-Umbenenners
+
+---
+
+## Nächste Version
+
+**V3.2** – geplante Schwerpunkte: PDF-Viewer Render-DPI, F1-Hilfe, Log-Viewer,
+Token- und Kosten-Tracking, Excel-Export, automatische Update-Prüfung.
+
+---
+
+## Freigabeaussage
+
+V3.1 ist nach Prüfung fehlerfrei buildbar. Alle Kernanforderungen der hexagonalen
+Architektur sind eingehalten. Die fachliche Kernverarbeitung des PDF-Umbenenners
+bleibt unverändert gegenüber V3.0. Manueller Produkttest bestanden.
+Keine Release-Blocker.
@@ -337,13 +337,23 @@ vorbelegt.

 ## 8. Dirty-State und Schutzdialoge

+### Konfigurations-Tab
+
 Sobald eine geladene oder neu erzeugte Konfiguration bearbeitet wird, gilt der
-Editor als „dirty" (ungespeicherte Änderungen). Zwei visuelle Markierungen
+Editor als „dirty" (ungespeicherte Änderungen). Drei visuelle Markierungen
 zeigen diesen Zustand an:

+- Ein **`*`**-Präfix im **Tab-Titel**: `* Konfiguration`
 - Ein **`*`**-Präfix im Fenstertitel
 - Ein kleines **„geändert"**-Label im Header

+Das Dirty-Flag wird über einen **Baseline-Snapshot** ermittelt: Beim Laden einer
+Konfiguration wird ein Snapshot des geladenen Zustands gespeichert. Erst wenn
+der aktuelle Formularinhalt vom Snapshot abweicht, erscheint der Dirty-Indikator.
+Programmgesteuertes Laden und Normalisieren von Feldinhalten lösen keinen
+Dirty-State aus. Auch ein DB-Pfad-Wechsel über „Neue Datenbank anlegen..."
+(Abschnitt 16a) versetzt den Konfigurations-Tab in den Dirty-State.
+
 Vor den Aktionen „Neu", „Öffnen" und beim Schließen des Fensters prüft die GUI,
 ob ungespeicherte Änderungen vorhanden sind. Ist dies der Fall, erscheint ein
 Schutzdialog mit drei Optionen:
@@ -354,6 +364,12 @@ Schutzdialog mit drei Optionen:
 | **Verwerfen** | Verwirft die Änderungen und führt die Aktion aus |
 | **Abbrechen** | Bricht die Aktion ab; die Änderungen bleiben erhalten |

+### Prompt-Tab
+
+Der Prompt-Tab zeigt ebenfalls ein Asterisk im Tab-Titel (`Prompt *`), sobald der
+TextArea-Inhalt vom gespeicherten Stand abweicht. Das Verhalten ist identisch zum
+Konfigurations-Tab (Schutzdialog, Reset nach Speichern).
+
 ---

 ## 9. `.bak`-Sicherung beim Überschreiben und Legacy-Migration
@@ -619,10 +635,31 @@ Das Panel enthält drei Bereiche:
 - **Seitennavigation:** Über die Schaltflächen **„◀"** und **„▶"** (oder das Mausrad)
  kann seitenweise geblättert werden. Die aktuelle Seitenzahl und Gesamtseitenzahl
  werden angezeigt.
- **Fit-to-view:** Die Seite wird automatisch an die verfügbare Fläche angepasst
-  (preserveRatio=true). Keine Scrollbalken, keine manuelle Zoom-Einstellung.
+- **Fit-to-Width:** Nach dem Laden wird die Seite automatisch an die verfügbare Breite
+  angepasst (preserveRatio=true).
 - Das Rendering erfolgt direkt über Apache PDFBox bei 120 DPI.

+#### Zoom per Mausrad (Strg+Mausrad)
+
+- **Strg + Mausrad nach oben/unten** zoomt die Vorschau herein bzw. heraus.
+- Zoombereich: **10 % bis 500 %**, ca. 10 % je Mausrad-Rastpunkt.
+- Nach dem ersten manuellen Zoom verlässt die Vorschau den Fit-to-Width-Modus.
+  Fit-to-Width wird erst wieder aktiv, wenn ein neues PDF geladen oder der
+  Fit-to-Width-Button explizit betätigt wird.
+- Beim Laden eines neuen PDF wird der Zoom auf Fit-to-Width zurückgesetzt.
+- Beim Zoomen bleibt die sichtbare Viewport-Mitte möglichst stabil.
+- Trackpad-Gesten (sehr kleine Delta-Werte) werden intern akkumuliert, bis ein
+  vollständiger Zoomschritt erreicht ist.
+- **Ohne Strg:** Mausrad scrollt die Seite normal (kein Zoom).
+- ScrollEvents mit gedrückter Strg-Taste werden immer konsumiert, sodass kein
+  paralleles Scrollen im Hintergrund stattfindet.
+
+#### Grab & Pan (Handcursor im Zoom-Modus)
+
+Im vergrößerten Zustand (Zoom über Fit-to-Width) wechselt der Mauszeiger über
+der Vorschau auf einen **Handcursor**. Durch Klicken und Ziehen (Drag) kann die
+Ansicht verschoben werden. Im Fit-to-Width-Modus ist Pan nicht aktiv.
+
 ### KI-Begründung und Fehlertext

 Der mittlere Bereich zeigt das KI-Reasoning des ausgewählten Eintrags.
@@ -792,11 +829,38 @@ Die Tabelle zeigt folgende Spalten:
 Über dem Tab befinden sich drei Bedienelemente:

 - **Freitextsuche** – filtert über Quelldateiname und Zieldateiname, case-insensitiv
- **Status-Filter** – ComboBox zur Auswahl eines bestimmten Status oder „Alle"
- **„Aktualisieren"** – lädt die Liste neu aus der Datenbank (kein automatisches Echtzeit-Tailing)
+- **Status-Filter** – ComboBox zur Auswahl eines bestimmten Status oder „Alle Status"
+- **„Suchen"** – startet die Suche sofort; alternativ die Enter-Taste im Suchfeld

 Die Suche erfolgt datenbanksseitig; Sonderzeichen in der Sucheingabe werden korrekt behandelt.

+#### Live-Suche
+
+Die Freitextsuche reagiert **live** auf Tastatureingaben: 300 ms nach dem letzten
+Tastendruck startet die Suche automatisch auf einem Hintergrund-Thread.
+Der Such-Button und die Enter-Taste starten die Suche sofort ohne Verzögerung.
+
+Nach jeder neuen Suchanfrage wird die Tabellenauswahl vollständig geleert;
+Detailbereich und Aktionsbuttons werden zurückgesetzt. Ein leeres Suchfeld zeigt
+alle Einträge (bis Limit 500).
+
+### Mehrfachauswahl
+
+Die Verlauf-Tabelle unterstützt **Mehrfachauswahl**:
+
+| Geste | Wirkung |
+|---|---|
+| **Klick** | Einzelauswahl |
+| **Strg+Klick** | Einzelnen Eintrag zur Auswahl hinzufügen oder entfernen |
+| **Shift+Klick** | Bereich vom letzten zur aktuellen Zeile auswählen |
+| **Strg+A** | Alle sichtbaren Einträge auswählen (**nur wenn die Tabelle den Fokus hat**) |
+
+> **Hinweis:** Liegt der Fokus im Suchfeld, wirkt Strg+A als normale Textselektion
+> im Suchfeld und selektiert keine Tabellenzeilen.
+
+Bei Mehrfachauswahl zeigt der **Detailbereich** den Platzhaltertext
+„X Einträge ausgewählt." (statt Dokumentdetails).
+
 ### Detailbereich

 Ein Klick auf eine Zeile öffnet im rechten Bereich drei Informationsblöcke:
@@ -813,36 +877,100 @@ Ein Klick auf eine Zeile öffnet im rechten Bereich drei Informationsblöcke:
 |--------|--------|
 | # | Versuchsnummer |
 | Datum | Endzeitpunkt des Versuchs |
-| Status | Ergebnisstatus des Versuchs |
+| Status | Ergebnisstatus des Versuchs (lesbarer Anzeigetext, kein Enum-Rohname) |
 | Provider | Verwendeter KI-Provider |
 | Modell | Verwendetes Sprachmodell |
 | Vorgeschlagener Name | Vom Versuch erzeugter Zieldateiname |

-**KI-Begründung:** Das `ai_reasoning` des ausgewählten Versuchs als nicht editierbarer Text.
+**KI-Begründung / Fehlerursache:**
+
+Das `ai_reasoning` des zuletzt ausgewählten Versuchs als nicht editierbarer Text.
+Ist kein Reasoning gespeichert, erscheint ein gedimmter Platzhaltertext
+„Keine KI-Begründung für diesen Versuch gespeichert."
+
+Bei Einträgen mit Status `FAILED_FINAL`, `FAILED_RETRYABLE` oder
+`SKIPPED_FINAL_FAILURE` wird zusätzlich die **Fehlerursache** des letzten
+fehlgeschlagenen Versuchs angezeigt. Liegt keine Fehlerursache vor (z. B. ältere
+Einträge), erscheint ebenfalls ein Platzhaltertext.

 ### Aktionen

-Unterhalb der Dokumentenliste stehen zwei Aktionen zur Verfügung:
+Unterhalb der Dokumentenliste stehen zwei Aktionen zur Verfügung.
+**Beide Aktionen unterstützen Mehrfachauswahl** (≥ 1 Eintrag):

 **„Status zurücksetzen"**

-Setzt den Status des ausgewählten Dokuments auf „Wartet auf Verarbeitung" zurück,
-sodass es beim nächsten Verarbeitungslauf automatisch erneut verarbeitet wird.
+Setzt den Status der ausgewählten Dokumente auf „Wartet auf Verarbeitung" zurück,
+sodass sie beim nächsten Verarbeitungslauf automatisch erneut verarbeitet werden.
 Die Versuchshistorie bleibt vollständig erhalten – kein Versuch wird gelöscht.
-Vor der Aktion erscheint ein Bestätigungsdialog.
+Vor der Aktion erscheint ein Bestätigungsdialog: „X Einträge zurücksetzen?"
+
+Bei Mehrfachauswahl werden Einträge einzeln zurückgesetzt. Nach Abschluss erscheint
+eine kompakte Zusammenfassung „X von Y erfolgreich verarbeitet." Detaillierte
+Einzelfehler werden geloggt.

 Wann sinnvoll: wenn die Ursache eines Fehlers behoben wurde (z. B. OCR nachträglich
 durchgeführt, Passwortschutz entfernt) und das Dokument erneut verarbeitet werden soll.

 **„Eintrag löschen"**

-Löscht den Stammsatz und alle Verarbeitungsversuche des ausgewählten Dokuments
+Löscht die Stammsätze und alle Verarbeitungsversuche der ausgewählten Dokumente
 vollständig aus der Datenbank. Diese Aktion ist **nicht rückgängig zu machen**.
-Vor der Aktion erscheint ein Bestätigungsdialog mit einem ausdrücklichen Hinweis
-auf die Unwiderruflichkeit.
+Vor der Aktion erscheint ein Bestätigungsdialog: „X Einträge unwiderruflich löschen?"
+
+Bei Mehrfachauswahl gilt dieselbe Partial-Success-Logik wie beim Zurücksetzen.

 **Hinweis:** Beide Aktionen sind während eines laufenden Verarbeitungslaufs deaktiviert.
-Ein Hinweis „Aktion während Verarbeitungslauf nicht möglich." wird angezeigt.
+Nach Laufende werden die Buttons automatisch reaktiviert, sofern eine Auswahl besteht –
+ohne dass der Benutzer die Auswahl erneuern muss.
+
+---
+
+## 16a. Neue Datenbank anlegen
+
+Über **Datenbank → Neue Datenbank anlegen...** in der Menüleiste kann eine neue,
+leere SQLite-Datenbank erstellt und sofort als aktive Datenbank der Anwendung
+gesetzt werden – ohne Neustart.
+
+### Voraussetzung
+
+Der Menüpunkt ist nur aktiv, wenn kein Verarbeitungslauf läuft.
+
+### Ablauf
+
+1. Ein Dateidialog öffnet sich (Filter: `*.sqlite` und `*.db`). Neue Zieldatei
+   wählen oder eingeben.
+2. Die Anwendung prüft, ob die gewählte Datei identisch mit der aktuell aktiven
+   Datenbank ist (normalisierter, case-insensitiver Pfadvergleich). Bei
+   Übereinstimmung erscheint eine Fehlermeldung, kein Überschreiben.
+3. Existiert die gewählte Datei bereits (andere als aktive DB): Bestätigungsdialog
+   „Die Datei existiert bereits. Überschreiben?"
+4. Die neue DB wird als temporäre Datei im Zielverzeichnis erzeugt. Flyway
+   führt alle Migrationsskripte auf den neuesten Schema-Stand aus.
+5. Verbindungstest: Verbindung öffnen, Flyway-History prüfen, Leseabfrage prüfen.
+6. Nach erfolgreichem Test: atomarer Move zur Zieldatei
+   (`ATOMIC_MOVE + REPLACE_EXISTING`). Schlägt dies fehl, bricht der Vorgang
+   mit einer klaren Fehlermeldung ab.
+7. Die aktive Datenbankverbindung wechselt zur neuen DB.
+8. Der Verlauf-Tab lädt neu: „Noch keine Verarbeitungen vorhanden."
+9. Die Statuszeile aktualisiert den DB-Pfad.
+10. Die Konfiguration wird als geändert markiert (Dirty-State im Konfig-Tab).
+11. Im Meldungsbereich erscheint der Hinweis:
+    „Neue Datenbank ist aktiv. Konfiguration speichern, damit diese Datenbank
+    beim nächsten Start verwendet wird."
+
+### Fehlerfall
+
+Schlägt ein Schritt fehl, bleibt die bisherige Datenbank vollständig unverändert
+in Betrieb. Die temporäre Datei wird gelöscht. Ein Fehlerdialog erscheint mit
+einer konkreten Meldung.
+
+### Wichtiger Hinweis
+
+**Die Konfigurationsdatei wird durch den DB-Wechsel nicht automatisch gespeichert.**
+Damit die neue Datenbank beim nächsten Start der Anwendung verwendet wird, muss
+die Konfiguration explizit über „Speichern" oder „Speichern unter" gesichert werden.
+Der Dirty-State im Konfig-Tab und der Hinweis im Meldungsbereich erinnern daran.

 ---