# 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 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).

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.

---

## 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`](../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

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 `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 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 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-view:** Die Seite wird automatisch an die verfügbare Fläche angepasst
  (preserveRatio=true). Keine Scrollbalken, keine manuelle Zoom-Einstellung.
- Das Rendering erfolgt direkt über Apache PDFBox bei 120 DPI.

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

---

## 15. 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 |

---

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