pdf-umbenenner/docs/gui-bedienanleitung.md

GUI-Bedienanleitung – PDF-Umbenenner V2.0

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 verwalten und technisch prüfen möchten.

---

1. Zweck und Scope der GUI

Die GUI gliedert sich in zwei 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).

Weiterhin nicht enthalten sind ein Historien-Tab, eine Datenbankansicht und ein Kosten-Tracking — diese Ausbauten sind für spätere Stufen vorbehalten.

Der headless Batch-/Scheduler-Betrieb über --headless bleibt der einzige Weg, PDF-Dateien automatisiert zu verarbeiten.

---

2. Startzustände

2.1 GUI-Standardstart

Wird die Anwendung ohne CLI-Argumente gestartet, öffnet sich die JavaFX-Desktop-GUI. Es wird keine Konfigurationsdatei automatisch geladen.

Stattdessen zeigt die GUI einen deutschen Willkommenstext mit dem Hinweis, über „Neu" eine Standardvorlage zu erzeugen oder über „Öffnen" eine bestehende .properties-Datei zu laden.

2.2 Start mit --config <pfad> (gültige Datei)

Wird beim Start eine gültige .properties-Datei über --config <pfad> angegeben, lädt die GUI diese Datei automatisch und zeigt den Inhalt im Editor an. Der Pfad wird im Header angezeigt.

2.3 Start mit --config <pfad> (ungültiger oder nicht vorhandener Pfad)

Zeigt der angegebene Pfad auf eine nicht vorhandene oder nicht lesbare Datei, erscheint eine Fehlermeldung im zentralen Meldungsbereich. Danach verhält sich die GUI so, als wäre --config nicht angegeben worden: Es erscheint der Willkommenstext, und der Benutzer kann manuell eine Datei öffnen oder eine neue Konfiguration anlegen.

Im Unterschied zum headless Betrieb ist dies kein harter Startfehler – die GUI bleibt vollständig bedienbar.

2.4 GUI-Startfehler vor Anzeige der Oberfläche

Tritt vor der erfolgreichen Anzeige der grafischen Oberfläche ein nicht behebbarer Fehler auf (z. B. fehlende JavaFX-Laufzeit, schwerwiegender Bootstrap-Fehler), beendet sich die Anwendung mit Exit-Code 1. In diesem Fall wird keine Oberfläche angezeigt.

---

3. Header und Meldungsbereich

3.1 Header

Der Header oben im Fenster zeigt den Pfad der aktuell geladenen .properties-Datei. Ist keine Datei geladen, bleibt der Pfadbereich leer oder zeigt einen entsprechenden Hinweis.

Sobald ungespeicherte Änderungen vorliegen, erscheinen zwei visuelle Markierungen:

• ein kleines „geändert"-Label im Header
• ein führendes * im Fenstertitel

Diese Markierungen verschwinden, sobald die Datei gespeichert wurde oder Änderungen verworfen werden.

3.2 Zentraler Meldungsbereich

Am unteren Ende der GUI befindet sich ein großer Meldungsbereich. Er ist dauerhaft sichtbar und zeigt Ergebnisse von Validierungen, technischen Tests, Migrationsmeldungen und sonstige Statusinformationen.

Der Meldungsbereich verwendet vier feste Stufen:

Stufe	Präfix	Farbe des Präfix
Info	Info:	Blau
Hinweis	Hinweis:	Grün
Warnung	Warnung:	Orange
Fehler	Fehler:	Rot

Nur das Präfix am Zeilenanfang wird farbig dargestellt. Der eigentliche Meldungstext derselben Zeile ist immer schwarz. Die vier Stufen dienen ausschließlich der visuellen Einordnung; sie verhindern das Speichern nicht.

Meldungen kopieren

Einzelne oder mehrere Meldungen können markiert und in die Zwischenablage kopiert werden:

• Einzelne Zeile markieren: Meldung anklicken
• Mehrere Zeilen markieren: Shift+Klick (Bereich) oder Strg+Klick (Einzelauswahl)
• Alle Zeilen markieren: Strg+A
• Markierte Zeilen kopieren: Strg+C

Per Rechtsklick steht zusätzlich ein Kontextmenü zur Verfügung:

Eintrag	Wirkung
Meldung kopieren	Kopiert alle markierten Zeilen in die Zwischenablage (nur aktiv, wenn eine Auswahl besteht)
Alle Meldungen kopieren	Kopiert alle aktuell angezeigten Meldungen in die Zwischenablage

Meldungen leeren

Unterhalb des Meldungsbereichs befindet sich links der Button „Meldungen leeren". Ein Klick darauf entfernt alle aktuell angezeigten Meldungen sofort und vollständig.

