pdf-umbenenner/docs/gui-bedienanleitung.md

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

---

1. Zweck und Scope der GUI

Die GUI gliedert sich in fünf 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 „Scheduler" – Optionaler automatischer Scheduler für periodische Verarbeitungsläufe (siehe Abschnitt 14).
• Tab 4 „Verlauf" – Ansicht aller bisher verarbeiteten Dokumente mit Status und Verarbeitungsdetails aus der SQLite-Datenbank (siehe Abschnitt 17).
• Tab 5 „Prompt" – Editor zum Lesen, Bearbeiten und Speichern der konfigurierten KI-Prompt-Datei (siehe Abschnitt 18).

Am unteren Fensterrand ist permanent eine Statuszeile sichtbar (siehe Abschnitt 19).

Für unbeaufsichtigte, geplante Läufe (z. B. Windows Task Scheduler) bleibt --headless der empfohlene Weg.

---

2. Startzustände

2.1 GUI-Standardstart

Wird die Anwendung ohne CLI-Argumente gestartet, öffnet sich die JavaFX-Desktop-GUI maximiert (Vollbild).

Wurde bei einem früheren Start eine Konfigurationsdatei geladen, wird diese automatisch erneut geladen. Der zuletzt verwendete Pfad wird systemseitig gespeichert (java.util.prefs.Preferences). Existiert die Datei nicht mehr, startet die GUI ohne Fehlermeldung mit dem Willkommenstext — es erscheint kein Dialog und kein Fehler.

Beim allerersten Start (oder wenn noch keine Datei geladen wurde) 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 – 39	Warnung – Titellänge unter 40 Zeichen – KI-Ergebnisse können unvollständig sein, da Absender allein bereits 15–20 Zeichen benötigt
40 – 99	Normaler Betrieb, keine Meldung
100 – 120	Warnung – Hohe Titellänge – 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

Konfigurations-Tab

Sobald eine geladene oder neu erzeugte Konfiguration bearbeitet wird, gilt der 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 17a) 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:

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

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

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 FAILED_*-Zeilen und SKIPPED_FINAL_FAILURE-Zeilen wird in den Spalten „Neuer Dateiname" und „Datum" ein Gedankenstrich — eingetragen. SKIPPED_ALREADY_PROCESSED-Zeilen zeigen in der Spalte „Neuer Dateiname" den historischen Zieldateinamen aus dem letzten erfolgreichen Lauf; „Datum" bleibt —.

• Status-Icons (Unicode-Zeichen mit Farbe):

  Symbol	Farbe	Bedeutung
  ✓	Grün	Erfolgreich
  ↻	Orange	Fehlgeschlagen (wiederholbar)
  ×	Rot	Fehlgeschlagen (permanent)
  ≡	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 20 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 das Summary-Banner unterhalb des Fortschrittsbalkens (siehe Abschnitt 13c).

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.

---

13a. Selektion, Wiederverarbeitung und Status-Reset (V2.8)

Nach Abschluss eines Verarbeitungslaufs können einzelne oder mehrere Dateien aus der Ergebnisliste gezielt erneut verarbeitet oder deren Status zurückgesetzt werden.

Selektion in der Ergebnisliste

• Jede Zeile hat eine Checkbox am linken Rand
• Zusätzlich eine Master-Checkbox oberhalb der Liste zum Auswählen/Abwählen aller Einträge
• Zeilenklick (auf Text/Status-Icon) repräsentiert dieselbe Selektionsmenge wie die Checkbox
• Shift/Strg-Mehrfachselektion funktioniert wie im Windows Explorer
  • Shift+Klick: Bereich vom letzten zur aktuellen Zeile
  • Strg+Klick: einzelne Zeilen hinzufügen/entfernen
• Alle vier Statustypen sind selektierbar: ✅ erfolgreich, ⚠️ retryable, ❌ permanent, ⏭️ übersprungen
• Die Selektion bleibt nach Aktionen erhalten, bis ein neuer Lauf gestartet wird

Button „Erneut verarbeiten"

Wann nutzen: Der KI-Prompt wurde geändert, das Modell gewechselt oder die Verarbeitung einer Datei muss aus anderen Gründen wiederholt werden – und das Ergebnis soll sofort verfügbar sein.

Was passiert:

