From 4b8974340473a016950f0fa5167477f7fa59db78 Mon Sep 17 00:00:00 2001 From: Marcus van Elst Date: Sun, 3 May 2026 07:35:47 +0200 Subject: [PATCH] Bedienanleitung um Verlauf-Tab, Prompt-Tab, Statuszeile und Summary-Banner ergaenzt --- docs/gui-bedienanleitung.md | 301 ++++++++++++++++++++++++++++++++++-- 1 file changed, 290 insertions(+), 11 deletions(-) diff --git a/docs/gui-bedienanleitung.md b/docs/gui-bedienanleitung.md index 530446a..3931991 100644 --- a/docs/gui-bedienanleitung.md +++ b/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 -Kosten-Tracking — diese Ausbauten sind für spätere Stufen vorbehalten. +Am unteren Fensterrand ist permanent eine **Statuszeile** sichtbar (siehe Abschnitt 18). 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 (endgültig fehlgeschlagen) | + | `≡` | Grau | Übersprungen (bereits erfolgreich verarbeitet) | + | `⊘` | 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, - Z übersprungen` im Meldungs- und Zusammenfassungsbereich. +- Nach Laufende erscheint das **Summary-Banner** unterhalb des Fortschrittsbalkens + (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.