marcus/pdf-umbenenner
1
0
Fork 0
Code Issues 14 Releases 2 Activity

M13 vollständig abgeschlossen: V2.0-Freigabe (AP-001 bis AP-009)

Browse Source 
- AP-001: Betriebs- und Startdokumentation für GUI und headless
  konsolidiert (betrieb.md, README.md)
- AP-002: Endbenutzer-Bedienanleitung gui-bedienanleitung.md angelegt
  (deskriptiv, 13 Kapitel, deutsch, Windows-Hinweise)
- AP-003: Konfigurationsbeispiele docs/examples/application.properties
  und docs/examples/prompt.txt konsolidiert, konsistent mit Standardvorlage
- AP-004: Regressionstests für headless Abwärtskompatibilität
  (JAR-Smoke-IT mit --config-Varianten und JavaFX-Freiheit)
- AP-005: GUI-Smoke-Tests für V2.0-Kernumfang vervollständigt
  (Startup-Notice-Sichtbarkeit im Header)
- AP-006: Build- und Packaging-Dokumentation im Abschnitt
  "Build und Packaging" in betrieb.md, README-Artefaktnamen korrigiert
- AP-007: Integrierte Gesamtprüfung durchgeführt, V2.0-Abschnitt in
  befundliste.md — keine Release-Blocker, zwei nicht blockierende
  Restpunkte (R1 ByteBuddy-Warning, R2 fehlender visueller GUI-Render-Test)
- AP-008: entfiel (keine Release-Blocker zu beheben)
- AP-009: Finale Gesamtprüfung, Freigabedokument docs/freigabe-v2_0.md
  mit Git-HEAD, Build-/Test-Ergebnissen, Freigabeaussage. Ein während
  der Stichprobe entdeckter Doku-Defekt (R3: API-Key-Legacy-Variable)
  wurde unmittelbar in gui-bedienanleitung.md korrigiert.

V2.0 ist freigabefähig. 1.403 Tests grün, 0 Failures, 0 Errors.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
Marcus van Elst
2026-04-20 22:50:51 +02:00
parent 1bb7a42735
commit 016da8318d
10 changed files with 1399 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/gui-bedienanleitung.md
+405
View File
@@ -0,0 +1,405 @@
# 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 in V2.0
Die GUI dient in V2.0 ausschließlich als:
- **Konfigurationseditor** für die `.properties`-Datei
- **Validierungsoberfläche** für den aktuellen Konfigurationsstand
- **Technische Test- und Diagnoseoberfläche** für Erreichbarkeit des Providers,
Pfadprüfungen und Ressourcenverfügbarkeit
Die GUI enthält in V2.0 **keinen** manuellen Verarbeitungslauf. Das Starten eines
Batch-Laufs aus der GUI ist erst ab einer späteren Ausbaustufe vorgesehen.
Ebenso gibt es keinen Historien-Tab, keine Datenbankansicht und kein Kosten-Tracking.
Der headless Batch-/Scheduler-Betrieb über `--headless` bleibt der einzige Weg,
PDF-Dateien automatisiert zu verarbeiten.
---
## 2. Startzustände
### 2.1 GUI-Standardstart
Wird die Anwendung ohne CLI-Argumente gestartet, öffnet sich die JavaFX-Desktop-GUI.
Es wird keine Konfigurationsdatei automatisch geladen.
Stattdessen zeigt die GUI einen deutschen Willkommenstext mit dem Hinweis, über
„Neu" eine Standardvorlage zu erzeugen oder über „Öffnen" eine bestehende
`.properties`-Datei zu laden.
### 2.2 Start mit `--config <pfad>` (gültige Datei)
Wird beim Start eine gültige `.properties`-Datei über `--config <pfad>` angegeben,
lädt die GUI diese Datei automatisch und zeigt den Inhalt im Editor an. Der Pfad
wird im Header angezeigt.
### 2.3 Start mit `--config <pfad>` (ungültiger oder nicht vorhandener Pfad)
Zeigt der angegebene Pfad auf eine nicht vorhandene oder nicht lesbare Datei,
erscheint eine Fehlermeldung im zentralen Meldungsbereich. Danach verhält sich die
GUI so, als wäre `--config` nicht angegeben worden: Es erscheint der Willkommenstext,
und der Benutzer kann manuell eine Datei öffnen oder eine neue Konfiguration anlegen.
Im Unterschied zum headless Betrieb ist dies kein harter Startfehler – die GUI
bleibt vollständig bedienbar.
### 2.4 GUI-Startfehler vor Anzeige der Oberfläche
Tritt vor der erfolgreichen Anzeige der grafischen Oberfläche ein nicht behebbarer
Fehler auf (z. B. fehlende JavaFX-Laufzeit, schwerwiegender Bootstrap-Fehler),
beendet sich die Anwendung mit Exit-Code `1`. In diesem Fall wird keine Oberfläche
angezeigt.
---
## 3. Header und Meldungsbereich
### 3.1 Header
Der Header oben im Fenster zeigt den Pfad der aktuell geladenen `.properties`-Datei.
Ist keine Datei geladen, bleibt der Pfadbereich leer oder zeigt einen entsprechenden
Hinweis.
Sobald ungespeicherte Änderungen vorliegen, erscheinen zwei visuelle Markierungen:
- ein kleines **„geändert"**-Label im Header
- ein führendes **`*`** im Fenstertitel
Diese Markierungen verschwinden, sobald die Datei gespeichert wurde oder Änderungen
verworfen werden.
### 3.2 Zentraler Meldungsbereich
Am unteren Ende der GUI befindet sich ein großer, nicht editierbarer
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.
---
## 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 |
`max.pages` wird als Plausibilitäts- und Performance-Hinweis behandelt.
---
## 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. Bekannte Einschränkungen V2.0
| Einschränkung | Erläuterung |
|---|---|
| Kein manueller Verarbeitungslauf | Das Starten eines Batch-Laufs aus der GUI ist erst ab V2.1+ vorgesehen |
| 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 | Läuft gleichzeitig ein headless Batch-Lauf, koordinieren sich GUI und headless Betrieb nicht. Schreibkonflikte können entstehen, wenn dieselbe `.properties`-Datei gleichzeitig über die GUI gespeichert und vom headless Lauf gelesen wird |
| GUI nur für Windows | Die GUI wird offiziell nur unter Windows unterstützt; der headless Betrieb ist für Windows Server geeignet |