pdf-umbenenner/CLAUDE.md

CLAUDE.md

Zweck

Dieses Repository implementiert einen lokal gestarteten PDF-Umbenenner mit KI. Das Programm liest bereits OCR-verarbeitete, durchsuchbare PDF-Dateien aus einem Quellordner, ermittelt daraus einen normierten Dateinamen und legt eine Kopie der Datei im Zielordner ab. Die Quelldatei bleibt unverändert.

Ab V2.0 wird die Anwendung um eine lokale JavaFX-Desktop-GUI erweitert. Die GUI ist der neue Standardstart. Der bestehende headless Batch-Betrieb bleibt über --headless vollständig erhalten.

Autoritative Dokumente

@docs/specs/technik-und-architektur.md @docs/specs/fachliche-anforderungen.md @docs/specs/meilensteine-v2_0.md

Für die Umsetzung ist zusätzlich immer das aktuell aktive Arbeitspaket unter docs/workpackages/ maßgeblich. Dateinamensschema: M9 - Arbeitspakete.md, M10 - Arbeitspakete.md, … M13 - Arbeitspakete.md Nicht raten, wenn Dokumente fehlen, unklar sind oder sich widersprechen.

Priorisierung der Regeln

Die Dokumente haben folgende feste Bedeutung:

• docs/specs/technik-und-architektur.md = verbindliche technische Zielarchitektur
• docs/specs/fachliche-anforderungen.md = verbindliche fachliche Regeln
• docs/specs/meilensteine-v2_0.md = verbindliche V2.0-Zieldefinition und Meilensteinabgrenzung
• docs/workpackages/... = verbindlicher Scope, Reihenfolge und Inhalt des aktuell bearbeiteten Arbeitspakets

Bei Konflikten gilt folgende Priorität:

1. Technik- und Architektur-Dokument Verbindliche technische Zielarchitektur. Architekturbrüche sind unzulässig.

2. Fachliche Anforderungen Verbindliche fachliche Regeln und fachliches Zielverhalten.

3. Meilensteine V2.0 Verbindliche Zieldefinition, Abgrenzungen und Leitplanken für den V2.0-Ausbau.

4. Arbeitspakete Definieren den konkret erlaubten Umsetzungsumfang des aktuellen Schritts.

Wenn Dokumente fehlen, unklar sind oder sich widersprechen, nicht raten und keine stillen Annahmen treffen.

Unverrückbare Technikvorgaben

• Java 21
• Maven Multi-Module
• ausführbares Standalone-JAR (ein gemeinsames JAR für GUI und headless)
• GUI ist der neue Standardstart (ab V2.0)
• --headless startet weiterhin den bestehenden Batch-/Scheduler-Betrieb
• --config <pfad> steht für GUI und headless zur Verfügung
• kein Webserver
• kein Applikationsserver
• keine Dauerlauf-Anwendung
• kein interner Scheduler
• keine EXE, kein Installer
• Log4j2 für Logging
• SQLite als lokaler Persistenzspeicher
• JavaFX wird mit dem JAR ausgeliefert (kein separates JavaFX-Setup)
• GUI offiziell nur für Windows; headless bleibt für Windows Server / Task Scheduler geeignet
• gemappte Laufwerke wie S:\ oder H:\ sind ausdrücklich zu unterstützen
• KI-Anbindung über genau eine der beiden unterstützten Provider-Familien:
  • OpenAI-kompatible HTTP-Schnittstelle (Chat-Completions-Stil)
  • native Anthropic Messages API (Claude-Modelle)
• Pro Lauf ist genau ein Provider aktiv. Kein Fallback, keine Parallelnutzung.
• .properties bleibt die einzige Konfigurationswahrheit
• Konkrete Provider-Familie, Base-URL und Modellname sind Konfiguration, keine Architekturentscheidung.

Verbindliche Modulstruktur (ab V2.0)

• pdf-umbenenner-domain
• pdf-umbenenner-application
• pdf-umbenenner-adapter-in-cli
• pdf-umbenenner-adapter-in-gui
• pdf-umbenenner-adapter-out
• pdf-umbenenner-bootstrap

Architekturregeln