1. Wird ein Button-Klick ausgelöst, wird die aktuelle Selektion als Snapshot erfasst
2. Der DB-Status aller selektierten Einträge wird zurückgesetzt
3. Ein Mini-Lauf startet sofort und verarbeitet nur diese Dateien
4. Unselektierte Einträge bleiben unverändert in der Liste
5. Die Mini-Lauf-Ergebnisse werden live in den selektierten Zeilen aktualisiert

Besonderheiten:

• Verarbeitet die KI wieder denselben Dateinamen wie der vorherige erfolgreiche Lauf, erfolgt keine erneute Kopie – der Eintrag erhält Status ✅ erfolgreich
• Ist die Quelldatei nicht mehr vorhanden, erhält der Eintrag Status ❌ permanent fehlgeschlagen mit Meldung „Quelldatei nicht gefunden"

Button-Status:

• Aktiv: kein Lauf aktiv UND mindestens 1 Eintrag selektiert
• Inaktiv: Lauf läuft ODER keine Selektion

Button „Status zurücksetzen"

Wann nutzen: Eine Datei soll später erneut verarbeitet werden, aber nicht sofort – z. B. nach Behebung eines externen Fehlers oder planmäßig im nächsten regulären Lauf.

Was passiert:

1. Der DB-Status aller selektierten Einträge wird zurückgesetzt
2. Betroffene Zeilen erhalten die Kennzeichnung „Zurückgesetzt – wartet auf nächsten Lauf"
3. Kein sofortiger Mini-Lauf
4. Beim nächsten regulären Lauf werden diese Dateien automatisch mitgenommen

Fehlerbehandlung (Best-effort):

• Resets werden pro Eintrag einzeln durchgeführt
• Erfolgreiche und fehlgeschlagene Resets werden separat gezählt
• Zusammenfassung im Meldungsbereich zeigt:
  • Anzahl ausgewählter Einträge
  • Anzahl erfolgreich zurückgesetzt
  • Anzahl fehlgeschlagen + betroffene Dateinamen

Button-Status:

• Aktiv: kein Lauf aktiv UND mindestens 1 Eintrag selektiert
• Inaktiv: Lauf läuft ODER keine Selektion

Verhalten während eines Mini-Laufs

• Der Abbrechen-Button löst einen Soft-Stop auch für Mini-Läufe aus:
  • bereits verarbeitete Einträge behalten ihren neuen Endstatus
  • noch nicht gestartete, aber bereits zurückgesetzte Einträge erhalten Status „Zurückgesetzt – wartet auf nächsten Lauf" und werden beim nächsten regulären Lauf mitgenommen
• Tab 1 „Konfiguration" ist während des Mini-Laufs gesperrt
• Der Fortschrittsbalken zeigt den Fortschritt für die ausgewählte Dateimenge (Nenner = Anzahl selektierter Dateien)
• Beide Buttons „Erneut verarbeiten" und „Status zurücksetzen" sind deaktiviert

---

13b. PDF-Vorschau und editierbarer Dateiname im Verarbeitungslauf-Tab

Nach Abschluss eines Verarbeitungslaufs (oder während laufender Verarbeitung) zeigt ein Klick auf eine Zeile in der Ergebnisliste ein Detail-Panel auf der rechten Seite. Das Panel enthält drei Bereiche:

PDF-Vorschau

• Zeigt die Quelldatei der gewählten Zeile als Vorschau an.
• Lazy Rendering: Seite 1 wird sofort geladen; weitere Seiten werden erst bei Bedarf gerendert.
• In-Memory-Cache: Bereits gerenderte Seiten werden pro Zeilenselektion zwischengespeichert. Bei einem Zeilenwechsel wird der Cache der vorherigen Auswahl verworfen.
• Seitennavigation: Über die Schaltflächen „◀" und „▶" (oder das Mausrad) kann seitenweise geblättert werden. Die aktuelle Seitenzahl und Gesamtseitenzahl werden angezeigt.
• 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.

Für Einträge mit Status FAILED_* wird – sofern kein KI-Reasoning vorliegt – stattdessen eine übersetzte Fehlermeldung angezeigt (Präfix ⚠), zum Beispiel:

• „PDF enthält keinen lesbaren Text. Möglicherweise handelt es sich um einen Scan ohne Texterkennung (OCR). Eine automatische Benennung ist nicht möglich."
• „KI-Dienst: Ungültiger API-Schlüssel. Bitte in den Einstellungen prüfen."
• „KI-Dienst nicht erreichbar. Bitte Verbindung und Konfiguration prüfen."

