M5 AP-003 Adapter-Tests für Timeout und JSON-Request-Inhalt belastbar

gemacht

CLAUDE.md

@@ -21,16 +21,16 @@ Die Dokumente haben folgende feste Bedeutung:
 
 Bei Konflikten gilt folgende Priorität:
 
-1. **Technik- und Architektur-Dokument**  
+1. **Technik- und Architektur-Dokument**
    Verbindliche technische Zielarchitektur. Architekturbrüche sind unzulässig.
 
-2. **Fachliche Anforderungen**  
+2. **Fachliche Anforderungen**
    Verbindliche fachliche Regeln und fachliches Zielverhalten.
 
-3. **Meilensteine**  
+3. **Meilensteine**
    Begrenzen den zulässigen Funktionsumfang auf den aktuellen Entwicklungsstand.
 
-4. **Arbeitspakete**  
+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.
@@ -66,11 +66,13 @@ Wenn Dokumente fehlen, unklar sind oder sich widersprechen, nicht raten und kein
 - 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
@@ -81,12 +83,111 @@ Wenn Dokumente fehlen, unklar sind oder sich widersprechen, nicht raten und kein
 - 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
@@ -97,9 +198,25 @@ Ein Arbeitspaket ist erst fertig, wenn:
 - 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
 
@@ -109,6 +226,23 @@ Ein Arbeitspaket ist erst fertig, wenn:
 - 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
@@ -120,3 +254,6 @@ Ein Arbeitspaket ist erst fertig, wenn:
 - 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