• Strikte hexagonale Architektur / Ports and Adapters
• Abhängigkeiten zeigen immer nach innen
• Domain kennt keine Infrastruktur, keine Datenbank, kein Dateisystem, keine HTTP-Kommunikation und kein JavaFX
• Application enthält keine technischen Implementierungsdetails und keine JavaFX-Typen
• Externe Zugriffe erfolgen ausschließlich über Ports
• Konkrete technische Implementierungen sind Adapter
• Adapter dürfen nicht direkt voneinander abhängen
• Die GUI ist ein Inbound-Adapter (pdf-umbenenner-adapter-in-gui) – sie wird nicht in Bootstrap vermischt
• Bootstrap bleibt verantwortlich für: Startmoduswahl, Konfigurationsauflösung, Objektgraph, kontrollierten Start des passenden Adapters, Exit-Code-Ableitung bei harten Startfehlern
• GUI-Code und JavaFX dürfen im headless Pfad nicht unnötig früh initialisiert oder geladen werden
• Keine Vermischung von Dateisystem, PDF-Auslese, SQLite, KI-HTTP, Konfiguration, Logging, Benennungslogik und Retry-Entscheidungen
• Logging ist technische Infrastruktur, kein fachlicher Port
• Port-Verträge enthalten weder Path/File noch NIO- oder JDBC-Typen
• Der AiNamingPort bleibt provider-neutral; provider-spezifische Typen, Header, URLs und Antwortstrukturen leben ausschließlich in der jeweiligen Adapter-Out-Implementierung
• Es gibt keine gemeinsame „abstrakte KI-Adapter"-Zwischenschicht zwischen Port und konkreten Adaptern
• Die Bootstrap-Schicht wählt die eine aktive AiNamingPort-Implementierung anhand der Konfiguration aus

GUI-Leitplanken (verbindlich für alle V2.0-Arbeitspakete)

Threadingmodell

• Jede potenziell blockierende Operation (Modellabruf, technische Tests, Pfad-/Dateisystemprüfungen, SQLite-Prüfungen, Lesen/Schreiben der .properties) läuft auf einem Hintergrund-Worker-Thread
• UI-Updates erfolgen ausschließlich über den JavaFX Application Thread (Platform.runLater)
• Die GUI darf während laufender Hintergrund-Operationen nicht einfrieren

GUI-Teststrategie

• View-Modelle und Application-nahe GUI-Logik werden mit JUnit unit-getestet; Fokus auf Zustandsübergängen, Validierungsregeln und Datenflüssen – nicht auf Rendering
• GUI-Smoke-Tests laufen unter headless JavaFX (Monocle) in der Maven-Test-Phase
• Kein TestFX, kein weiteres GUI-Testframework über Monocle hinaus

GUI-Logging

• Der GUI-Adapter nutzt denselben Log4j2-Stack wie der headless Pfad
• Logformat und Log-Verzeichnis bleiben gegenüber dem headless Betrieb unverändert
• Mindesteinträge für GUI-nahe Ereignisse: Start- und Beendigungsereignisse der GUI, Modellabruf-Versuche (Provider, Erfolg/Misserfolg, ohne API-Key), Dateischreibvorgänge inkl. Zielpfad, Ergebnisse der Aktionen Validieren und Technische Tests ausführen, sowie alle schreibenden Korrekturen

--config-Semantik

• Zeigt --config <pfad> im GUI-Start auf eine nicht existente Datei: Fehlermeldung, danach verhält sich die GUI so, als wäre --config nicht angegeben worden
• Zeigt --config <pfad> im headless Start auf eine nicht existente Datei: harter Startfehler, kein stiller Fallback

JavaDoc-Standard (verbindlich für alle V2.0-Arbeitspakete)

Für jede neu hinzugefügte oder substanziell geänderte öffentliche Klasse, öffentliche Methode und jedes neue Java-Package gilt:

• Klassen-JavaDoc: Zweck, Verantwortung und Abgrenzung der Klasse
• Methoden-JavaDoc: Zweck, Parameter, Rückgabewert und dokumentierte Ausnahmen
• package-info.java: pro neuem Package, mit Kurzbeschreibung der Paketverantwortung

Ein Arbeitspaket ist erst fertig, wenn die betroffenen öffentlichen Klassen und Methoden dem JavaDoc-Standard entsprechen.

Globale fachliche Leitplanken