Für SKIPPED_ALREADY_PROCESSED-Einträge erscheint der Zeitpunkt des letzten erfolgreichen Verarbeitungslaufs, sofern er in der Datenbank vorliegt.

Liegt weder Reasoning noch Fehlermeldung vor, erscheint der Hinweis „Für diesen Eintrag liegt kein KI-Reasoning vor.".

Editierbarer Dateiname

Unterhalb des Reasoning-Bereichs befindet sich ein editierbares Textfeld mit dem Dateinamen des ausgewählten Eintrags (ohne .pdf-Erweiterung; .pdf wird als nicht editierbares Label daneben angezeigt).

Aktivitätszustand je Zeilenstatus

Zeilenstatus	Textfeld-Verhalten
Kein Eintrag selektiert	Leer, deaktiviert
SUCCESS	Editierbar; letzter gespeicherter Name vorausgefüllt. Ermöglicht Umbenennung der vorhandenen Zieldatei.
SKIPPED_ALREADY_PROCESSED	Editierbar (sofern historischer Dateiname vorhanden). Ermöglicht Umbenennung der vorhandenen Zieldatei.
FAILED_RETRYABLE, FAILED_PERMANENT, SKIPPED_FINAL_FAILURE	Editierbar; Feld leer. Erlaubt Eingabe eines manuellen Dateinamens für eine direkte Kopie der Quelldatei.
Zurückgesetzt (⟳)	Deaktiviert
Lauf aktiv	Vollständig deaktiviert

Das Feld kann direkt bearbeitet werden. Die Eingabe wird live validiert (Formatprüfung YYYY-MM-DD - Titel.pdf, Titelzeichen, Länge).

• Fehlerhafte Eingaben werden direkt unter dem Feld als rote Meldung angezeigt.
• Speichern: Der Button „Übernehmen" führt die Umbenennung durch – atomare Dateisystem- und DB-Transaktion inkl. automatischer Rollback bei Fehler. Namenskonflikte im Zielordner werden über ein Dubletten-Suffix aufgelöst.
• Zurücksetzen: Der Button „Zurücksetzen" verwirft die Änderungen und stellt den zuletzt persistierten Dateinamen wieder her.
• Wird die Zeile gewechselt oder der Tab verlassen, während ungespeicherte Änderungen vorliegen, erscheint ein Schutzdialog mit den Optionen „Speichern", „Verwerfen" und „Abbrechen".
• Während eines laufenden Verarbeitungslaufs ist das Dateiname-Feld gesperrt.

---

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. Tab „Scheduler" (automatische Verarbeitungsläufe)

Der dritte Tab „Scheduler" ermöglicht den Betrieb eines optionalen, periodisch ausgeführten automatischen Schedulers. Er startet Verarbeitungsläufe in einem konfigurierten Intervall, ohne dass ein manueller Start erforderlich ist.

Voraussetzung

Damit der Scheduler-Tab funktioniert, muss in der gespeicherten Konfigurationsdatei scheduler.enabled=true und ein gültiges scheduler.interval.seconds (Integer >= 30) eingetragen sein. Ungültige oder fehlende Werte werden im Tab als Fehler gemeldet; der Scheduler-Start ist in diesem Fall nicht möglich.

Start und Stop

• „Scheduler starten" – Aktiviert den Scheduler. Der erste Lauf beginnt unmittelbar nach dem Start (kein initiales Warten auf das Intervall).
• „Scheduler stoppen" – Stoppt den Scheduler. Ein laufender Verarbeitungslauf wird als Soft-Stop behandelt: die aktuell bearbeitete Datei wird fertig verarbeitet, danach hält der Scheduler an.

Beide Buttons wechseln je nach Zustand ihre Sichtbarkeit: Nur der zum aktuellen Zustand passende Button ist aktiv.

Statusanzeige

Der Tab zeigt den aktuellen Scheduler-Zustand in Echtzeit (1-Sekunden-Takt):

Zustand	Anzeige
STOPPED	Scheduler gestoppt
STARTING	Scheduler wird gestartet …
RUNNING_IDLE	Scheduler läuft – nächster Lauf in HH:MM:SS
RUNNING_BATCH_ACTIVE	Scheduler läuft – Verarbeitungslauf aktiv
STOPPING_BATCH_ACTIVE	Scheduler wird gestoppt – Lauf läuft noch …

