marcus
55088354ab
- [TEMP-TRACE] INFO-Logs in SqliteDocumentRecordRepositoryAdapter: deleteByFingerprint() zeigt Fingerprint, jdbcUrl und rowsAffected; findByFingerprint() zeigt Fingerprint, jdbcUrl und Lookup-Ergebnis - [TEMP-TRACE] Log in DocumentProcessingCoordinator.processDeferredOutcome() zeigt Fingerprint und Lookup-Ergebnis-Typ nach DB-Abfrage - Bestehende [TEMP-TRACE] Logs in GuiBatchRunCoordinator und SqliteUnitOfWorkAdapter sind ebenfalls enthalten - Neuer Test resetDocumentByFingerprint_deletesFailedFinalRecord_resultIsDocumentUnknown: legt FAILED_FINAL-Datensatz in echter SQLite-DB an, führt Reset aus und prüft, dass der Datensatz danach DocumentUnknown zurückliefert Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
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
--headlessvollstä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:
- 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 konfigurierte maximale Titellänge bezieht sich nur auf den Basistitel
- das Dubletten-Suffix zählt nicht zur konfigurierten Titellänge
- 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-domainpdf-umbenenner-applicationpdf-umbenenner-adapter-in-clipdf-umbenenner-adapter-in-guipdf-umbenenner-adapter-outpdf-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
- maximale Titellänge (
max.title.length, Default 60, Bereich 10..120) - 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.mddocs/specs/technik-und-architektur.mddocs/specs/fachliche-anforderungen.mddocs/specs/meilensteine-v2_0.mddocs/betrieb.mddocs/gui-bedienanleitung.mddocs/freigabe-v2_0.mddocs/workpackages/...
Empfohlene Leserichtung:
CLAUDE.md- technische Zielarchitektur
- fachliche Anforderungen
- Meilensteine
docs/betrieb.mdfür Betriebs- und Startdetailsdocs/gui-bedienanleitung.mdfür die GUI-Bedienung- 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.