• Zielformat: YYYY-MM-DD - Titel.pdf
• Bei Namenskollisionen: YYYY-MM-DD - Titel(1).pdf, YYYY-MM-DD - Titel(2).pdf, ...
• Die 20 Zeichen gelten nur für den Basistitel; das Dubletten-Suffix zählt nicht mit
• Das Dubletten-Suffix wird unmittelbar vor .pdf angehängt
• Titel sind deutsch, verständlich, eindeutig und enthalten keine Sonderzeichen außer Leerzeichen
• Eigennamen bleiben unverändert
• Datumsermittlung mit Priorität aus den fachlichen Anforderungen; wenn kein belastbares Datum eindeutig ableitbar ist, ist das aktuelle Datum als Fallback erlaubt
• Mehrdeutige Dokumente liefern kein unsicheres Ergebnis, sondern einen Fehler
• Erfolgreich verarbeitete Dateien werden nicht erneut verarbeitet
• Retryable fehlgeschlagene Dateien dürfen in späteren Läufen erneut verarbeitet werden
• Final fehlgeschlagene Dateien werden in späteren Läufen übersprungen
• Identifikation erfolgt nicht über Dateinamen
• Quelldateien werden nie überschrieben, verändert, verschoben oder gelöscht

Aktiver Implementierungsstand

V1.1 ist vollständig umgesetzt, dokumentiert, getestet und freigegeben.

Der aktive Entwicklungsstand ist V2.0. Ziel ist der Ausbau um eine lokale JavaFX-Desktop-GUI als neuen Standardstart, ohne die bestehende Architektur, das Standalone-JAR-Betriebsmodell oder den headless Scheduler-Betrieb aufzugeben.

Die fachliche Kernverarbeitung des PDF-Umbenenners bleibt in V2.0 unverändert.

Statussemantik

Status	Bedeutung
READY_FOR_AI	Verarbeitbar, KI-Pfad noch nicht durchlaufen
FAILED_RETRYABLE	Verarbeitbar, transient fehlgeschlagen
PROPOSAL_READY	Eingangszustand für Dateinamensbildung und Zielkopie
SUCCESS	Terminaler Enderfolg – nur nach Zielkopie und konsistenter Persistenz zulässig
FAILED_FINAL	Terminal, wird nicht erneut fachlich verarbeitet
SKIPPED_ALREADY_PROCESSED	Historisierter Skip für SUCCESS-Dokumente
SKIPPED_FINAL_FAILURE	Historisierter Skip für FAILED_FINAL-Dokumente

SUCCESS-Bedingung (verbindlich)

SUCCESS darf erst gesetzt werden, wenn:

1. die Zielkopie erfolgreich geschrieben wurde,
2. der finale Zieldateiname bestimmt ist,
3. die Persistenz konsistent fortgeschrieben wurde.

Führende Quelle des Benennungsvorschlags (verbindlich)

• Die führende Quelle für Datum, Datumsquelle, validierten Titel und Reasoning ist der neueste Versuchshistorieneintrag mit Status PROPOSAL_READY
• Kein Rekonstruieren aus dem Dokument-Stammsatz
• Kein neuer KI-Aufruf, wenn bereits ein nutzbarer PROPOSAL_READY-Versuch vorliegt
• Status PROPOSAL_READY ohne lesbaren konsistenten Proposal-Versuch = dokumentbezogener technischer Fehler
• Inkonsistente Proposal-Zustände werden nicht stillschweigend geheilt, sondern als technische Dokumentfehler behandelt

Retry-Semantik

Deterministische Inhaltsfehler

• erster historisierter deterministischer Inhaltsfehler → FAILED_RETRYABLE
• zweiter historisierter deterministischer Inhaltsfehler → FAILED_FINAL

Transiente technische Fehler

• Transiente Fehler laufen über den Transientfehlerzähler im Dokument-Stammsatz
• Retryable bis der konfigurierte Grenzwert max.retries.transient erreicht ist
• Der Fehlversuch, der den Grenzwert erreicht, finalisiert den Dokumentstatus zu FAILED_FINAL
• max.retries.transient = Integer >= 1; der Wert 0 ist ungültige Startkonfiguration

Technischer Sofort-Wiederholversuch

• Genau ein zusätzlicher technischer Schreibversuch innerhalb desselben Dokumentlaufs
• Ausschließlich für Fehler beim physischen Zielkopierpfad
• Kein erneuter KI-Aufruf, keine erneute Fachableitung
• Zählt nicht zum laufübergreifenden Transientfehlerzähler

Exit-Codes (verbindlich)

