708 lines
31 KiB
Markdown
708 lines
31 KiB
Markdown
# GUI-Bedienanleitung – PDF-Umbenenner V2.0
|
||
|
||
Diese Anleitung beschreibt die JavaFX-Desktop-GUI des PDF-Umbenenners. Sie richtet sich an
|
||
Endbenutzer und Betreuer, die die Konfiguration der Anwendung über die grafische Oberfläche
|
||
verwalten und technisch prüfen möchten.
|
||
|
||
---
|
||
|
||
## 1. Zweck und Scope der GUI
|
||
|
||
Die GUI gliedert sich in zwei feste Tabs:
|
||
|
||
- **Tab 1 „Konfiguration"** – Editor, Validierungsoberfläche und technische
|
||
Test-/Diagnoseoberfläche für die `.properties`-Datei.
|
||
- **Tab 2 „Verarbeitungslauf"** – Start eines Batch-Laufs aus der GUI mit
|
||
Live-Fortschritt, Ergebnisliste und KI-Begründung je Dokument (siehe Abschnitt 13).
|
||
|
||
Weiterhin **nicht** enthalten sind ein Historien-Tab, eine Datenbankansicht und ein
|
||
Kosten-Tracking — diese Ausbauten sind für spätere Stufen vorbehalten.
|
||
|
||
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) |
|
||
| `≡` | Blau | Übersprungen (bereits erfolgreich verarbeitet) |
|
||
| `⊘` | Grau | Übersprungen (endgültig fehlgeschlagen) |
|
||
| `⟳` | Grau | Zurückgesetzt – wartet auf nächsten Lauf |
|
||
|
||
- Ein Klick auf eine Zeile öffnet den Detailbereich rechts. Für `FAILED_*`-Einträge
|
||
zeigt der Detailbereich eine übersetzte Fehlermeldung (Präfix `⚠`) anstelle des
|
||
KI-Reasonings. Liegt weder Reasoning noch Fehlermeldung vor, erscheint der
|
||
Hinweistext „Für diesen Eintrag liegt kein KI-Reasoning vor.".
|
||
- Nach Laufende erscheint die Zusammenfassung `X erfolgreich, Y fehlgeschlagen,
|
||
Z übersprungen` im Meldungs- und Zusammenfassungsbereich.
|
||
|
||
### 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**.
|
||
|
||
---
|
||
|
||
## 14. Bekannte Einschränkungen V2.x
|
||
|
||
| Einschränkung | Erläuterung |
|
||
|---|---|
|
||
| Kein Historien-Tab | Eine Ansicht der SQLite-Datenbank und Verarbeitungshistorie ist für spätere Ausbaustufen vorbehalten |
|
||
| Kein Kosten-Tracking | Token-/Preisberechnungen sind für spätere Ausbaustufen vorbehalten |
|
||
| Keine Erkennung externer Änderungen | Wird die `.properties`-Datei während einer GUI-Sitzung von außen geändert, erkennt die GUI dies nicht. Die GUI arbeitet weiterhin auf dem zuletzt geladenen Stand |
|
||
| Keine Koordination mit parallelen headless Läufen | Ein gleichzeitiger externer headless Lauf wird nicht technisch geblockt. Schreibkonflikte sind nicht ausgeschlossen, wenn dieselbe `.properties`-Datei parallel genutzt wird |
|
||
| GUI nur für Windows | Die GUI wird offiziell nur unter Windows unterstützt; der headless Betrieb ist für Windows Server geeignet |
|
||
| Ergebnisliste nicht persistent | Die Ergebnisliste im Verarbeitungslauf-Tab existiert nur für den aktuellen Programmstart; nach Neustart ist die Liste leer |
|
||
| 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 |
|
||
|
||
---
|
||
|
||
## 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 |
|