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.

## Autoritative Dokumente
@docs/specs/technik-und-architektur.md
@docs/specs/fachliche-anforderungen.md
@docs/specs/meilensteine.md

Für die Umsetzung ist zusätzlich immer das aktuell aktive Arbeitspaket unter `docs/workpackages/` maßgeblich.
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.md` = zulässiger Funktionsumfang pro Meilenstein
- `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**
   Begrenzen den zulässigen Funktionsumfang auf den aktuellen Entwicklungsstand.

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
- Start über Windows Task Scheduler
- kein Webserver
- kein Applikationsserver
- keine Dauerlauf-Anwendung
- kein interner Scheduler
- Log4j2 für Logging
- SQLite als lokaler Persistenzspeicher
- OpenAI-kompatible HTTP-Schnittstelle für KI-Zugriff
- API-Provider, Base-URL und Modellname sind **Konfiguration**, keine Architekturentscheidung

## Verbindliche Modulstruktur
- `pdf-umbenenner-domain`
- `pdf-umbenenner-application`
- `pdf-umbenenner-adapter-in-cli`
- `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 und keine HTTP-Kommunikation
- Application orchestriert Use Cases und enthält keine technischen Implementierungsdetails
- Externe Zugriffe erfolgen ausschließlich über **Ports**
- Konkrete technische Implementierungen sind **Adapter**
- Adapter dürfen nicht direkt voneinander abhängen
- 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

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

M1 bis M6 sind vollständig abgeschlossen. Der aktive Stand schließt die betriebliche
Lücke zwischen dem M6-Erfolgspfad und dem final robusten Endstand.

### Baseline aus M6
- Technische Dateinamensbildung im Format `YYYY-MM-DD - Titel.pdf`
- Dublettenbehandlung im Zielordner: `(1)`, `(2)`, …
- Physische Zielkopie via temporäre Datei und finalem Move/Rename
- Schemaevolution M5 → M6 (Zielpfad, Zieldateiname in Stammsatz und Versuchshistorie)
- Statustransition `PROPOSAL_READY` → `SUCCESS`
- Zusätzliche Historisierung für Enderfolg und technische Fehler
- Startvalidierung für Zielordner-Konfiguration (`target.folder`)

### Ziel des aktiven Stands
- Vollständige laufübergreifende Retry-Logik für deterministische Inhaltsfehler und transiente technische Fehler
- Technischer Sofort-Wiederholversuch ausschließlich für Zielkopierfehler (genau ein zusätzlicher Versuch im selben Lauf)
- Finalisierung ausgeschöpfter Retry-Rahmen zu `FAILED_FINAL`
- Vollständige Skip-Semantik: `SUCCESS` und `FAILED_FINAL` werden historisiert übersprungen
- Logging-Mindestumfang des Endstands vollständig angebunden
- Sensibilitätsregel für KI-Inhalte im Logging
- Vervollständigte Startvalidierung und finale Exit-Code-Semantik

## 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.
- Proposal-Versuch mit fachlich unbrauchbarem Titel oder Datum = inkonsistenter Persistenzzustand = dokumentbezogener technischer Fehler.
- Inkonsistente Proposal-Zustände werden **nicht stillschweigend geheilt**, sondern als technische Dokumentfehler behandelt.

## Retry-Semantik (aktiver Stand)

### Deterministische Inhaltsfehler
Deterministische Inhaltsfehler sind insbesondere:
- kein brauchbarer Text
- Seitenlimit überschritten
- fachlich unbrauchbarer oder generischer Titel
- vorhandenes, aber unbrauchbares KI-Datum

Regel:
- **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.
- Sie bleiben 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.
- Beispiel: `max.retries.transient = 1` → erster transiente Fehlversuch finalisiert sofort.

### 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.
- Liefert genau ein dokumentbezogenes Ergebnis für Persistenz und Statusfortschreibung.

### Skip-Semantik
- `SUCCESS` → in späteren Läufen `SKIPPED_ALREADY_PROCESSED` historisieren, keine Zähleränderung.
- `FAILED_FINAL` → in späteren Läufen `SKIPPED_FINAL_FAILURE` historisieren, keine Zähleränderung.
- `FAILED_RETRYABLE`, `READY_FOR_AI`, `PROPOSAL_READY` → verarbeitbar.

## Logging-Mindestumfang (aktiver Stand)

Folgende Informationen müssen nachvollziehbar geloggt werden:
- Laufstart mit Lauf-ID
- Laufende
- erkannte Quelldatei
- Überspringen bereits erfolgreicher Dateien
- Überspringen final fehlgeschlagener Dateien
- erzeugter Zielname
- Retry-Entscheidung
- Fehler mit Klassifikation

### Korrelationsregel
- Vor erfolgreicher Fingerprint-Ermittlung: Korrelation über Lauf-ID und Kandidatenbezug.
- Nach erfolgreicher Fingerprint-Ermittlung: dokumentbezogene Logs enthalten den Fingerprint oder eine eindeutig ableitbare Referenz.
- Keine neue Persistenz-Wahrheit oder zusätzliche Tracking-Ebene.

### Sensibilitätsregel für KI-Inhalte
- Vollständige KI-Rohantwort: standardmäßig **nicht** ins Log, bleibt in SQLite.
- Vollständiges KI-`reasoning`: standardmäßig **nicht** ins Log, bleibt in SQLite.
- Freischaltung nur über expliziten booleschen Konfigurationswert.
- Default: sicher / nicht loggen.

## Verarbeitungsreihenfolge pro Dokument (aktiver Stand)

1. Fingerprint berechnen
2. Dokument-Stammsatz laden
3. Terminale Skip-Fälle entscheiden (`SUCCESS` → `SKIPPED_ALREADY_PROCESSED`, `FAILED_FINAL` → `SKIPPED_FINAL_FAILURE`)
4. Falls nötig: Pfad bis `PROPOSAL_READY` durchlaufen (inkl. KI-Aufruf)
5. Führenden `PROPOSAL_READY`-Versuch laden
6. Finalen Basis-Dateinamen bilden
7. Dubletten-Suffix im Zielordner bestimmen
8. Zielkopie schreiben (temporäre Datei + finaler Move/Rename; bei Fehler: genau ein Sofort-Wiederholversuch)
9. Retry-Entscheidung ableiten
10. Neuen Versuch historisieren, Stammsatz konsistent fortschreiben

## Zielkopie-Semantik
- Kopie zunächst in temporäre Zieldatei im Zielkontext
- Finaler Move/Rename auf den geplanten Zieldateinamen
- Quelldatei bleibt **immer unverändert**
- Bei technischem Schreibfehler: genau ein Sofort-Wiederholversuch (nur Zielkopierpfad)
- Bei Persistenzfehler nach erfolgreicher Zielkopie: kein `SUCCESS` setzen, best-effort Rückbau der Zielkopie, Ergebnis bleibt dokumentbezogener technischer Fehler

## Fehlersemantik (aktiver Stand)
- Technische Fehler → `FAILED_RETRYABLE`, Transientfehlerzähler +1
- Bei Erreichen von `max.retries.transient` → `FAILED_FINAL`
- Kein Abbruch des Batch-Laufs für andere Dokumente
- Keine neue finale Fehlerkategorie
- Vor-Fingerprint-Fehler werden **nicht** als SQLite-Versuch historisiert

## Persistenz (aktiver Stand)

Zwei-Ebenen-Modell bleibt unverändert – 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

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

## Naming-Regel (verbindlich für alle Arbeitspakete)
In Implementierungen, Kommentaren und JavaDoc dürfen **keine** Meilenstein- oder
Arbeitspaket-Bezeichner erscheinen:

- Verboten: `M1`, `M2`, `M3`, `M4`, `M5`, `M6`, `M7`, `M8`
- Verboten: `AP-001`, `AP-002`, … `AP-00x`

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 Meilenstein** und im **explizit aktiven Arbeitspaket**
- **Kein Vorgriff** auf spätere Meilensteine oder 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

## 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 und Tests ergänzt sind, **soweit für den Stand sinnvoll**
- keine Inhalte späterer Meilensteine 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:
  `.\mvnw.cmd clean verify -pl pdf-umbenenner-domain,pdf-umbenenner-application,pdf-umbenenner-adapter-out,pdf-umbenenner-adapter-in-cli,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`
- Run-Lock verhindert parallele Instanzen; wenn bereits eine Instanz läuft, beendet sich die neue Instanz sofort
- Exit-Code `0`: Lauf technisch ordnungsgemäß ausgeführt, auch wenn einzelne Dateien fachlich oder transient fehlgeschlagen sind
- Exit-Code `1`: harter Start-/Bootstrap-Fehler
- Umgebungsvariable hat Vorrang vor Properties beim API-Key
- 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
- `api.baseUrl` – KI-Basis-URL
- `api.model` – Modellname
- `api.timeoutSeconds` – Timeout
- `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)
- `api.key` – API-Key (Umgebungsvariable hat Vorrang)

## Nicht-Ziele / Verbote
- 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 stillen Änderungen an Provider-Bindung oder Architekturprinzipien
- kein Sofort-Wiederholversuch außerhalb des Zielkopierpfads
- keine Reporting- oder Statistikfunktionen
- keine neue dritte Persistenz-Wahrheitsquelle für Retry-Entscheidungen
- kein M8-Gesamtfeinschliff oder großflächiges Refactoring