Im Zustand RUNNING_IDLE zeigt der Tab einen Countdown bis zum nächsten automatischen Verarbeitungslauf.

Informationen zum letzten Lauf

Der Tab zeigt:

• Letzter Lauf beendet: Zeitpunkt des letzten abgeschlossenen Verarbeitungslaufs (oder „–" wenn noch kein Lauf stattfand).
• Zusammenfassung: Anzahl erfolgreich, wiederholt, fehlgeschlagen und übersprungen des letzten Laufs (falls verfügbar).
• Letzter Fehler: Fehlermeldung des letzten nicht erfolgreichen Scheduler-Laufs, sofern vorhanden.

Autostart-Fehler

Ist scheduler.enabled=true in der Konfiguration, versucht die GUI den Scheduler beim Start automatisch zu aktivieren. Schlägt dies fehl (z. B. ungültige Konfiguration, Intervall < 30 Sekunden), wird der Fehler im Tab angezeigt. Der Benutzer kann dann die Konfiguration korrigieren und den Scheduler manuell starten.

Warum sind manuelle Läufe während eines aktiven Schedulers gesperrt?

Manuelle Läufe (Tab „Verarbeitungslauf") sind während eines aktiven Schedulers deaktiviert. Dadurch werden parallele Läufe auf dieselbe Datenmenge vermieden, die zu inkonsistenten Datenbankzuständen führen könnten. Der Start-Button im Tab „Verarbeitungslauf" ist während eines aktiven Schedulers deaktiviert und zeigt einen erklärenden Tooltip.

Warum ist Tab 1 „Konfiguration" während eines aktiven Schedulers gesperrt?

Um sicherzustellen, dass der Scheduler mit einer konsistenten Konfiguration läuft, ist der Konfigurations-Editor während eines aktiven Schedulers gesperrt. Ein Hinweisbanner erklärt die Sperre. Konfigurationsänderungen können nach dem Stoppen des Schedulers vorgenommen werden.

Schließen der Anwendung

Versucht der Benutzer das Fenster zu schließen oder die Anwendung über das Tray-Menü zu beenden, während der Scheduler aktiv ist oder ein Lauf läuft, erscheint ein Informationsdialog mit dem Hinweis, den Scheduler zunächst zu stoppen bzw. den laufenden Verarbeitungslauf abzuwarten. Das Schließen wird blockiert, bis der Scheduler gestoppt und kein Lauf mehr aktiv ist.

---

15. Bekannte Einschränkungen

Einschränkung	Erläuterung
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. Die dauerhaften Ergebnisse sind im Verlauf-Tab (Abschnitt 17) 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.

---

16. System-Tray

Wird das Hauptfenster über das Schließen-Symbol (oder Alt+F4) geschlossen, ohne dass ungespeicherte Änderungen oder ein aktiver Verarbeitungslauf vorliegen, minimiert sich die Anwendung in den Windows System-Tray statt sich zu beenden. Das Fenster bleibt im Hintergrund aktiv und ist über das Tray-Icon wieder erreichbar.

15.1 Tray-Icon-Menü

Ein Rechtsklick auf das Tray-Icon öffnet ein Kontextmenü:

Eintrag	Wirkung
Öffnen	Bringt das Hauptfenster in den Vordergrund
Beenden	Beendet die Anwendung vollständig

Ein Doppelklick auf das Tray-Icon hat denselben Effekt wie „Öffnen".

15.2 Sonderfälle beim Schließen

Situation	Verhalten
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

---

17. 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 20)
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 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:

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 (lesbarer Anzeigetext, kein Enum-Rohname)
Provider	Verwendeter KI-Provider
Modell	Verwendetes Sprachmodell
Vorgeschlagener Name	Vom Versuch erzeugter Zieldateiname

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. Beide Aktionen unterstützen Mehrfachauswahl (≥ 1 Eintrag):

„Status zurücksetzen"

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: „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 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: „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. Nach Laufende werden die Buttons automatisch reaktiviert, sofern eine Auswahl besteht – ohne dass der Benutzer die Auswahl erneuern muss.

---

17a. 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.

---

18. 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.

---

19. 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.

---

20. 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 17) 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.

---

21. 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 20)
• 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.