# 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
Nutze ausschließlich die im Repository abgelegten Dokumente als verbindliche Grundlage:

1. `docs/specs/technik-und-architektur.md`
2. `docs/specs/fachliche-anforderungen.md`
3. `docs/specs/meilensteine.md`
4. das jeweils aktive Arbeitspaket-Dokument unter `docs/workpackages/`, z. B. `docs/workpackages/M1 - Arbeitspakete.md`, `docs/workpackages/M2 - Arbeitspakete.md`

Diese Dateien müssen im Repository tatsächlich vorhanden sein. Vor Implementierungsentscheidungen sind die für das aktuelle Arbeitspaket relevanten Dokumente gezielt zu lesen. 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

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

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

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

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