pdf-umbenenner/docs/betrieb.md

Betriebsdokumentation – PDF Umbenenner

Zweck

Der PDF Umbenenner liest bereits OCR-verarbeitete, durchsuchbare PDF-Dateien aus einem konfigurierten Quellordner, ermittelt per KI-Aufruf einen normierten deutschen Dateinamen und legt eine Kopie im konfigurierten Zielordner ab. Die Quelldatei bleibt unverändert.

---

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 KI-Dienst (API-Schlüssel erforderlich; unterstützte Provider: OpenAI-kompatibel, Anthropic Claude)
• Quellordner mit OCR-verarbeiteten PDF-Dateien
• Schreibzugriff auf Zielordner und Datenbankverzeichnis

---

Start des ausführbaren JAR

Das ausführbare JAR wird durch den Maven-Build im Verzeichnis pdf-umbenenner-bootstrap/target/ erzeugt:

java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar

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 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 --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. Die Konfigurationsdatei config/application.properties sowie das Prompt-Verzeichnis 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

Vorlagen für lokale und Test-Konfigurationen befinden sich in:

• config/application-local.example.properties
• config/application-test.example.properties

Pflichtparameter (allgemein)

Parameter	Beschreibung
source.folder	Quellordner mit OCR-PDFs (muss vorhanden und lesbar sein)
target.folder	Zielordner für umbenannte Kopien (wird angelegt, wenn nicht vorhanden)
sqlite.file	SQLite-Datenbankdatei (übergeordnetes Verzeichnis muss existieren)
ai.provider.active	Aktiver KI-Provider: openai-compatible oder claude
max.retries.transient	Maximale transiente Fehlversuche pro Dokument (ganzzahlig, >= 1)
max.pages	Maximale Seitenzahl pro Dokument (ganzzahlig, > 0)
max.text.characters	Maximale Zeichenanzahl des Dokumenttexts für KI-Anfragen (ganzzahlig, > 0)
prompt.template.file	Pfad zur externen Prompt-Datei (muss vorhanden sein)

Provider-Parameter

Nur der aktive Provider muss vollständig konfiguriert sein. Der inaktive Provider wird nicht validiert.

OpenAI-kompatibler Provider (ai.provider.active=openai-compatible):

