Bedienanleitung um Verlauf-Tab, Prompt-Tab, Statuszeile und Summary-Banner ergaenzt

docs/gui-bedienanleitung.md

@@ -1,4 +1,4 @@
-# GUI-Bedienanleitung – PDF-Umbenenner V2.0
+# GUI-Bedienanleitung – PDF-Umbenenner
 
 Diese Anleitung beschreibt die JavaFX-Desktop-GUI des PDF-Umbenenners. Sie richtet sich an
 Endbenutzer und Betreuer, die die Konfiguration der Anwendung über die grafische Oberfläche
@@ -8,15 +8,18 @@ verwalten und technisch prüfen möchten.
 
 ## 1. Zweck und Scope der GUI
 
-Die GUI gliedert sich in zwei feste Tabs:
+Die GUI gliedert sich in vier feste Tabs:
 
 - **Tab 1 „Konfiguration"** – Editor, Validierungsoberfläche und technische
   Test-/Diagnoseoberfläche für die `.properties`-Datei.
 - **Tab 2 „Verarbeitungslauf"** – Start eines Batch-Laufs aus der GUI mit
   Live-Fortschritt, Ergebnisliste und KI-Begründung je Dokument (siehe Abschnitt 13).
+- **Tab 3 „Verlauf"** – Ansicht aller bisher verarbeiteten Dokumente mit Status
+  und Verarbeitungsdetails aus der SQLite-Datenbank (siehe Abschnitt 16).
+- **Tab 4 „Prompt"** – Editor zum Lesen, Bearbeiten und Speichern der
+  konfigurierten KI-Prompt-Datei (siehe Abschnitt 17).
 
-Weiterhin **nicht** enthalten sind ein Historien-Tab, eine Datenbankansicht und ein
+Am unteren Fensterrand ist permanent eine **Statuszeile** sichtbar (siehe Abschnitt 18).
-Kosten-Tracking — diese Ausbauten sind für spätere Stufen vorbehalten.
 
 Für unbeaufsichtigte, geplante Läufe (z. B. Windows Task Scheduler) bleibt
 `--headless` der empfohlene Weg.
@@ -479,16 +482,20 @@ in den Lauf ein. Vor dem Start muss die Konfiguration daher gespeichert sein.
   | `✓` | Grün | Erfolgreich |
   | `↻` | Orange | Fehlgeschlagen (wiederholbar) |
   | `×` | Rot | Fehlgeschlagen (permanent) |
-  | `≡` | Blau | Übersprungen (bereits erfolgreich verarbeitet) |
+  | `≡` | Grau | Übersprungen (bereits erfolgreich verarbeitet) |
-  | `⊘` | Grau | Übersprungen (endgültig fehlgeschlagen) |
+  | `⊘` | Dunkelgrau | Übersprungen (endgültig fehlgeschlagen) |
   | `⟳` | Grau | Zurückgesetzt – wartet auf nächsten Lauf |
 
+  Farbe ist niemals das einzige Unterscheidungsmerkmal – Icon und Tooltip beschreiben
+  den Status auch ohne Farbwahrnehmung eindeutig. Die vollständige Status-Mapping-Tabelle
+  mit Tooltips ist in Abschnitt 19 beschrieben.
+
 - Ein Klick auf eine Zeile öffnet den Detailbereich rechts. Für `FAILED_*`-Einträge
   zeigt der Detailbereich eine übersetzte Fehlermeldung (Präfix `⚠`) anstelle des
   KI-Reasonings. Liegt weder Reasoning noch Fehlermeldung vor, erscheint der
   Hinweistext „Für diesen Eintrag liegt kein KI-Reasoning vor.".
-- Nach Laufende erscheint die Zusammenfassung `X erfolgreich, Y fehlgeschlagen,
+- Nach Laufende erscheint das **Summary-Banner** unterhalb des Fortschrittsbalkens
-  Z übersprungen` im Meldungs- und Zusammenfassungsbereich.
+  (siehe Abschnitt 13c).
 
 ### Soft-Stop
 Der Knopf **Abbrechen** löst einen **Soft-Stop** aus: die aktuell in Bearbeitung
