pdf-umbenenner/README.md

PDF-Umbenenner

Ein lokal gestartetes Java-Programm zur KI-gestützten Umbenennung bereits OCR-verarbeiteter, durchsuchbarer PDF-Dateien.

Die Anwendung liest PDF-Dateien aus einem konfigurierbaren Quellordner, extrahiert den Text, ermittelt daraus per KI einen normierten Dateinamen und legt eine Kopie im Zielordner ab. Die Quelldateien bleiben unverändert.

V2.0: Die Anwendung enthält ab V2.0 eine lokale JavaFX-Desktop-GUI als Standardstart. Die GUI dient der Konfiguration, Validierung und technischen Diagnose. Der headless Batch-Betrieb bleibt über --headless vollständig erhalten. Details zum Betrieb: docs/betrieb.md

Zielbild

Der PDF-Umbenenner ist als schlanke, lokal gestartete Anwendung ausgelegt:

• Java 21
• Maven Multi-Module
• ausführbares Standalone-JAR (ein gemeinsames JAR für GUI und headless)
• GUI-Standardstart ab V2.0 (JavaFX-Desktop, offiziell Windows)
• headless Betrieb über --headless, z. B. für den Windows Task Scheduler
• --config <pfad> für GUI und headless
• kein Webserver
• kein Applikationsserver
• keine Dauerlauf-Anwendung
• kein interner Scheduler
• SQLite als lokaler Persistenzspeicher
• Log4j2 für Logging
• strikte hexagonale Architektur / Ports and Adapters

Fachlicher Überblick

Die Anwendung verarbeitet Dokumente in einem robusten, nachvollziehbaren Ablauf:

1. Quellordner lesen
2. PDF-Kandidaten erkennen
3. Fingerprint der Quelldatei bestimmen
4. bereits erfolgreich verarbeitete bzw. final fehlgeschlagene Dokumente überspringen
5. PDF-Text extrahieren
6. KI-basierten Benennungsvorschlag erzeugen
7. normierten Zieldateinamen bilden
8. Kollisionen im Zielordner über Dubletten-Suffixe auflösen
9. Kopie im Zielordner ablegen
10. Ergebnis und Versuchshistorie in SQLite persistieren

Dateinamensregeln

Das Zielformat lautet:

YYYY-MM-DD - Titel.pdf

Bei Namenskollisionen werden Suffixe direkt vor .pdf ergänzt:

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

Wichtige Regeln:

• die 20 Zeichen beziehen sich nur auf den Basistitel
• das Dubletten-Suffix zählt nicht zu diesen 20 Zeichen
• Titel werden auf Deutsch erzeugt
• Eigennamen bleiben unverändert
• Quelldateien werden nie überschrieben, verschoben oder verändert

KI-Anbindung

Die KI-Anbindung ist konfigurationsgetrieben. Der fachliche Vertrag bleibt unabhängig vom Anbieter gleich: Aus dem Dokumentinhalt wird ein strukturierter Benennungsvorschlag abgeleitet, aus dem die Anwendung den finalen Dateinamen bildet.

Der aktuelle Stand unterstützt mehrere Provider über Konfiguration, darunter:

• OpenAI-kompatible Endpunkte
• Claude API

Die Provider-Auswahl ist Konfiguration, keine Architekturentscheidung.

Wichtige Annahmen und Grenzen

• Die Anwendung erwartet bereits OCR-verarbeitete, durchsuchbare PDFs.
• Nicht durchsuchbare oder inhaltlich nicht brauchbare PDFs werden als Fehler behandelt.
• Mehrdeutige Dokumente erzeugen kein unsicheres Ergebnis.
• Erfolgreich verarbeitete Dateien werden in späteren Läufen nicht erneut verarbeitet.
• Final fehlgeschlagene Dateien werden in späteren Läufen übersprungen.

Architektur

Das Projekt ist strikt nach Ports and Adapters / Hexagonal Architecture aufgebaut.

Module

