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/betrieb.md
+187 -11
View File
@@ -8,10 +8,70 @@ und legt eine Kopie im konfigurierten Zielordner ab. Die Quelldatei bleibt unver
---
## Startmodi und Betriebsmodell (V2.0)
Ab V2.0 enthält die Anwendung zwei Startmodi in **einem gemeinsamen ausführbaren JAR**:
| Startmodus | Beschreibung |
|---|---|
| **GUI-Start** (Standard) | Öffnet die JavaFX-Desktop-GUI. Wird verwendet, wenn kein `--headless` angegeben ist. |
| **headless Betrieb** | Klassischer Batch-/Scheduler-Betrieb ohne grafische Oberfläche. Wird über `--headless` aktiviert. |
### CLI-Optionen
| Option | Beschreibung |
|---|---|
| *(keine Argumente)* | GUI-Standardstart |
| `--headless` | Aktiviert den headless Batch-Betrieb (wie vor V2.0) |
| `--config <pfad>` | Zeigt explizit auf eine `.properties`-Konfigurationsdatei (für GUI und headless) |
`--config` und `--headless` können kombiniert werden:
```
java -jar pdf-umbenenner-bootstrap-*.jar --headless --config C:\Pfad\zur\config.properties
```
### Verhalten bei fehlender oder ungültiger `--config`-Datei
| Startmodus | Datei nicht vorhanden | Datei vorhanden, aber ungültig |
|---|---|---|
| **headless** | Harter Startfehler, Exit-Code `1`, kein Fallback | Harter Startfehler, Exit-Code `1` |
| **GUI** | Fehlermeldung in der GUI, danach Verhalten wie ohne `--config` (Willkommenstext) | Fehlermeldung in der GUI, Konfiguration nicht geladen |
Im headless Betrieb ist ein nicht vorhandener `--config`-Pfad ein **harter Startfehler**. Ein stiller
Fallback auf das Default-Verhalten ist in diesem Fall ausdrücklich unzulässig.
### Verhalten bei GUI-Startfehlern
Tritt vor der erfolgreichen Anzeige der grafischen Oberfläche ein nicht behebbarer Fehler auf
(z. B. fehlende JavaFX-Laufzeit, Bootstrap-Fehler), beendet sich die Anwendung mit Exit-Code `1`.
### Plattform und Laufwerksbuchstaben
Die GUI wird **offiziell nur unter Windows** unterstützt. Der headless Betrieb bleibt für den
Windows Server-Betrieb geeignet.
Gemappte Netzlaufwerke wie `S:\` oder `H:\` werden ausdrücklich unterstützt. Eine Ablehnung
solcher Pfade allein wegen eines dahinterliegenden UNC-Pfads ist unzulässig.
### Umfang der V2.0-GUI
Die GUI in V2.0 dient ausschließlich als:
- **Konfigurationseditor** für die `.properties`-Datei
- **Validierungsoberfläche** (automatische und explizite Prüfung des Konfigurationsstands)
- **Technische Testoberfläche** (Erreichbarkeit des Providers, Pfade, SQLite-Datei, Prompt-Datei)
Die GUI enthält in V2.0 **keinen** manuellen Verarbeitungslauf. Das Starten eines Batch-Laufs
aus der GUI ist erst ab V2.1+ vorgesehen. Der headless Betrieb über den Windows Task Scheduler
bleibt der einzige Weg, PDF-Dateien automatisiert zu verarbeiten.
---
## Voraussetzungen
- Java 21 (JRE oder JDK)
- Zugang zu einem OpenAI-kompatiblen KI-Dienst (API-Schlüssel erforderlich)
- Zugang zu einem KI-Dienst (API-Schlüssel erforderlich; unterstützte Provider: OpenAI-kompatibel, Anthropic Claude)
- Quellordner mit OCR-verarbeiteten PDF-Dateien
- Schreibzugriff auf Zielordner und Datenbankverzeichnis
@@ -26,16 +86,24 @@ Das ausführbare JAR wird durch den Maven-Build im Verzeichnis
java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar
```
Die Anwendung liest die Konfiguration aus `config/application.properties` relativ zum
Ohne weitere Argumente öffnet sich die **GUI** (Standardstart ab V2.0).
Für den **headless Betrieb** (Batch-/Scheduler-Start):
```
java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar --headless
```
Die Anwendung liest die Konfiguration standardmäßig aus `config/application.properties` relativ zum
Arbeitsverzeichnis, in dem der Befehl ausgeführt wird.
### Start über Windows Task Scheduler
Empfohlene Startsequenz für den Windows Task Scheduler:
Empfohlene Startsequenz für den headless Betrieb über den Windows Task Scheduler:
1. Aktion: Programm/Skript starten
2. Programm: `java`
3. Argumente: `-jar C:\Pfad\zur\Installation\pdf-umbenenner-bootstrap\target\pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar`
3. Argumente: `-jar C:\Pfad\zur\Installation\pdf-umbenenner-bootstrap\target\pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar --headless`
4. Starten in: `C:\Pfad\zur\Installation` (muss das Verzeichnis mit `config\application.properties` und `config\prompts\` enthalten)
> **Hinweis:** Das „Starten in"-Verzeichnis ist das Arbeitsverzeichnis der Anwendung.
@@ -43,11 +111,26 @@ Empfohlene Startsequenz für den Windows Task Scheduler:
> `config/prompts/` müssen relativ zu diesem Verzeichnis erreichbar sein. Der JAR-Pfad
> in den Argumenten muss absolut oder relativ zum Starten-in-Verzeichnis korrekt angegeben sein.
Alternativ kann über `--config` ein expliziter Konfigurationspfad angegeben werden:
```
java -jar ... --headless --config S:\Betrieb\meine-config.properties
```
> **Wichtig:** Zeigt `--config` auf eine nicht vorhandene Datei, bricht die Anwendung mit Exit-Code `1` ab.
> Es findet kein stiller Fallback auf `config/application.properties` statt.
---
## Konfiguration
Die Konfiguration wird aus `config/application.properties` geladen.
Ein vollständiges Konfigurationsbeispiel mit allen unterstützten Parametern,
realistischen Windows-Pfaden und erklärenden Kommentaren liegt unter:
- [`docs/examples/application.properties`](examples/application.properties)
Vorlagen für lokale und Test-Konfigurationen befinden sich in:
- `config/application-local.example.properties`
@@ -155,16 +238,17 @@ Der Dateiname der Prompt-Datei dient als Prompt-Identifikator in der Versuchshis
(SQLite) und ermöglicht so die Nachvollziehbarkeit, welche Prompt-Version für welchen
Verarbeitungsversuch verwendet wurde.
Eine Vorlage befindet sich in `config/prompts/template.txt` und kann direkt verwendet oder
an den jeweiligen KI-Dienst angepasst werden.
Eine angepasste Vorlage befindet sich in `config/prompts/template.txt` und kann direkt
verwendet oder an den jeweiligen KI-Dienst angepasst werden.
Fehlt die konfigurierte Prompt-Datei, erzeugt die GUI beim Ausführen der technischen Tests
automatisch eine deutsche Standardvorlage am konfigurierten Pfad. Ein Beispiel dieser
Standardvorlage liegt unter [`docs/examples/prompt.txt`](examples/prompt.txt).
Die Anwendung ergänzt den Prompt automatisch um:
- einen Dokumenttext-Abschnitt
- eine explizite JSON-Antwortspezifikation mit den Feldern `title`, `reasoning` und `date`
Der Prompt in `template.txt` muss deshalb **keine** JSON-Formatanweisung enthalten –
nur den inhaltlichen Auftrag an die KI.
---
## Zielformat
@@ -279,11 +363,103 @@ Sie muss nicht manuell verwaltet werden – das Schema wird beim Start automatis
---
## Build und Packaging
### Gemeinsames ausführbares JAR
Die gesamte Anwendung wird als **ein einziges ausführbares JAR** ausgeliefert, das GUI-Start
und headless Batch-Betrieb vereint. Eine separate JavaFX-Installation ist nicht erforderlich.
Das JAR wird vom Maven-Shade-Plugin im Modul `pdf-umbenenner-bootstrap` erzeugt.
Nach einem erfolgreichen Build liegt es unter:
```
pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar
```
Dieses JAR enthält alle Abhängigkeiten inklusive der JavaFX-Plattformbibliotheken
für Windows (Classifier `win`). Die nativen JavaFX-DLLs werden beim GUI-Start
von JavaFX selbst in ein temporäres Verzeichnis extrahiert.
### Integrierte JavaFX-Laufzeit
JavaFX ist als Maven-Dependency im Modul `pdf-umbenenner-adapter-in-gui` mit
Windows-Classifier deklariert (`javafx-base:win`, `javafx-graphics:win`,
`javafx-controls:win`). Das Shade-JAR schließt diese Bibliotheken ein, sodass
der GUI-Start ohne separate JavaFX-Installation auf dem Zielsystem funktioniert.
Nur das Modul `pdf-umbenenner-adapter-in-gui` hängt direkt von JavaFX ab.
Die Module `domain`, `application`, `adapter-in-cli` und `adapter-out` sind
vollständig JavaFX-frei.
### Headless-Start ohne JavaFX-Initialisierung
Beim headless Start (`--headless`) wird JavaFX **nicht** initialisiert. Der
`GuiAdapter` wird nur dann instanziiert und gestartet, wenn der Startmodus GUI ist.
JavaFX-Klassen sind zwar im Shade-JAR enthalten, werden im headless Pfad jedoch
nicht geladen. Headless läuft damit auch auf Windows Server-Systemen ohne
JavaFX-fähige Grafiklaufzeit.
### Keine EXE, kein Installer
In V2.0 wird ausschließlich das JAR als Distributionsartefakt ausgeliefert.
EXE-Wrapper und Installer sind bewusst nicht Bestandteil von V2.0.
### Build-Kommandos
**Vollständiger Reactor-Build** (alle Module, Tests, Packaging):
```powershell
.\mvnw.cmd clean verify
```
Auf Unix-Systemen (headless CI):
```bash
./mvnw clean verify
```
**Nur das ausführbare JAR erzeugen** (überspringt Tests):
```powershell
.\mvnw.cmd clean package -pl pdf-umbenenner-bootstrap --also-make -DskipTests
```
**Selektiver Reactor-Build** (ohne Coverage-Modul, z. B. während der Entwicklung):
```powershell
.\mvnw.cmd clean verify -pl pdf-umbenenner-domain,pdf-umbenenner-application,pdf-umbenenner-adapter-out,pdf-umbenenner-adapter-in-cli,pdf-umbenenner-adapter-in-gui,pdf-umbenenner-bootstrap --also-make
```
### Technische Hinweise zum Shade-JAR
- Signaturdateien (`*.SF`, `*.DSA`, `*.RSA`) signierter JARs (u. a. JavaFX) werden
beim Shading entfernt, da sie im zusammengeführten JAR ungültig wären.
- JPMS-Moduldeskriptoren (`module-info.class`) werden entfernt, da JavaFX als
modulares Framework mit dem nicht-modularen Fat-JAR-Modell kollidieren würde.
- `META-INF/services`-Einträge aus allen Abhängigkeiten werden durch den
`ServicesResourceTransformer` zusammengeführt statt überschrieben.
- Der Main-Class-Eintrag im Manifest verweist auf
`de.gecheckt.pdf.umbenenner.bootstrap.PdfUmbenennerApplication`.
Diese Klasse erweitert bewusst **nicht** `javafx.application.Application`,
um den JavaFX-Modul-System-Launcher-Check zu umgehen, der Fat-JAR-Ausführung
blockieren würde. Der GUI-Pfad ruft `Application.launch(...)` explizit auf.
---
## Weitere Dokumentation
Die Bedienung der GUI ist in [`gui-bedienanleitung.md`](gui-bedienanleitung.md) beschrieben.
---
## Systemgrenzen
- Nur OCR-verarbeitete, durchsuchbare PDF-Dateien werden verarbeitet
- Keine eingebaute OCR-Funktion
- Kein Web-UI, keine REST-API, keine interaktive Bedienung
- Kein interner Scheduler – der Start erfolgt extern (z. B. Windows Task Scheduler)
- Kein Web-UI, keine REST-API
- Die GUI (V2.0) dient der Konfiguration, Validierung und technischen Diagnose – **kein** manueller Verarbeitungslauf aus der GUI
- Kein interner Scheduler – der Batch-Betrieb wird extern angestoßen (z. B. Windows Task Scheduler, `--headless`)
- Quelldateien werden nie überschrieben, verschoben oder gelöscht
- Die Identifikation erfolgt über SHA-256-Fingerprint des Dateiinhalts, nicht über Dateinamen
- Die GUI wird offiziell nur unter Windows unterstützt; der headless Betrieb ist für Windows Server geeignet