Darüber hinaus wird der Meldungsbereich in folgenden Situationen automatisch geleert, sodass keine Meldungen aus einem früheren Vorgang sichtbar bleiben:

Aktion	Verhalten
Neu	Meldungsbereich wird vor der neuen Konfiguration geleert
Öffnen	Meldungsbereich wird vor der geladenen Konfiguration geleert
Validieren	Meldungsbereich wird geleert; danach erscheinen ausschließlich die Befunde des aktuellen Durchlaufs
Technische Tests ausführen	Meldungsbereich wird geleert; danach erscheinen ausschließlich die Befunde des aktuellen Durchlaufs

---

4. Aktionen

4.1 Neu

Erzeugt eine neue Konfiguration aus der internen Standardvorlage. Die Vorlage enthält sinnvolle Standardwerte und beide bekannten Provider-Blöcke (Claude und OpenAI-kompatibel). Standardmäßig ist der alphabetisch erste Provider (Claude) als aktiver Provider vorbelegt.

Sind zum Zeitpunkt der Aktion ungespeicherte Änderungen vorhanden, erscheint der Schutzdialog (siehe Abschnitt 8).

4.2 Öffnen

Öffnet einen nativen Dateidialog gefiltert auf *.properties-Dateien. Die ausgewählte Datei wird geladen und im Editor angezeigt.

Enthält die Datei das ältere Legacy-Format (flache api.*-Schlüssel), wird sie automatisch ins aktuelle Mehrprovider-Schema migriert. Vor der Migration wird eine .bak-Sicherung der Originaldatei angelegt (siehe Abschnitt 9). Die durchgeführte Migration wird im zentralen Meldungsbereich sichtbar gemeldet.

Sind zum Zeitpunkt der Aktion ungespeicherte Änderungen vorhanden, erscheint der Schutzdialog (siehe Abschnitt 8).

4.3 Speichern

Schreibt den aktuellen Editorstand in die zuletzt geladene oder gespeicherte Datei.

Ist die Konfiguration neu und wurde noch nie gespeichert, verhält sich „Speichern" wie „Speichern unter": Es wird ein Dateidialog geöffnet und ein Speicherpfad erfragt.

4.4 Speichern unter

Öffnet einen nativen Dateidialog gefiltert auf *.properties-Dateien. Als Vorschlagspfad wird config/application.properties relativ zum aktuellen Arbeitsverzeichnis verwendet. Damit ist die gespeicherte Datei ohne weitere Schritte für den nächsten headless Batch-Lauf nutzbar.

Zeigt der Dialog auf eine bereits existierende Datei, erscheint eine Rückfrage „Datei überschreiben?". Bei Bestätigung wird vor dem Überschreiben automatisch eine .bak-Sicherung angelegt (siehe Abschnitt 9).

Kommentare und Schlüsselreihenfolge der .properties-Datei werden beim Speichern normalisiert.

4.5 Validieren

Führt eine explizite, nicht-schreibende Gesamtprüfung des aktuellen Editorzustands durch. Die Prüfung läuft lokal ohne Netzwerkzugriff und umfasst dieselben Regelprüfungen wie die automatische Hintergrundvalidierung, kann aber zusätzliche lokale Prüfpunkte zusammenführen.

Die Prüfung arbeitet auf dem aktuellen GUI-Zustand, also auch auf ungespeicherten Änderungen. Die Datei wird dabei nicht implizit gespeichert.

Ergebnisse erscheinen im zentralen Meldungsbereich und als feldnahe Fehlermeldungen direkt unter den betroffenen Eingabefeldern.

4.6 Technische Tests ausführen

Führt eine umfassende technische Prüfung des aktuellen Editorzustands durch, einschließlich provider-naher Tests mit Netzwerkzugriff. Alle Prüfpunkte werden vollständig und gesammelt durchlaufen; die Aktion bricht bei einem Einzelfehler nicht ab.

Geprüft werden unter anderem:

• .properties-Datei und Provider-Konfiguration
• Erreichbarkeit von Base-URL bzw. Endpoint
• Vorhandensein und technische Akzeptanz des API-Keys
• Abrufbarkeit der Modellliste
• Plausibilität des gewählten Modells
• Vorhandensein und Lesbarkeit der Prompt-Datei
• Quellordner (vorhanden und lesbar)
• Zielordner (vorhanden oder anlegbar und beschreibbar)
• SQLite-Datei bzw. -Pfad

Die Tests arbeiten auf dem aktuellen GUI-Zustand ohne implizites Speichern. Wenn ungespeicherte Änderungen vorliegen, ist ein entsprechender Hinweis zweckmäßig.

