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.

Zielbild

Der PDF-Umbenenner ist bewusst als schlanke Batch-Anwendung ausgelegt:

Java 21
Maven Multi-Module
ausführbares Standalone-JAR
lokaler Start, z. B. über den Windows Task Scheduler
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:

Quellordner lesen
PDF-Kandidaten erkennen
Fingerprint der Quelldatei bestimmen
bereits erfolgreich verarbeitete bzw. final fehlgeschlagene Dokumente überspringen
PDF-Text extrahieren
KI-basierten Benennungsvorschlag erzeugen
normierten Zieldateinamen bilden
Kollisionen im Zielordner über Dubletten-Suffixe auflösen
Kopie im Zielordner ablegen
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-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. Der Start erfolgt als normales Java-Programm:

java -jar <bootstrap-jar>.jar

Die konkrete JAR-Datei hängt vom aktuellen Build-Stand ab.

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.md
docs/workpackages/...

Empfohlene Leserichtung:

CLAUDE.md
technische Zielarchitektur
fachliche Anforderungen
Meilensteine
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 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
Dateinamensbildung und Zielkopie
Retry-Logik, Logging und betriebliche Robustheit

Lizenz / Nutzung

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