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.

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:

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

1. CLAUDE.md
2. technische Zielarchitektur
3. fachliche Anforderungen
4. Meilensteine
5. 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.