• 0: normale erfolgreiche Beendigung eines headless Laufs sowie für das reguläre Beenden der GUI
• 1: harte Start-, Bootstrap-, Verdrahtungs-, Konfigurations- oder Initialisierungsfehler, einschließlich ungültiger CLI-Verwendung, nicht existenter --config-Datei im headless Start und GUI-Startfehlern vor erfolgreicher Anzeige der Oberfläche
• Dokumentbezogene Verarbeitungsfehler im headless Lauf ändern dieses Exit-Code-Modell nicht

Persistenz

Zwei-Ebenen-Modell – keine dritte Wahrheitsquelle.

Dokument-Stammsatz enthält u.a.:

• letzten Zielpfad, letzten Zieldateinamen
• Inhaltsfehler- und Transientfehlerzähler
• Gesamtstatus

Versuchshistorie enthält u.a.:

• finalen Zieldateinamen
• Fehlerklasse, Fehlermeldung, Retryable-Flag
• Provider-Identifikator des aktiven KI-Providers für den Versuch

Invariante: Der führende PROPOSAL_READY-Versuch wird nicht überschrieben. Jeder Lauf erzeugt einen zusätzlichen neuen Versuchseintrag.

Rückwärtsverträglichkeit: Bestehende Datenbestände bleiben lesbar, fortschreibbar und korrekt interpretierbar.

Naming-Regel (verbindlich für alle Arbeitspakete)

In Implementierungen, Kommentaren und JavaDoc dürfen keine Meilenstein- oder Arbeitspaket-Bezeichner erscheinen:

• Verboten: M1, M2, …, M13
• Verboten: AP-001, AP-002, … AP-0xx
• Verboten: Versionsbezeichner wie V1.0, V1.1, V2.0 in Code/JavaDoc

Stattdessen werden zeitlose technische Bezeichnungen verwendet. Bestehende Kommentare mit solchen Bezeichnern, die durch eigene Änderungen berührt werden, sind zu ersetzen.

Arbeitsweise

• Arbeite immer nur im explizit aktiven Arbeitspaket
• Kein Vorgriff auf spätere Arbeitspakete
• Änderungen klein, fokussiert und architekturtreu halten
• Keine unnötigen Umbenennungen, keine großflächigen Refactorings ohne Not
• Vor Änderungen zuerst die betroffenen Dateien und Abhängigkeiten verstehen
• Keine Annahmen über Dateipfade. Typen und Klassen werden per Suche nach Typname gefunden, nicht über vermutete Pfade.
• Keine Vermutungen: Bei echter Unklarheit oder Dokumentkonflikten knapp nachfragen oder den Konflikt benennen
• Keine stillen Änderungen am bestehenden headless Batch-Betrieb
• GUI-Code darf den headless Pfad nicht unnötig früh initialisieren

Definition of Done pro Arbeitspaket

Ein Arbeitspaket ist erst fertig, wenn:

• der Zielumfang des aktuellen Arbeitspakets vollständig umgesetzt ist
• der Stand konsistent, fehlerfrei und buildbar ist
• Implementierung, Konfiguration, JavaDoc (inkl. package-info.java für neue Packages) und Tests ergänzt sind
• der JavaDoc-Standard für alle neu hinzugefügten oder substanziell geänderten öffentlichen Klassen und Methoden eingehalten wurde
• keine Inhalte späterer Arbeitspakete vorweggenommen wurden
• der Zwischenstand in sich geschlossen und übergabefähig ist

Pflicht-Output-Format nach jedem Arbeitspaket

- Scope erfüllt: ja/nein
- Geänderte Dateien:
  - <Dateipfad>
  - ...
- Build-Kommando: <verwendetes Kommando>
- Build-Status: ERFOLGREICH / FEHLGESCHLAGEN
- Offene Punkte: keine / <Beschreibung>
- Risiken: keine / <Beschreibung>

Qualitäts- und Prüfreihenfolge

• Nur den für das aktuelle Arbeitspaket nötigen Scope ändern
• Nach Änderungen den kleinsten sinnvollen Build-/Test-Umfang ausführen
• Build-Validierung vom Parent-Root (Beispiel für vollständigen Reactor-Build ab V2.0): .\mvnw.cmd clean verify -pl pdf-umbenenner-domain,pdf-umbenenner-application,pdf-umbenenner-adapter-out,pdf-umbenenner-adapter-in-cli,pdf-umbenenner-adapter-in-gui,pdf-umbenenner-bootstrap --also-make
• Schlägt der Build fehl: Fehler beheben, erneut bauen, erst dann weiter
• Vor Abschluss sicherstellen, dass der relevante Maven-Reactor-Stand fehlerfrei ist
• Fehler nicht kaschieren; Ursachen sauber beheben oder offen benennen