Bestimmte Befunde können durch korrigierende Maßnahmen behoben werden (z. B. Zielordner anlegen, SQLite-Datei anlegen, fehlende Prompt-Datei mit einem deutschen Standardinhalt erzeugen). Diese Korrekturen erfolgen nicht still im Hintergrund, sondern erst nach Bestätigung eines gesammelten Bestätigungsdialogs („Folgende Korrekturen werden durchgeführt … Fortfahren?").

Die automatisch erzeugte Prompt-Datei enthält einen deutschen Standardprompt, der ohne weitere Anpassung funktioniert. Ein Beispiel dieses Standardprompts liegt unter docs/examples/prompt.txt.

Nicht automatisch korrigierbar sind insbesondere: falscher API-Key, unerreichbare Base-URL, nicht verfügbare Modellliste, sonstige externe technische Fehler.

4.7 Modelle neu laden

Ruft die Modellliste des aktuell ausgewählten Providers erneut über einen Hintergrund-Worker-Thread ab. Der gleiche Abruf wird auch automatisch bei jedem Providerwechsel ausgelöst.

---

5. Feldnahe Fehlermeldungen

Direkt unter bestimmten Eingabefeldern kann die GUI kleine, rote, deutschsprachige Hinweise einblenden, wenn der eingetragene Wert fehlerhaft oder riskant ist. Diese feldnahen Meldungen ergänzen den zentralen Meldungsbereich und ersetzen ihn nicht.

Feldnahe Meldungen erscheinen nach einer Validierung oder nach dem Ausführen der technischen Tests. Sie verschwinden, sobald der Fehler behoben und eine neue Prüfung durchgeführt wurde.

---

6. Automatische Hintergrundvalidierung

Eine geladene Konfiguration wird sofort beim Öffnen geprüft. Während der Bearbeitung aktualisiert die Validierung ihre Ergebnisse kontinuierlich im Hintergrund. Ergebnisse werden im zentralen Meldungsbereich und als feldnahe Hinweise angezeigt.

Die automatische Validierung unterscheidet:

• Fehler: Der Konfigurationsstand ist nicht lauffähig.
• Warnungen: Die Einstellung ist technisch akzeptabel, aber riskant oder unüblich. Beispiele: sehr hohe max.text.characters-Werte, ungewöhnliche Timeouts.
• Hinweise: Informationen ohne Handlungsbedarf.

Warnungen und Hinweise verhindern das Speichern nicht. Vor dem Speichern eines als nicht lauffähig markierten Stands erscheint jedoch eine deutlich sichtbare Warnung im zentralen Meldungsbereich, die ausdrücklich auf mögliche Auswirkungen auf den nächsten headless Lauf hinweist. Speichern ist dennoch erlaubt.

Wirtschaftliche Warnschwellen für max.text.characters:

Wertebereich	Bewertung
bis 1.000	unkritisch
1.001 – 3.000	Warnung
ab 3.001	starke Warnung

Standard-Default der GUI-Vorlage: 1.000 Zeichen (unkritisch)

max.pages wird als Plausibilitäts- und Performance-Hinweis behandelt.

Validierungsregeln für max.title.length (Feld „Max. Titellänge (Zeichen)" im Bereich „Verarbeitungslimits"):

Wertebereich	Bewertung
Kein Wert / leer	Fehler – Pflichtfeld, Konfiguration nicht lauffähig
Keine Ganzzahl (z. B. „abc")	Fehler – ungültiger Typ
Kleiner als 10	Fehler – Minimum ist 10 Zeichen
10 – 19	Warnung – Titellänge unter 20 Zeichen ist für die meisten Dokumente nicht empfohlen
20 – 99	Normaler Betrieb, keine Meldung
100 – 120	Warnung – Dateiname wird sehr lang, Kompatibilität mit verschlüsselten Volumes prüfen
Größer als 120	Fehler – überschreitet sicheres Limit für verschlüsselte Volumes

Warnungen verhindern das Speichern nicht. Fehler markieren den Stand als nicht lauffähig; Speichern ist dennoch erlaubt, jedoch erscheint ein deutlicher Hinweis im Meldungsbereich.

---

7. Provider-Bedienung und Modellabruf

7.1 Provider-ComboBox

Im Bereich „Provider" befindet sich eine ComboBox zur Auswahl des aktiven Providers. In V2.0 stehen zwei Einträge zur Verfügung:

• Claude
• OpenAI-kompatibel

Nur der aktuell ausgewählte Provider-Bereich ist im Formular sichtbar. Der verdeckte Provider-Block behält seine Daten; ein Providerwechsel löscht die Konfiguration des anderen Blocks nicht.

7.2 Automatischer Modellabruf

Bei jedem Providerwechsel startet der Modellabruf automatisch auf einem Hintergrund-Worker-Thread. Wird die Modellliste erfolgreich geladen, erscheint eine nicht editierbare ComboBox mit den verfügbaren Modellen. Das erste Modell der Liste ist automatisch vorbelegt.

Kann keine Modellliste abgerufen werden (z. B. wegen fehlendem oder falschem API-Key, unerreichbarem Endpoint), erscheint statt der ComboBox ein leeres Texteingabefeld. In diesem Fall muss der Modellname manuell eingetragen werden.

Wurde zuvor ein Modellname manuell eingetragen und wird später eine echte Modellliste geladen, in der dieser Wert nicht vorkommt, wird der manuell eingetragene Modellname verworfen. Es wird dann das erste Modell der Liste vorbelegt.

---

8. Dirty-State und Schutzdialoge

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

• Ein *-Präfix im Fenstertitel
• Ein kleines „geändert"-Label im Header

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:

Option	Wirkung
Speichern	Speichert die Änderungen und führt die Aktion danach aus
Verwerfen	Verwirft die Änderungen und führt die Aktion aus
Abbrechen	Bricht die Aktion ab; die Änderungen bleiben erhalten

---

9. .bak-Sicherung beim Überschreiben und Legacy-Migration

9.1 Sicherung beim Überschreiben

Bevor eine bestehende .properties-Datei überschrieben wird, legt die GUI automatisch eine Sicherungskopie an:

• Standardfall: <dateiname>.bak (im selben Verzeichnis)
• Falls .bak bereits existiert: <dateiname>.bak.1, .bak.2, …
• Bestehende Sicherungen werden niemals überschrieben.

Dieses Schema gilt sowohl für „Speichern unter" bei existierendem Ziel als auch für die Legacy-Migration beim Öffnen.

9.2 Legacy-Migration

Ältere .properties-Dateien, die noch die flachen Schlüssel api.baseUrl, api.model, api.timeoutSeconds und api.key verwenden, erkennt die GUI beim Öffnen automatisch als Legacy-Format. Sie führt folgende Schritte durch:

1. .bak-Sicherung der Originaldatei anlegen (nach dem Schema aus 9.1)
2. Inhalt ins aktuelle Mehrprovider-Schema überführen:
   • Legacy-Werte werden dem Namensraum openai-compatible zugeordnet
   • ai.provider.active=openai-compatible wird ergänzt
3. Die migrierte Konfiguration wird im Editor angezeigt

Die durchgeführte Migration wird im zentralen Meldungsbereich sichtbar gemeldet, damit der Benutzer die Änderung nachvollziehen kann.

---

10. API-Key-Auflösungsreihenfolge

Der API-Key eines Providers wird in folgender Priorität aufgelöst:

1. Providerspezifische Umgebungsvariable (höchste Priorität)
2. Für OpenAI-kompatibel zusätzlich: Legacy-Umgebungsvariable PDF_UMBENENNER_API_KEY (aus dem früheren Einzelprovider-Stand)
3. Property-Wert in der .properties-Datei

Provider	Providerspezifische Umgebungsvariable
Claude	ANTHROPIC_API_KEY
OpenAI-kompatibel	OPENAI_COMPATIBLE_API_KEY

Für OpenAI-kompatibel wird zusätzlich die Legacy-Variable PDF_UMBENENNER_API_KEY akzeptiert, falls die providerspezifische Variable nicht gesetzt ist. Für Claude gibt es keine Legacy-Variable.

Die GUI zeigt unterhalb des API-Key-Felds die Herkunft des aktuell wirksamen Schlüssels an. Greift eine Umgebungsvariable, erscheint ein Hinweis mit dem Namen der Variablen (z. B. „Aktuell wirksam aus Umgebungsvariable ANTHROPIC_API_KEY"). Ist kein Schlüssel aus keiner Quelle verfügbar, erscheint eine Warnung.

Das API-Key-Feld ist ein normales, unmaskiertes Textfeld. Ein leeres Feld entfernt den vorhandenen Property-Wert nicht stillschweigend, solange keine Umgebungsvariable greift. In diesem Fall bleibt der bestehende Property-Wert erhalten, und die GUI zeigt eine deutliche Warnung.

---

11. Pfadfelder und Datei-/Ordnerdialoge

Für die folgenden Konfigurationswerte stellt die GUI je ein Texteingabefeld sowie einen kleinen Button zum Öffnen des nativen Dialogs bereit:

Feld	Dialog-Typ
Quellordner	Ordnerdialog
Zielordner	Ordnerdialog
SQLite-Datei	Dateidialog
Prompt-Datei	Dateidialog

Pfade können auch direkt ins Texteingabefeld eingegeben werden, ohne den Dialog zu nutzen.

---

12. Windows-Hinweise zu gemappten Laufwerken

Die GUI sowie alle zugehörigen Pfadprüfungen akzeptieren Windows-Laufwerksbuchstaben wie S:\, H:\ oder C:\. Gemappte Netzlaufwerke werden ausdrücklich unterstützt und werden nicht allein wegen eines dahinterliegenden UNC-Pfads abgelehnt.

UNC-Pfade (z. B. \\server\freigabe\pfad\) werden ebenfalls akzeptiert, sind aber nicht das primäre Format für den GUI-Betrieb.

Die GUI wird offiziell nur unter Windows unterstützt.

---

13. Tab „Verarbeitungslauf" (live-Verfolgung)

Der zweite Tab „Verarbeitungslauf" startet einen Batch-Lauf direkt aus der GUI und zeigt dessen Fortschritt in Echtzeit an.

Layout

• Fortschrittsbalken mit Zähler (n / m Dateien) im Kopfbereich
• Ergebnisliste (scrollbar) mit einer Zeile pro abgeschlossener Datei
• Seitenbereich rechts neben der Liste für die KI-Begründung
• Meldungs- und Zusammenfassungsbereich unter der Liste
• Aktionsknöpfe Starten und Abbrechen

Konfigurationsquelle

Der Lauf verwendet ausschließlich den zuletzt gespeicherten Stand der .properties-Datei. Ungespeicherte Änderungen im Konfigurations-Editor fließen nicht in den Lauf ein. Vor dem Start muss die Konfiguration daher gespeichert sein.

Start und Verlauf

• Beim Start wird die Dateimenge einmalig bestimmt; der Nenner des Fortschrittsbalkens bleibt während des Laufs konstant.
• Nach jeder abgeschlossenen Datei erscheint ohne manuellen Refresh eine neue Zeile mit den fünf Spalten Status-Icon, Originaldateiname, Neuer Dateiname, Datum und Dauer.
• Für Fehler- und Übersprungen-Fälle wird bei den Spalten „Neuer Dateiname" und „Datum" ein Gedankenstrich — eingetragen.
• Die Status-Icons folgen: ✅ erfolgreich, ⚠️ fehlgeschlagen (retryable), ❌ fehlgeschlagen (permanent), ⏭️ übersprungen.
• Ein Klick auf eine Zeile zeigt die KI-Begründung im Seitenbereich. Liegt keine Begründung 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.

Soft-Stop

Der Knopf Abbrechen löst einen Soft-Stop aus: die aktuell in Bearbeitung befindliche Datei wird vollständig fertig verarbeitet, anschließend wird der Lauf sauber beendet — keine halbfertigen Zustände in der SQLite-Datenbank.

Sperre von Tab 1 während eines Laufs

Während eines laufenden Verarbeitungslaufs ist Tab 1 „Konfiguration" gesperrt. Ein sichtbarer Hinweis erinnert daran, dass die Konfiguration während des Laufs nicht editierbar ist. Nach Abschluss, Abbruch oder einer unerwarteten Ausnahme wird Tab 1 automatisch wieder freigegeben.

Fenster schließen während eines Laufs

Versucht der Benutzer das Fenster zu schließen, während ein Lauf aktiv ist, erscheint ein Hinweisdialog mit zwei Optionen:

• Nicht schließen – der Lauf läuft unverändert weiter
• Lauf beenden und schließen – ein Soft-Stop wird ausgelöst; nach Abschluss der aktuellen Datei schließt die Anwendung

Grenzen und Hinweise

• Pro Anwendungsinstanz ist genau ein Verarbeitungslauf gleichzeitig zulässig. Ein zweiter Startversuch während eines laufenden Laufs wird mit der Meldung „Ein Verarbeitungslauf ist bereits aktiv." verweigert.
• Ein gleichzeitiger externer headless Lauf (Windows Task Scheduler) wird weder aktiv erkannt noch technisch geblockt. Der Benutzer ist selbst verantwortlich, parallele Läufe zu vermeiden.
• Startet der Lauf mit einem leeren Quellordner, erscheint der Hinweis „Keine verarbeitbaren Dateien im Quellordner gefunden" und die Zusammenfassung 0 erfolgreich, 0 fehlgeschlagen, 0 übersprungen wird eingetragen.

---

14. Bekannte Einschränkungen V2.x

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