@@ -666,17 +673,54 @@ Das Feld kann direkt bearbeitet werden. Die Eingabe wird **live validiert**
 
 ---
 
-## 14. Bekannte Einschränkungen V2.x
+## 13c. Summary-Banner nach Laufabschluss
+
+Nach Abschluss eines Verarbeitungslaufs erscheint unterhalb des Fortschrittsbalkens und
+oberhalb der Ergebnistabelle ein einzeiliges **Summary-Banner** (`BatchRunSummaryBanner`).
+Es zeigt auf einen Blick, wie viele Dateien in welche Kategorie gefallen sind.
+
+**Beispiel:**
+
+```
+✓ 14 erfolgreich  ·  ↻ 1 wird wiederholt  ·  × 2 fehlgeschlagen  ·  ≡ 3 übersprungen  ·  ⊘ 1 endgültig übersprungen
+```
+
+**Regeln:**
+
+- Nur Kategorien mit Anzahl größer als 0 werden angezeigt.
+- Bei einem vollständig sauberen Lauf erscheint nur die Erfolgskategorie,
+  z. B. `✓ 17 erfolgreich`.
+- Jedes Segment enthält Icon und Text – Farbe ist niemals das einzige Unterscheidungsmerkmal.
+- Das Banner verschwindet automatisch, wenn der nächste Lauf gestartet wird.
+- Das Banner erscheint **nicht** beim Anwendungsstart oder bei einem Tab-Wechsel
+  ohne vorherigen Lauf.
+
+**Kategorien:**
+
+| Icon | Text | Entsprechender Status |
+|------|------|-----------------------|
+| `✓` | erfolgreich | `SUCCESS` |
+| `↻` | wird wiederholt | `FAILED_RETRYABLE` |
+| `×` | fehlgeschlagen | `FAILED_FINAL` |
+| `≡` | übersprungen | `SKIPPED_ALREADY_PROCESSED` |
+| `⊘` | endgültig übersprungen | `SKIPPED_FINAL_FAILURE` |
+
+Die Zwischenstatus `READY_FOR_AI`, `PROPOSAL_READY` und `PROCESSING` werden im Banner
+nicht gezählt – sie treten nach Laufabschluss nicht mehr auf.
+
+---
+
+## 14. Bekannte Einschränkungen
 
 | Einschränkung | Erläuterung |
 |---|---|
-| Kein Historien-Tab | Eine Ansicht der SQLite-Datenbank und Verarbeitungshistorie ist für spätere Ausbaustufen vorbehalten |
 | Kein Kosten-Tracking | Token-/Preisberechnungen sind für spätere Ausbaustufen vorbehalten |
 | Keine Erkennung externer Änderungen | Wird die `.properties`-Datei während einer GUI-Sitzung von außen geändert, erkennt die GUI dies nicht. Die GUI arbeitet weiterhin auf dem zuletzt geladenen Stand |
 | Keine Koordination mit parallelen headless Läufen | Ein gleichzeitiger externer headless Lauf wird nicht technisch geblockt. Schreibkonflikte sind nicht ausgeschlossen, wenn dieselbe `.properties`-Datei parallel genutzt wird |
 | GUI nur für Windows | Die GUI wird offiziell nur unter Windows unterstützt; der headless Betrieb ist für Windows Server geeignet |
-| Ergebnisliste nicht persistent | Die Ergebnisliste im Verarbeitungslauf-Tab existiert nur für den aktuellen Programmstart; nach Neustart ist die Liste leer |
+| Ergebnisliste nicht persistent | Die Ergebnisliste im Verarbeitungslauf-Tab existiert nur für den aktuellen Programmstart; nach Neustart ist die Liste leer. Die dauerhaften Ergebnisse sind im Verlauf-Tab (Abschnitt 16) einsehbar. |
 | Einzelinstanz-Schutz | Wird die Anwendung ein zweites Mal gestartet, während bereits eine Instanz läuft (auch wenn diese im System-Tray minimiert ist), beendet sich die neue Instanz sofort ohne Hinweisfenster |
+| Prompt-Editor: kein automatisches Reload | Wird die Prompt-Datei während einer Bearbeitung extern geändert, erkennt die GUI dies nicht. Beim Speichern gilt Last-write-wins. |
 
 ---
 