Wichtige Betriebsregeln

• Ungültige Startkonfiguration verhindert den Verarbeitungslauf und führt zu Exit-Code 1
• Eine ungültige oder fehlende Provider-Auswahl ist eine ungültige Startkonfiguration
• Run-Lock verhindert parallele Instanzen; wenn bereits eine Instanz läuft, beendet sich die neue Instanz sofort
• API-Schlüssel: pro Provider eine eigene Umgebungsvariable, Vorrang vor Properties derselben Provider-Familie. Schlüssel verschiedener Provider werden niemals vermischt.
• Dokumentbezogene Fehler führen nicht zu Exit-Code 1

Konfigurationsparameter

Verbindlich zweckmäßige Parameter:

• source.folder – Quellordner
• target.folder – Zielordner (muss vorhanden oder anlegbar sein, Schreibzugriff erforderlich)
• sqlite.file – SQLite-Datenbankdatei
• ai.provider.active – aktiver KI-Provider (Pflicht)
• max.retries.transient – max. historisierte transiente Fehlversuche pro Fingerprint (Integer >= 1, 0 ist ungültig)
• max.pages – Seitenlimit
• max.text.characters – maximale Zeichenzahl für KI-Eingabe
• prompt.template.file – externe Prompt-Datei
• log.ai.sensitive – sensible KI-Logausgabe freischalten (Boolean, Default: false)
• runtime.lock.file – Lock-Datei (optional)
• log.directory – Log-Verzeichnis (optional)

Pro Provider-Familie existiert ein eigener Parameter-Namensraum:

ai.provider.active=openai-compatible

ai.provider.openai-compatible.baseUrl=...
ai.provider.openai-compatible.model=...
ai.provider.openai-compatible.timeoutSeconds=...
ai.provider.openai-compatible.apiKey=...

ai.provider.claude.baseUrl=...
ai.provider.claude.model=...
ai.provider.claude.timeoutSeconds=...
ai.provider.claude.apiKey=...

Migration historischer Konfiguration

Bestehende Properties-Dateien des Vorgängerstands (flache Schlüssel wie api.baseUrl, api.model, api.timeoutSeconds, api.key) werden beim ersten Start erkannt und kontrolliert in das neue Schema überführt.

Verbindlicher Ablauf:

1. Legacy-Form erkennen
2. .bak-Sicherung der Originaldatei anlegen
3. Inhalt in das neue Schema überführen (Legacy-Werte → Namensraum openai-compatible, ai.provider.active=openai-compatible)
4. Datei in-place schreiben
5. Datei erneut laden und validieren
6. Erst danach den normalen Lauf fortsetzen

Nicht-Ziele / Verbote

• kein manueller Verarbeitungslauf aus der GUI (erst V2.1+)
• kein DB-/Historien-Tab in der GUI (erst V2.x+)
• kein Kosten-Tracking (erst V2.x+)
• kein echter Mini-KI-Testaufruf mit fachlicher Antwortauswertung
• keine EXE, kein Installer
• kein Web-UI
• keine REST-API zur Bedienung
• keine OCR innerhalb der Java-Anwendung
• keine DMS-Funktionalität
• kein menschlicher Review-Workflow in der Anwendung
• keine interne Scheduler-Logik
• keine Architekturbrüche
• keine neuen Bibliotheken oder Frameworks ohne klare Notwendigkeit und Begründung
• keine automatische Fallback-Umschaltung zwischen KI-Providern
• keine parallele Nutzung mehrerer KI-Provider in einem Lauf
• keine Profilverwaltung mit mehreren Konfigurationen je Provider-Familie
• keine Provider-Familien jenseits der explizit unterstützten
• kein neues Konfigurationsformat
• keine Änderung der fachlichen Kernverarbeitung des PDF-Umbenenners
• keine Änderung der bestehenden Status-, Retry- oder Persistenz-Wahrheit
• keine stillen Änderungen am bestehenden headless Batch-Betrieb
• kein Sofort-Wiederholversuch außerhalb des Zielkopierpfads
• keine spekulativen Umbauten ohne konkreten Qualitäts- oder Konsistenzbezug
• kein großflächiges Refactoring ohne nachweisbaren Defektbezug