Parameter	Beschreibung
ai.provider.openai-compatible.baseUrl	Basis-URL des KI-Dienstes (z. B. https://api.openai.com/v1)
ai.provider.openai-compatible.model	Modellname (z. B. gpt-4o-mini)
ai.provider.openai-compatible.timeoutSeconds	HTTP-Timeout in Sekunden (ganzzahlig, > 0)
ai.provider.openai-compatible.apiKey	API-Schlüssel (Umgebungsvariable OPENAI_COMPATIBLE_API_KEY hat Vorrang)

Anthropic Claude-Provider (ai.provider.active=claude):

Parameter	Beschreibung
ai.provider.claude.baseUrl	Basis-URL (optional; Standard: https://api.anthropic.com)
ai.provider.claude.model	Modellname (z. B. claude-3-5-sonnet-20241022)
ai.provider.claude.timeoutSeconds	HTTP-Timeout in Sekunden (ganzzahlig, > 0)
ai.provider.claude.apiKey	API-Schlüssel (Umgebungsvariable ANTHROPIC_API_KEY hat Vorrang)

Optionale Parameter

Parameter	Beschreibung	Standard
runtime.lock.file	Lock-Datei für Startschutz	pdf-umbenenner.lock im Arbeitsverzeichnis
log.directory	Log-Verzeichnis	./logs/
log.level	Log-Level (DEBUG, INFO, WARN, ERROR)	INFO
log.ai.sensitive	KI-Rohantwort und Reasoning ins Log schreiben (true/false)	false

API-Schlüssel

Pro Provider-Familie existiert eine eigene Umgebungsvariable, die Vorrang vor dem Properties-Wert hat:

Provider	Umgebungsvariable
openai-compatible	OPENAI_COMPATIBLE_API_KEY
claude	ANTHROPIC_API_KEY

Schlüssel verschiedener Provider-Familien werden niemals vermischt.

---

Migration älterer Konfigurationsdateien

Ältere Konfigurationsdateien, die noch die flachen Schlüssel api.baseUrl, api.model, api.timeoutSeconds und api.key verwenden, werden beim ersten Start automatisch in das aktuelle Schema überführt.

Was passiert

1. Die Anwendung erkennt die veraltete Form anhand der flachen api.*-Schlüssel.
2. Vor jeder Änderung wird eine Sicherungskopie der Originaldatei angelegt:
   • Standardfall: config/application.properties.bak
   • Falls .bak bereits existiert: config/application.properties.bak.1, .bak.2, …
   • Bestehende Sicherungen werden niemals überschrieben.
3. Die Datei wird in-place in das neue Schema überführt:
   • api.baseUrl → ai.provider.openai-compatible.baseUrl
   • api.model → ai.provider.openai-compatible.model
   • api.timeoutSeconds → ai.provider.openai-compatible.timeoutSeconds
   • api.key → ai.provider.openai-compatible.apiKey
   • ai.provider.active=openai-compatible wird ergänzt.
   • Alle übrigen Schlüssel bleiben unverändert.
4. Die migrierte Datei wird über eine temporäre Datei (*.tmp) und atomischen Move/Rename geschrieben. Das Original wird niemals teilbeschrieben.
5. Die migrierte Datei wird sofort neu eingelesen und validiert.

Bei Migrationsfehler

Schlägt die Validierung der migrierten Datei fehl, bricht die Anwendung mit Exit-Code 1 ab. Die Sicherungskopie (.bak) bleibt in diesem Fall erhalten und enthält die unveränderte Originaldatei. Die Konfiguration muss dann manuell korrigiert werden.

Betreiber-Hinweis

Die Umgebungsvariable PDF_UMBENENNER_API_KEY des Vorgängerstands wird nicht automatisch umbenannt. Falls dieser Wert bislang verwendet wurde, muss er auf OPENAI_COMPATIBLE_API_KEY umgestellt werden.

---

Prompt-Konfiguration

Der Prompt wird aus der in prompt.template.file konfigurierten externen Textdatei geladen. Der Dateiname der Prompt-Datei dient als Prompt-Identifikator in der Versuchshistorie (SQLite) und ermöglicht so die Nachvollziehbarkeit, welche Prompt-Version für welchen Verarbeitungsversuch verwendet wurde.

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.

Die Anwendung ergänzt den Prompt automatisch um:

• einen Dokumenttext-Abschnitt
• eine explizite JSON-Antwortspezifikation mit den Feldern title, reasoning und date

---

Zielformat

Jede erfolgreich verarbeitete PDF-Datei wird im Zielordner unter folgendem Namen abgelegt:

YYYY-MM-DD - Titel.pdf

Bei Namenskollisionen wird ein laufendes Suffix angehängt:

YYYY-MM-DD - Titel(1).pdf
YYYY-MM-DD - Titel(2).pdf

Das Suffix zählt nicht zu den 20 Zeichen des Basistitels.

---

Retry- und Skip-Verhalten

Dokumentstatus

Die folgende Tabelle beschreibt die persistenten Statuszustände der Dokument-Stammsätze in der SQLite-Datenbank. Diese Zustände sind nach Abschluss eines Verarbeitungsversuchs dauerhaft gespeichert.

Status	Bedeutung
READY_FOR_AI	Verarbeitbar, KI-Pfad noch nicht durchlaufen
PROPOSAL_READY	KI-Benennungsvorschlag liegt vor, Zielkopie noch nicht geschrieben
SUCCESS	Erfolgreich verarbeitet und kopiert (terminaler Endzustand)
FAILED_RETRYABLE	Fehlgeschlagen, erneuter Versuch in späterem Lauf möglich
FAILED_FINAL	Terminal fehlgeschlagen, wird nicht erneut verarbeitet
SKIPPED_ALREADY_PROCESSED	Übersprungen – Dokument bereits erfolgreich verarbeitet
SKIPPED_FINAL_FAILURE	Übersprungen – Dokument terminal fehlgeschlagen

Zusätzlich kennt das System den transienten Zustand PROCESSING, der während der aktiven Verarbeitung eines Dokuments im Stammsatz gesetzt werden kann. Er wird nach Abschluss des Verarbeitungsversuchs stets durch einen der obigen Zustände ersetzt und ist kein gültiger Endstatus in der Datenbank.

Retry-Regeln

Deterministische Inhaltsfehler (z. B. kein extrahierbarer Text, Seitenlimit überschritten, unbrauchbarer KI-Titel):

• Erster Fehler → FAILED_RETRYABLE (ein Wiederholversuch in späterem Lauf erlaubt)
• Zweiter Fehler → FAILED_FINAL (kein weiterer Versuch)

Transiente technische Fehler (z. B. KI nicht erreichbar, HTTP-Timeout):

• Wiederholbar bis zum Grenzwert max.retries.transient
• Bei Erreichen des Grenzwerts → FAILED_FINAL

Technischer Sofort-Wiederholversuch:

Bei einem Schreibfehler der Zielkopie wird innerhalb desselben Laufs exakt ein Sofort-Wiederholversuch unternommen. Dieser zählt nicht zum laufübergreifenden Fehlerzähler.

---

Logging

Logs werden in das konfigurierte log.directory geschrieben (Standard: ./logs/). Log-Rotation erfolgt täglich und bei Erreichen von 10 MB je Datei.

Sensible KI-Inhalte

Standardmäßig werden die vollständige KI-Rohantwort und das KI-Reasoning nicht ins Log geschrieben, sondern ausschließlich in der SQLite-Datenbank gespeichert.

Die Ausgabe kann für Diagnosezwecke mit log.ai.sensitive=true freigeschaltet werden. Erlaubte Werte: true oder false. Jeder andere Wert ist ungültig und verhindert den Start.

---

Exit-Codes

Code	Bedeutung
0	Lauf technisch ordnungsgemäß ausgeführt (auch bei dokumentbezogenen Teilfehlern)
1	Harter Start- oder Bootstrap-Fehler (ungültige Konfiguration, Lock nicht erwerbbar, Schema-Initialisierungsfehler)

Dokumentbezogene Fehler einzelner PDF-Dateien führen nicht zu Exit-Code 1.

---

Startschutz (Parallelinstanzschutz)

Die Anwendung verwendet eine exklusive Lock-Datei, um parallele Instanzen zu verhindern. Wenn bereits eine Instanz läuft, beendet sich die neue Instanz sofort mit Exit-Code 1.

Der Pfad der Lock-Datei ist über runtime.lock.file konfigurierbar. Ohne Konfiguration wird pdf-umbenenner.lock im Arbeitsverzeichnis verwendet.

---

SQLite-Datenbank

Die SQLite-Datei enthält:

• Dokument-Stammsätze: Gesamtstatus, Fehlerzähler, letzter Zieldateiname, Zeitstempel
• Versuchshistorie: Jeder Verarbeitungsversuch mit Modell, Prompt-Identifikator, KI-Rohantwort, Reasoning, Datum, Titel und Fehlerstatus

Die Datenbank ist die führende Wahrheitsquelle für Bearbeitungsstatus und Nachvollziehbarkeit. Sie muss nicht manuell verwaltet werden – das Schema wird beim Start automatisch initialisiert.

---

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):

.\mvnw.cmd clean verify

Auf Unix-Systemen (headless CI):

./mvnw clean verify

Nur das ausführbare JAR erzeugen (überspringt Tests):

.\mvnw.cmd clean package -pl pdf-umbenenner-bootstrap --also-make -DskipTests

Selektiver Reactor-Build (ohne Coverage-Modul, z. B. während der Entwicklung):

.\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 beschrieben.

---

Systemgrenzen

• Nur OCR-verarbeitete, durchsuchbare PDF-Dateien werden verarbeitet
• Keine eingebaute OCR-Funktion
• 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