@@ -705,3 +749,238 @@ Ein **Doppelklick** auf das Tray-Icon hat denselben Effekt wie „Öffnen".
 | Ungespeicherte Änderungen | Schutzdialog erscheint zuerst (Speichern / Verwerfen / Abbrechen); erst nach Auflösung wird in den Tray minimiert |
 | Aktiver Verarbeitungslauf | Hinweisdialog erscheint (Abschnitt 13); nach Soft-Stop oder Abschluss kann in den Tray minimiert werden |
 | System-Tray nicht verfügbar | Fenster wird beim Schließen wie ohne Tray-Support behandelt; der Schutzdialog für ungespeicherte Änderungen bleibt aktiv |
+
+---
+
+## 16. Tab „Verlauf" (Historien-Tab)
+
+Der dritte Tab **„Verlauf"** zeigt alle jemals verarbeiteten Dokumente mit Status,
+Dateinamen und Verarbeitungsdetails. Die Daten stammen direkt aus der SQLite-Datenbank,
+die in der geladenen Konfiguration angegeben ist.
+
+### Layout
+
+Das Tab ist zweigeteilt:
+
+- **Linke Hälfte (~55%):** Dokumentenliste mit Filter-Bereich oben
+- **Rechte Hälfte (~45%):** Detailbereich zum ausgewählten Dokument
+
+### Dokumentenliste
+
+Die Tabelle zeigt folgende Spalten:
+
+| Spalte | Inhalt |
+|--------|--------|
+| Status-Icon | Symbol und Farbe gemäß Status-Mapping-Tabelle (Abschnitt 19) |
+| Quelldateiname | Ursprünglicher Dateiname der PDF-Datei |
+| Zieldateiname | Zuletzt vergebener Dateiname nach Umbenennung |
+| Quellpfad | Letzter bekannter Quellordner |
+| Letzter Versuch | Zeitpunkt der letzten Statusänderung |
+| Anzahl Versuche | Gesamtzahl aller Verarbeitungsversuche |
+
+**Sortierung:** Standardmäßig absteigend nach dem letzten Versuch (neueste zuerst).
+
+**Hinweise zur Anzeige:**
+- Lange Dateinamen und Pfade werden in der Tabelle abgekürzt (Ellipsis). Der vollständige
+  Text erscheint im Tooltip beim Hover.
+- Bei mehr als 500 Treffern erscheint der Hinweis „Weitere Einträge vorhanden – Filter
+  verwenden". Es werden dann nur die 500 neuesten Einträge angezeigt.
+- Bei leerer Datenbank erscheint der Text „Noch keine Verarbeitungen vorhanden."
+
+### Filter
+
+Ü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)
+
+Die Suche erfolgt datenbanksseitig; Sonderzeichen in der Sucheingabe werden korrekt behandelt.
+
+### Detailbereich
+
+Ein Klick auf eine Zeile öffnet im rechten Bereich drei Informationsblöcke:
+
+**Dokument-Info:**
+- Fingerprint (12 Zeichen des SHA-256-Hash)
+- Quelldateiname und Quellpfad
+- Status (Icon + Text)
+- Erstellt am / Aktualisiert am
+
+**Versuche-Tabelle:** Alle bisher protokollierten Verarbeitungsversuche:
+
+| Spalte | Inhalt |
+|--------|--------|
+| # | Versuchsnummer |
+| Datum | Endzeitpunkt des Versuchs |
+| Status | Ergebnisstatus des Versuchs |
+| 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.
+
+### Aktionen
+
+Unterhalb der Dokumentenliste stehen zwei Aktionen zur Verfügung:
+
+**„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.
+Die Versuchshistorie bleibt vollständig erhalten – kein Versuch wird gelöscht.
+Vor der Aktion erscheint ein Bestätigungsdialog.
+
+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
+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.
+
+**Hinweis:** Beide Aktionen sind während eines laufenden Verarbeitungslaufs deaktiviert.
+Ein Hinweis „Aktion während Verarbeitungslauf nicht möglich." wird angezeigt.
+
+---
+
+## 17. Tab „Prompt" (Prompt-Editor)
+
+Der vierte Tab **„Prompt"** ermöglicht das Lesen, Bearbeiten und Speichern der
+KI-Prompt-Datei direkt in der GUI – ohne externen Editor.
+
+### Inhalt und Bedienung
+
+Die TextArea zeigt den aktuellen Inhalt der in der Konfiguration eingetragenen
+Prompt-Datei. Der Inhalt ist vollständig editierbar.
+
+**Buttons:**
+
+- **„Speichern"** – schreibt den aktuellen Inhalt atomar in die Prompt-Datei
+  (Temp-Datei im selben Verzeichnis, dann atomarer Austausch). Encoding: UTF-8;
+  Zeilenenden werden unverändert übernommen. Bei einem Fehler erscheint eine
+  Fehlermeldung im Tab; es gibt keinen stillen Fallback.
+- **„Auf Standard zurücksetzen"** – füllt die TextArea mit dem eingebauten
+  Standard-Template, ohne die Datei sofort zu speichern. Erst ein anschließendes
+  „Speichern" schreibt die Änderung auf den Datenträger.
+
+**Dirty State:**
+
+Sobald der TextArea-Inhalt vom gespeicherten Stand abweicht, erscheint ein
+Asterisk im Tab-Titel: **„Prompt \*"**. Wird der Tab gewechselt oder die
+Anwendung geschlossen, während ungespeicherte Änderungen vorliegen, erscheint
+ein Bestätigungsdialog mit der Frage „Änderungen verwerfen?".
+
+### Fehlende Prompt-Datei
+
+Ist keine Prompt-Datei konfiguriert oder existiert die konfigurierte Datei nicht,
+zeigt der Tab einen Hinweistext und den Button **„Standard-Prompt erstellen"**.
+Ein Klick legt eine Prompt-Datei mit dem deutschen Standard-Template an
+(standardmäßig im selben Ordner wie die geladene `.properties`-Datei).
+
+### Hinweise
+
+- Das Tab lädt den Dateiinhalt automatisch, wenn es geöffnet wird (Hintergrund-Thread).
+- Wird die Datei während einer Bearbeitung extern geändert, erkennt die GUI dies nicht.
+  Beim Speichern gilt Last-write-wins.
+- Für den Betrieb über MSI oder Task Scheduler wird empfohlen, den Prompt-Pfad
+  in der Konfiguration als absoluten Pfad anzugeben, um vom jeweiligen Arbeitsverzeichnis
+  unabhängig zu sein.
+
+---
+
+## 18. Statuszeile
+
+Am unteren Rand des Hauptfensters ist permanent eine **Statuszeile** (`GuiStatusBar`)
+sichtbar. Sie ist auf allen Tabs sichtbar und zeigt drei Segmente:
+
+| Position | Inhalt | Beispiel |
+|----------|--------|---------|
+| Links | Anwendungsversion | `V3.0.42` |
+| Mitte | Aktiver Provider und Modell | `Provider: Claude · claude-opus-4-7` |
+| Rechts | Pfad der geladenen Konfigurationsdatei | `config/application.properties` |
+
+**Besonderheiten:**
+
+- Die Versionsangabe wird aus der JAR-Manifest-Datei gelesen. Beim Start aus einer IDE
+  ohne gepacktes JAR erscheint der Fallback `Vdev`.
+- Ist keine Konfiguration geladen, zeigen Mitte und Rechts den Text „Kein Profil geladen".
+- Die Statuszeile aktualisiert sich automatisch beim Laden, Speichern und Schließen
+  einer Konfigurationsdatei.
+
+---
+
+## 19. Fehlerstatus – Bedeutung und Unterscheidung
+
+Zwei Fehlerstatus werden in der GUI klar unterschieden. Die Unterscheidung ist wichtig,
+um zu entscheiden, ob eine erneute Verarbeitung sinnvoll ist.
+
+### `↻` Wird wiederholt (orange) – `FAILED_RETRYABLE`
+
+Das Dokument konnte vorübergehend nicht verarbeitet werden. Der Fehler ist
+wahrscheinlich technischer Natur und kann sich bei einem späteren Versuch
+von selbst auflösen.
+
+**Typische Ursachen:** Netzwerkfehler, Timeout beim KI-Dienst, vorübergehende
+Nicht-Erreichbarkeit.
+
+**Was passiert:** Das Dokument wird beim nächsten regulären Verarbeitungslauf
+**automatisch erneut versucht** – kein manuelles Eingreifen notwendig.
+
+### `×` Fehlgeschlagen (rot) – `FAILED_FINAL`
+
+Das Dokument ist dauerhaft nicht verarbeitbar. Automatische Wiederholversuche
+werden nicht mehr unternommen.
+
+**Typische Ursachen:**
+- Kein lesbarer Text (z. B. eingescanntes Foto ohne OCR-Verarbeitung)
+- Passwortgeschützte PDF
+- Beschädigte oder unlesbare Datei
+
+**Was passiert:** Das Dokument wird in späteren Läufen übersprungen.
+
+**Mögliche Abhilfe:** Wenn die Ursache behoben wurde (z. B. OCR wurde nachträglich
+durchgeführt), kann der Status im **Verlauf-Tab** (Abschnitt 16) manuell zurückgesetzt
+werden. Das Dokument wird dann beim nächsten Lauf erneut verarbeitet. Alternativ kann
+der Eintrag vollständig gelöscht werden, damit die Datei als neu erkannt wird.
+
+---
+
+### Vollständige Status-Mapping-Tabelle
+
+| Status | Icon | Farbe | Tooltip-Text | Summary-Kategorie |
+|--------|------|-------|-------------|-------------------|
+| `SUCCESS` | `✓` | Grün | „Erfolgreich verarbeitet und umbenannt." | erfolgreich |
+| `FAILED_RETRYABLE` | `↻` | Orange | „Temporärer Fehler – wird beim nächsten Lauf automatisch erneut versucht." | wird wiederholt |
+| `FAILED_FINAL` | `×` | Rot | „Dauerhaft nicht verarbeitbar – z. B. kein Textinhalt (Foto-PDF), Passwortschutz oder beschädigte Datei. Kein weiterer automatischer Versuch." | fehlgeschlagen |
+| `SKIPPED_ALREADY_PROCESSED` | `≡` | Grau | „Übersprungen – wurde bereits in einem früheren Lauf erfolgreich verarbeitet." | übersprungen |
+| `SKIPPED_FINAL_FAILURE` | `⊘` | Dunkelgrau | „Endgültig übersprungen nach wiederholten Fehlern." | endgültig übersprungen |
+| `READY_FOR_AI` | `⟳` | Blau | „Wartet auf Verarbeitung." | – |
+| `PROPOSAL_READY` | `◇` | Hellblau | „KI-Vorschlag liegt vor, wartet auf Bestätigung." | – |
+| `PROCESSING` | `▶` | Hellgrau | „Wird gerade verarbeitet." | – |
+
+**Wichtig:** Farbe ist niemals das einzige Unterscheidungsmerkmal. Icon und Tooltip-Text
+beschreiben den Status auch ohne Farbwahrnehmung eindeutig.
+
+---
+
+## 20. Tooltips
+
+Auf den meisten interaktiven Elementen der GUI sind Tooltips gesetzt, die beim Hover über
+ein Element erscheinen. Sie erklären kurz den Zweck des Elements.
+
+Tooltips sind unter anderem vorhanden auf:
+
+- **Konfigurationsfeldern** – Quellordner, Zielordner, SQLite-Datei, Prompt-Datei,
+  Provider-ComboBox, Modell-Feld, `max.text.characters`, `max.pages`, `max.title.length`
+- **Toolbar-Buttons** – Neu, Öffnen, Speichern, Speichern unter, Validieren,
+  Technische Tests ausführen
+- **Status-Icons** im Verarbeitungslauf-Tab – Text gemäß Status-Mapping-Tabelle
+  (Abschnitt 19)
+- **Buttons „Dateiname übernehmen"** und **„Zurücksetzen auf KI-Vorschlag"** im
+  Dateiname-Editor (Abschnitt 13b)
+
+Der Tooltip erscheint nach einer kurzen Verzögerung beim Verweilen mit der Maus
+über dem jeweiligen Element.