260 lines
12 KiB
Markdown
260 lines
12 KiB
Markdown
# 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 M5 sind vollständig abgeschlossen. Der aktive Stand ergänzt den vollständigen
|
||
Erfolgspfad: korrekt benannte Zielkopie erzeugen und Enderfolg konsistent persistieren.
|
||
|
||
### Baseline aus M5
|
||
- Externer Prompt-Bezug über konfigurierbare Prompt-Datei
|
||
- OpenAI-kompatibler HTTP-Adapter vollständig verdrahtet
|
||
- Validierte KI-Antwort mit `date`, `title`, `reasoning`
|
||
- Persistierter Benennungsvorschlag mit Status `PROPOSAL_READY`
|
||
- Versuchshistorie mit KI-Nachvollziehbarkeit (Modell, Prompt-ID, Zeichenzahl, Rohantwort, Reasoning, Datum, Datumsquelle)
|
||
- Idempotente Migration M4 → M5
|
||
|
||
### Ziel des aktiven Stands
|
||
- 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 auf den aktiven Stand (Zielpfad, Zieldateiname)
|
||
- Statustransition `PROPOSAL_READY` → `SUCCESS`
|
||
- Zusätzliche Historisierung für Enderfolg und technische Fehler (Proposal-Versuch bleibt erhalten)
|
||
- Startvalidierung für Zielordner-Konfiguration (`target.folder`)
|
||
|
||
## 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.
|
||
|
||
## 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: M5-Pfad bis `PROPOSAL_READY` durchlaufen
|
||
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)
|
||
9. Neuen Versuch für Enderfolg oder technischen Fehler historisieren
|
||
10. Dokument-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**
|
||
- Kein Sofort-Wiederholversuch im selben Lauf
|
||
- Bei Persistenzfehler nach erfolgreicher Zielkopie: kein `SUCCESS` setzen, best-effort Rückbau der Zielkopie vorsehen, Ergebnis bleibt dokumentbezogener technischer Fehler
|
||
|
||
## Fehlersemantik (aktiver Stand)
|
||
Technische Fehler bei Proposal-Quelllesung, Zielpfadbildung, Dublettenauflösung,
|
||
Zielkopie oder aktiver Persistenz nach Fingerprint-Ermittlung:
|
||
- → dokumentbezogener technischer Fehler
|
||
- → `FAILED_RETRYABLE`, Transientfehlerzähler +1
|
||
- → kein Abbruch des Batch-Laufs für andere Dokumente
|
||
- → keine neue finale Fehlerkategorie
|
||
|
||
## Persistenzerweiterung (aktiver Stand)
|
||
|
||
**Dokument-Stammsatz** erhält zusätzlich:
|
||
- letzten Zielpfad
|
||
- letzten Zieldateinamen
|
||
|
||
**Versuchshistorie** erhält zusätzlich:
|
||
- finalen Zieldateinamen
|
||
|
||
**Invariante:** Der führende `PROPOSAL_READY`-Versuch wird nicht überschrieben.
|
||
Enderfolg und technische Fehler des aktiven Stands werden als **zusätzliche neue Versuche** historisiert.
|
||
|
||
## 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` – maximale transiente Wiederholversuche
|
||
- `max.pages` – Seitenlimit
|
||
- `max.text.characters` – maximale Zeichenzahl für KI-Eingabe
|
||
- `prompt.template.file` – externe Prompt-Datei
|
||
- `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 der Zielkopie im selben Lauf
|
||
- kein Logging-Feinschliff des Endstands
|
||
- keine Reporting- oder Statistikfunktionen
|