• pdf-umbenenner-domain
• pdf-umbenenner-application
• pdf-umbenenner-adapter-in-cli
• pdf-umbenenner-adapter-in-gui
• pdf-umbenenner-adapter-out
• pdf-umbenenner-bootstrap

Grundprinzipien

• Abhängigkeiten zeigen immer nach innen
• Domain kennt keine Infrastruktur
• externe Zugriffe erfolgen ausschließlich über Ports
• technische Implementierungen liegen in Adaptern
• keine direkte Adapter-zu-Adapter-Kopplung

Konfiguration

Die Anwendung wird über eine .properties-Datei konfiguriert.

Typische Bereiche sind:

• Quellordner
• Zielordner
• SQLite-Datei
• KI-Provider und Modell
• Timeout
• Seitenlimit
• Textlimit für KI-Aufrufe
• Prompt-Datei
• Logging

Für einen lokalen Einstieg dient die Beispielkonfiguration unter:

config/application-local.example.properties

Build

Projektweit:

./mvnw clean verify

Unter Windows:

.\mvnw.cmd clean verify

Start

Das ausführbare Artefakt wird im Bootstrap-Modul erzeugt.

GUI-Standardstart (öffnet die JavaFX-Desktop-Oberfläche):

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

headless Betrieb (Batch-/Scheduler-Start ohne GUI):

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

Explizite Konfigurationsdatei (für GUI und headless):

java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar --config C:\Pfad\zur\config.properties
java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar --headless --config C:\Pfad\zur\config.properties

Das JAR ist das einzige Distributionsartefakt und enthält JavaFX für den GUI-Start bereits integriert. Ausführliche Build-, Packaging- und Starthinweise sowie Informationen zur JavaFX- Integration und zum headless Betrieb befinden sich in docs/betrieb.md.

Logging, Status und Nachvollziehbarkeit

Der PDF-Umbenenner ist auf Nachvollziehbarkeit und Wiederholbarkeit ausgelegt:

• persistente Dokumenthistorie in SQLite
• Status- und Retry-Semantik für robuste Batch-Läufe
• Idempotenz über inhaltsbasierten Fingerprint
• Logging über Log4j2
• Schutz sensibler KI-Inhalte im Log

Dokumentation im Repository

Die maßgeblichen Dokumente sind:

• CLAUDE.md
• docs/specs/technik-und-architektur.md
• docs/specs/fachliche-anforderungen.md
• docs/specs/meilensteine-v2_0.md
• docs/betrieb.md
• docs/gui-bedienanleitung.md
• docs/freigabe-v2_0.md
• docs/workpackages/...

Empfohlene Leserichtung:

1. CLAUDE.md
2. technische Zielarchitektur
3. fachliche Anforderungen
4. Meilensteine
5. docs/betrieb.md für Betriebs- und Startdetails
6. docs/gui-bedienanleitung.md für die GUI-Bedienung
7. aktives Arbeitspaket

Entwicklungsleitplanken

• kleine, fokussierte Änderungen
• keine stillen Annahmen bei Dokumentkonflikten
• keine unnötigen Refactorings
• Architekturtreue hat Vorrang
• keine Meilenstein- oder Arbeitspaket-Bezeichner in Produktionscode, Kommentaren oder JavaDoc

Status des Projekts

Das Repository verfolgt einen inkrementellen, meilensteinbasierten Ausbau. Der aktuelle Produktstand (V2.0) baut auf einem vollständig implementierten Kern für:

• Konfiguration und Startvalidierung
• Quellordner-Scan und PDF-Textauslese
• Fingerprint, SQLite-Persistenz und Idempotenz
• KI-Integration für Benennungsvorschläge (OpenAI-kompatibel und Anthropic Claude)
• Dateinamensbildung und Zielkopie
• Retry-Logik, Logging und betriebliche Robustheit
• JavaFX-Desktop-GUI als Standardstart (Konfigurationseditor, Validierung, technische Tests)
• headless Batch-Betrieb über --headless (rückwärtskompatibel zu V1.x)

Lizenz / Nutzung

Falls für dieses Repository eine konkrete Lizenz vorgesehen ist, sollte sie hier ergänzt werden.