marcus
c2a7921675
Neue Typen (port/in): - SchedulerControlUseCase – Inbound-Port: start(), stop(), getStatus() - SchedulerState – Enum: STOPPED, STARTING, RUNNING_IDLE, RUNNING_BATCH_ACTIVE, STOPPING_BATCH_ACTIVE - SchedulerStatus – Immutable Record mit AtomicReference-ready Snapshot - SchedulerStartException – Unchecked Exception für Start-Fehler Neue Typen (port/out): - RunLockHandle – AutoCloseable für tryAcquire() in try-with-resources - RunSummary – Aggregierte Lauf-Ergebniszähler (success/failed/skipped) - BatchRunTrigger – @FunctionalInterface für synchronen Lauf-Trigger - BatchRunTriggerResult – Sealed Interface: Started, SkippedBusy, Failed - SchedulerConfig – Betriebskonfiguration (intervalSeconds >= 30) - SchedulerSettings – Persistierte Properties-Werte mit Defaults - SchedulerPort – startScheduler() / stopScheduler() - ConfigurationFileLockPort – acquireLock() / releaseLock() / isLocked() - ConfigurationFileLockException – Unchecked bei Lock-Erwerb-Fehler - SchedulerSettingsPort – loadSettings() / saveEnabled() / saveIntervalSeconds() - SchedulerSettingsWriteException – Unchecked bei Schreib-Fehler Erweiterungen: - RunLockPort: neue Methode tryAcquire() → Optional<RunLockHandle> - FilesystemRunLockPortAdapter: implementiert tryAcquire() atomar via CREATE_NEW; idempotentes Handle via AtomicBoolean Test-Fixes: - 9 Mock-Klassen in application- und bootstrap-Tests um tryAcquire() ergänzt (liefern Optional.empty(), da nur blockierender Pfad getestet) Co-Authored-By: Claude Sonnet 4.6 <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.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
--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 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.