# 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.9:** Die Anwendung enthält eine lokale JavaFX-Desktop-GUI als Standardstart. > Die GUI dient der Konfiguration, Validierung, technischen Diagnose und der Ausführung von Verarbeitungsläufen. > Der Tab „Verarbeitungslauf" enthält eine integrierte PDF-Vorschau und einen editierbaren Dateiname-Bereich. > Die GUI startet maximiert und lädt beim Start automatisch die zuletzt verwendete Konfigurationsdatei. > Der headless Batch-Betrieb bleibt über `--headless` vollständig erhalten. > Details zum Betrieb: [`docs/betrieb.md`](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 `** 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: ```text YYYY-MM-DD - Titel.pdf ``` Bei Namenskollisionen werden Suffixe direkt vor `.pdf` ergänzt: ```text 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-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 - maximale Titellänge (`max.title.length`, Default 60, Bereich 10..120) - Prompt-Datei - Logging Für einen lokalen Einstieg dient die Beispielkonfiguration unter: ```text config/application-local.example.properties ``` ## Build Projektweit: ```bash ./mvnw clean verify ``` Unter Windows: ```powershell .\mvnw.cmd clean verify ``` ## Start Das ausführbare Artefakt wird im Bootstrap-Modul erzeugt. **GUI-Standardstart** (öffnet die JavaFX-Desktop-Oberfläche): ```bash java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar ``` **headless Betrieb** (Batch-/Scheduler-Start ohne GUI): ```bash java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar --headless ``` **Explizite Konfigurationsdatei** (für GUI und headless): ```bash 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`](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 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) - Tab „Verarbeitungslauf" mit integrierter PDF-Vorschau pro Zeile und editierbarem Dateiname-Bereich - Atomare Dateisystem- und Datenbankoperationen für manuelle Umbenennungen mit Konfliktauflösung - 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.