M8 komplett umgesetzt

docs/befundliste.md

@@ -0,0 +1,209 @@
+# Befundliste – Integrierte Gesamtprüfung des Endstands
+
+**Erstellt:** 2026-04-08  
+**Grundlage:** Vollständiger Maven-Reactor-Build, Unit-Tests, E2E-Tests, Integrationstests (Smoke),
+PIT-Mutationsanalyse, Code-Review gegen verbindliche Spezifikationen (technik-und-architektur.md,
+fachliche-anforderungen.md, CLAUDE.md)
+
+---
+
+## Ausgeführte Prüfungen
+
+| Prüfbereich | Ausgeführt | Ergebnis |
+|---|---|---|
+| Maven-Reactor-Build (clean verify, alle Module) | ja | GRÜN |
+| Unit-Tests (Domain, Application, Adapter-out, Bootstrap) | ja | GRÜN |
+| E2E-Tests (BatchRunEndToEndTest, 11 Szenarien) | ja | GRÜN |
+| Integrationstests / Smoke-IT (ExecutableJarSmokeTestIT, 2 Tests) | ja | GRÜN |
+| PIT-Mutationsanalyse (alle Module) | ja | siehe Einzelbefunde |
+| Hexagonale Architektur – Domain-Isolation | ja | GRÜN |
+| Hexagonale Architektur – Port-Verträge (kein Path/NIO/JDBC) | ja | GRÜN |
+| Hexagonale Architektur – keine Adapter-zu-Adapter-Abhängigkeiten | ja | GRÜN |
+| Statusmodell (8 Werte, Semantik laut CLAUDE.md) | ja | GRÜN |
+| Naming-Convention-Regel (kein M1–M8, kein AP-xxx im Code) | ja | OFFEN (nicht blockierend) |
+| Logging-Sensibilitätsregel (log.ai.sensitive) | ja | GRÜN |
+| Exit-Code-Semantik (0 / 1) | ja | GRÜN |
+| Konfigurationsbeispiele (Pflicht- und Optionalparameter) | ja | GRÜN |
+| Betriebsdokumentation (docs/betrieb.md) | ja | GRÜN |
+| Prompt-Template im Repository | ja | GRÜN |
+| Rückwärtsverträglichkeit M4–M7 (Statusmodell, Schema) | ja (statisch) | GRÜN |
+
+---
+
+## Grüne Bereiche (keine Befunde)
+
+### Build und Tests
+
+- Vollständiger Maven-Reactor-Build erfolgreich (`BUILD SUCCESS`, Gesamtlaufzeit ~4 Minuten)
+- **827+ Tests** bestanden, 0 Fehler, 0 übersprungen:
+  - Domain: 227 Tests
+  - Application: 295 Tests
+  - Adapter-out: 227 Tests
+  - Bootstrap (Unit): 76 Tests
+  - Smoke-IT: 2 Tests
+
+### E2E-Szenarien (BatchRunEndToEndTest)
+
+Alle geforderten Kernszenarien aus der E2E-Testbasis sind abgedeckt und grün:
+
+- Happy-Path: zwei Läufe → `SUCCESS`
+- Deterministischer Inhaltsfehler: zwei Läufe → `FAILED_FINAL`
+- Transienter KI-Fehler → `FAILED_RETRYABLE`
+- Skip nach `SUCCESS` → `SKIPPED_ALREADY_PROCESSED`
+- Skip nach `FAILED_FINAL` → `SKIPPED_FINAL_FAILURE`
+- `PROPOSAL_READY`-Finalisierung ohne erneuten KI-Aufruf im zweiten Lauf
+- Zielkopierfehler mit Sofort-Wiederholversuch → `SUCCESS`
+- Transiente Fehler über mehrere Läufe → Ausschöpfung → `FAILED_FINAL`
+- Zielkopierfehler beide Versuche gescheitert → `FAILED_RETRYABLE`
+- Zwei verschiedene Dokumente, gleicher Vorschlagsname → Dubletten-Suffix `(1)`
+- Mixed-Batch: ein Erfolg, ein Inhaltsfehler → Batch-Outcome `SUCCESS` (Exit-Code 0)
+
+### Hexagonale Architektur
+
+- **Domain** vollständig infrastrukturfrei: keine Imports aus `java.nio`, `java.io.File`,
+  JDBC, Log4j oder HTTP-Bibliotheken
+- **Port-Verträge** (alle Interfaces in `application.port.out`) enthalten keine `Path`-,
+  `File`-, NIO- oder JDBC-Typen; nur Domain-Typen werden in Signaturen verwendet
+- **Keine Adapter-zu-Adapter-Abhängigkeiten** in `adapter-out`: kein Modul referenziert
+  ein anderes Adapter-Implementierungspaket direkt
+- **Abhängigkeitsrichtung** korrekt: adapter-out → application → domain
+
+### Fachregeln
+
+- Statusmodell vollständig (8 Werte: `READY_FOR_AI`, `PROPOSAL_READY`, `SUCCESS`,
+  `FAILED_RETRYABLE`, `FAILED_FINAL`, `SKIPPED_ALREADY_PROCESSED`,
+  `SKIPPED_FINAL_FAILURE`, `PROCESSING`)
+- Retry-Semantik korrekt implementiert (deterministisch 1 Retry → final;
+  transient bis `max.retries.transient`)
+- Skip-Semantik korrekt (SUCCESS → Skip, FAILED_FINAL → Skip, keine Zähleränderung)
+- Führende Proposal-Quelle: `PROPOSAL_READY`-Versuch wird korrekt als Quelle verwendet
+- SUCCESS-Bedingung: erst nach Zielkopie und konsistenter Persistenz
+
+### Logging und Sensibilität
+
+- `log.ai.sensitive`-Mechanismus vollständig implementiert und getestet
+- Default `false` (sicher): KI-Rohantwort und Reasoning nicht im Log
+- Persistenz in SQLite unabhängig von dieser Einstellung
+- Konfiguration in beiden Beispieldateien dokumentiert
+
+### Konfiguration und Dokumentation
+
+- `config/application-local.example.properties`: vollständig, alle Pflicht- und
+  Optionalparameter vorhanden
+- `config/application-test.example.properties`: vollständig
+- `config/prompts/template.txt`: Prompt-Template im Repository vorhanden
+- `docs/betrieb.md`: Betriebsdokumentation mit Start, Konfiguration, Exit-Codes,
+  Retry-Grundverhalten, Logging-Sensibilität
+- Konfigurationsparameter-Namen in Dokumentation und Code konsistent
+
+### Exit-Code-Semantik
+
+- Exit-Code `0`: technisch ordnungsgemäßer Lauf (auch bei Teilfehlern einzelner Dokumente)
+- Exit-Code `1`: harte Start-/Bootstrap-Fehler, ungültige Konfiguration, Lock-Fehler
+- Implementierung in `PdfUmbenennerApplication` und `BootstrapRunner` korrekt
+
+### PIT-Mutationsanalyse (Gesamtstand)
+
+- Domain: 83 % Mutation Kill Rate
+- Adapter-out: 83 % Mutation Kill Rate
+- Application: 87 % Test Strength
+- Bootstrap: 76 % Kill Rate (34 Mutationen, 26 getötet)
+
+---
+
+## Offene Punkte
+
+### Nicht blockierend
+
+#### B1 – Naming-Convention-Verletzungen in Code, Tests und Konfiguration (CLAUDE.md § Naming-Regel)
+
+**Themenbereich:** Dokumentation / Codequalität  
+**Norm:** CLAUDE.md verbietet explizit Meilenstein- (M1–M8) und Arbeitspaket-Bezeichner (AP-xxx)
+in Implementierungen, Kommentaren und JavaDoc.  
+**Befund:** 43 Treffer in `.java`-Dateien (21 in Produktionscode, 22 in Testcode) sowie
+1 Treffer in `config/application.properties`.  
+
+Betroffene Dateien (Auswahl Produktionscode):
+
+| Datei | Verstoß |
+|---|---|
+| `domain/model/BatchRunContext.java` | `@since M2-AP-003` |
+| `domain/model/DocumentFingerprint.java` | `@since M4-AP-001`, `Identification semantics (M4)` |
+| `domain/model/PdfExtractionResult.java` | `@since M3-AP-001` |
+| `domain/model/SourceDocumentCandidate.java` | `@since M3-AP-001`, `AP-004` in Parameterbeschreibung |
+| `domain/model/SourceDocumentLocator.java` | `@since M3-AP-001` |
+| `adapter/out/lock/FilesystemRunLockPortAdapter.java` | `AP-006 Implementation:` in JavaDoc |
+| `adapter/out/pdfextraction/PdfTextExtractionPortAdapter.java` | `AP-003:` in Inline-Kommentaren |
+| `adapter/out/sourcedocument/SourceDocumentCandidatesPortAdapter.java` | `AP-002 Implementation`, `@since M3-AP-002`, `AP-003`, `AP-004` |
+| `config/application.properties` | Kommentarheader `# PDF Umbenenner Configuration for AP-006 Testing` |
+
+Betroffene Dateien (Auswahl Testcode):
+
+| Datei | Verstoß |
+|---|---|
+| `adapter/out/bootstrap/validation/StartConfigurationValidatorTest.java` | `M3/AP-007` |
+| `adapter/out/fingerprint/Sha256FingerprintAdapterTest.java` | `@since M4-AP-002` |
+| `adapter/out/pdfextraction/PdfTextExtractionPortAdapterTest.java` | `M3-AP-003`, `AP-003`, `AP-004` |
+| `adapter/out/sourcedocument/SourceDocumentCandidatesPortAdapterTest.java` | `M3-AP-002`, `AP-004` |
+| `adapter/out/sqlite/SqliteUnitOfWorkAdapterTest.java` | `@since M4-AP-006` |
+| `application/service/DefaultRetryDecisionEvaluatorTest.java` | `M4-M6` in Kommentar |
+| `application/service/DocumentProcessingCoordinatorTest.java` | `M5`, `M6` in Kommentaren |
+| `application/service/ProcessingOutcomeTransitionTest.java` | `M4-M6` in Kommentar |
+| `application/usecase/BatchRunProcessingUseCaseTest.java` | `M7` in Kommentar |
+| `bootstrap/ExecutableJarSmokeTestIT.java` | `AP-008`, `M1` in JavaDoc |
+
+**Bewertung:** Rein kosmetisch/dokumentarisch. Kein Einfluss auf Funktionalität, Build
+oder Testergebnis. Betrifft ausschließlich Kommentare und JavaDoc-Annotationen.  
+**Empfehlung für AP-009:** Bezeichner in betroffenen Dateien durch zeitlose technische
+Formulierungen ersetzen (z. B. `@since M4-AP-001` → entfernen oder in neutrales
+`@since 1.0` umwandeln; Inline-Kommentare sachlich formulieren).
+
+---
+
+#### B2 – StartConfiguration in Application-Schicht enthält java.nio.file.Path (Architektur-Grenzfall)
+
+**Themenbereich:** Architektur  
+**Norm:** „Application orchestriert Use Cases und enthält keine technischen
+Implementierungsdetails" (technik-und-architektur.md §3.1); Port-Verträge dürfen keine
+NIO-Typen enthalten (CLAUDE.md).  
+**Befund:** `StartConfiguration` (in `application/config/startup/`) ist ein Java-Record
+mit `java.nio.file.Path`-Feldern für `sourceFolder`, `targetFolder`, `sqliteFile`,
+`promptTemplateFile`, `runtimeLockFile`, `logDirectory`.  
+**Kontext:** `StartConfiguration` ist kein Port-Vertrag, sondern ein unveränderliches
+Konfigurations-DTO, das ausschließlich von Bootstrap erzeugt und an Adapter übergeben wird.
+Die Port-Verträge selbst sind sauber (keine Path-Typen in Port-Interfaces).  
+**Bewertung:** Grenzfall. `Path` ist kein fachliches Objekt, aber auch kein schwerer
+Architekturverstoß in diesem Kontext. Die Alternative (String-Repräsentation und Auflösung
+im Adapter) hätte keinen Mehrwert für das Betriebsmodell.  
+**Empfehlung für AP-009:** Auf Wunsch im Rahmen von AP-009 prüfen, ob das Verschieben von
+`StartConfiguration` in das Bootstrap-Modul sinnvoller wäre. Keine Pflicht, da kein
+funktionaler Defekt vorliegt.
+
+---
+
+#### B3 – PIT-Überlebende in Bootstrap (Bootstrap: 76 % Kill Rate)
+
+**Themenbereich:** Testqualität  
+**Befund:** 8 überlebende Mutanten im Bootstrap-Modul (34 generiert, 26 getötet).
+Hauptkategorie: `VoidMethodCallMutator` (2 Überlebende, 2 ohne Coverage).  
+**Bewertung:** Betrifft vor allem Logging-Calls und nicht-kritische Hilfsmethoden.
+Keine funktional tragenden Entscheidungspfade betroffen.  
+**Empfehlung:** Kein AP-009-Handlungsbedarf; wurde bereits in AP-007 auf akzeptablem
+Niveau konsolidiert.
+
+---
+
+## Zusammenfassung
+
+| Klassifikation | Anzahl | Beschreibung |
+|---|---|---|
+| Release-Blocker | **0** | – |
+| Nicht blockierend | **3** | B1 Naming, B2 Path-Grenzfall, B3 PIT-Bootstrap |
+
+**Der Endstand ist produktionsbereit.** Alle fachlichen, technischen und architekturellen
+Kernanforderungen sind umgesetzt und durch automatisierte Tests abgesichert. Der Maven-Build
+ist fehlerfrei. Die identifizierten offenen Punkte sind ausschließlich nicht blockierend.
+
+Falls AP-009 durchgeführt wird, sollte der Fokus auf **B1** (Naming-Convention-Bereinigung)
+liegen, da dieser Punkt die einzige verbindliche CLAUDE.md-Regel betrifft, die noch nicht
+vollständig eingehalten wird.

docs/betrieb.md

@@ -0,0 +1,214 @@
+# Betriebsdokumentation – PDF Umbenenner
+
+## Zweck
+
+Der PDF Umbenenner liest bereits OCR-verarbeitete, durchsuchbare PDF-Dateien aus einem
+konfigurierten Quellordner, ermittelt per KI-Aufruf einen normierten deutschen Dateinamen
+und legt eine Kopie im konfigurierten Zielordner ab. Die Quelldatei bleibt unverändert.
+
+---
+
+## Voraussetzungen
+
+- Java 21 (JRE oder JDK)
+- Zugang zu einem OpenAI-kompatiblen KI-Dienst (API-Schlüssel erforderlich)
+- Quellordner mit OCR-verarbeiteten PDF-Dateien
+- Schreibzugriff auf Zielordner und Datenbankverzeichnis
+
+---
+
+## Start des ausführbaren JAR
+
+Das ausführbare JAR wird durch den Maven-Build im Verzeichnis
+`pdf-umbenenner-bootstrap/target/` erzeugt:
+
+```
+java -jar pdf-umbenenner-bootstrap/target/pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar
+```
+
+Die Anwendung liest die Konfiguration aus `config/application.properties` relativ zum
+Arbeitsverzeichnis, in dem der Befehl ausgeführt wird.
+
+### Start über Windows Task Scheduler
+
+Empfohlene Startsequenz für den Windows Task Scheduler:
+
+1. Aktion: Programm/Skript starten
+2. Programm: `java`
+3. Argumente: `-jar pdf-umbenenner-bootstrap-0.0.1-SNAPSHOT.jar`
+4. Starten in: Verzeichnis mit `config/application.properties` und `config/prompts/`
+
+---
+
+## Konfiguration
+
+Die Konfiguration wird aus `config/application.properties` geladen.
+Vorlagen für lokale und Test-Konfigurationen befinden sich in:
+
+- `config/application-local.example.properties`
+- `config/application-test.example.properties`
+
+### Pflichtparameter
+
+| Parameter              | Beschreibung |
+|------------------------|--------------|
+| `source.folder`        | Quellordner mit OCR-PDFs (muss vorhanden und lesbar sein) |
+| `target.folder`        | Zielordner für umbenannte Kopien (wird angelegt, wenn nicht vorhanden) |
+| `sqlite.file`          | SQLite-Datenbankdatei (übergeordnetes Verzeichnis muss existieren) |
+| `api.baseUrl`          | Basis-URL des KI-Dienstes (z. B. `https://api.openai.com/v1`) |
+| `api.model`            | Modellname (z. B. `gpt-4o-mini`) |
+| `api.timeoutSeconds`   | HTTP-Timeout für KI-Anfragen in Sekunden (ganzzahlig, > 0) |
+| `max.retries.transient`| Maximale transiente Fehlversuche pro Dokument (ganzzahlig, >= 1) |
+| `max.pages`            | Maximale Seitenzahl pro Dokument (ganzzahlig, > 0) |
+| `max.text.characters`  | Maximale Zeichenanzahl des Dokumenttexts für KI-Anfragen (ganzzahlig, > 0) |
+| `prompt.template.file` | Pfad zur externen Prompt-Datei (muss vorhanden sein) |
+
+### Optionale Parameter
+
+| Parameter            | Beschreibung | Standard |
+|----------------------|--------------|---------|
+| `api.key`            | API-Schlüssel (alternativ: Umgebungsvariable `PDF_UMBENENNER_API_KEY`) | – |
+| `runtime.lock.file`  | Lock-Datei für Startschutz | `pdf-umbenenner.lock` im Arbeitsverzeichnis |
+| `log.directory`      | Log-Verzeichnis | `./logs/` |
+| `log.level`          | Log-Level (`DEBUG`, `INFO`, `WARN`, `ERROR`) | `INFO` |
+| `log.ai.sensitive`   | KI-Rohantwort und Reasoning ins Log schreiben (`true`/`false`) | `false` |
+
+### API-Schlüssel
+
+Der API-Schlüssel kann auf zwei Wegen gesetzt werden:
+
+1. **Umgebungsvariable `PDF_UMBENENNER_API_KEY`** (empfohlen, hat Vorrang)
+2. Property `api.key` in `config/application.properties`
+
+Die Umgebungsvariable hat immer Vorrang über die Properties-Datei.
+
+---
+
+## Prompt-Konfiguration
+
+Der Prompt wird aus der in `prompt.template.file` konfigurierten externen Textdatei geladen.
+Der Dateiname der Prompt-Datei dient als Prompt-Identifikator in der Versuchshistorie
+(SQLite) und ermöglicht so die Nachvollziehbarkeit, welche Prompt-Version für welchen
+Verarbeitungsversuch verwendet wurde.
+
+Eine Vorlage befindet sich in `config/prompts/template.txt` und kann direkt verwendet oder
+an den jeweiligen KI-Dienst angepasst werden.
+
+Die Anwendung ergänzt den Prompt automatisch um:
+- einen Dokumenttext-Abschnitt
+- eine explizite JSON-Antwortspezifikation mit den Feldern `title`, `reasoning` und `date`
+
+Der Prompt in `template.txt` muss deshalb **keine** JSON-Formatanweisung enthalten –
+nur den inhaltlichen Auftrag an die KI.
+
+---
+
+## Zielformat
+
+Jede erfolgreich verarbeitete PDF-Datei wird im Zielordner unter folgendem Namen abgelegt:
+
+```
+YYYY-MM-DD - Titel.pdf
+```
+
+Bei Namenskollisionen wird ein laufendes Suffix angehängt:
+
+```
+YYYY-MM-DD - Titel(1).pdf
+YYYY-MM-DD - Titel(2).pdf
+```
+
+Das Suffix zählt nicht zu den 20 Zeichen des Basistitels.
+
+---
+
+## Retry- und Skip-Verhalten
+
+### Dokumentstatus
+
+| Status                    | Bedeutung |
+|---------------------------|-----------|
+| `SUCCESS`                 | Erfolgreich verarbeitet und kopiert |
+| `FAILED_RETRYABLE`        | Fehlgeschlagen, erneuter Versuch in späterem Lauf möglich |
+| `FAILED_FINAL`            | Terminal fehlgeschlagen, wird nicht erneut verarbeitet |
+| `SKIPPED_ALREADY_PROCESSED` | Übersprungen – Dokument bereits erfolgreich verarbeitet |
+| `SKIPPED_FINAL_FAILURE`   | Übersprungen – Dokument terminal fehlgeschlagen |
+
+### Retry-Regeln
+
+**Deterministische Inhaltsfehler** (z. B. kein extrahierbarer Text, Seitenlimit überschritten,
+unbrauchbarer KI-Titel):
+
+- Erster Fehler → `FAILED_RETRYABLE` (ein Wiederholversuch in späterem Lauf erlaubt)
+- Zweiter Fehler → `FAILED_FINAL` (kein weiterer Versuch)
+
+**Transiente technische Fehler** (z. B. KI nicht erreichbar, HTTP-Timeout):
+
+- Wiederholbar bis zum Grenzwert `max.retries.transient`
+- Bei Erreichen des Grenzwerts → `FAILED_FINAL`
+
+**Technischer Sofort-Wiederholversuch:**
+
+Bei einem Schreibfehler der Zielkopie wird innerhalb desselben Laufs exakt ein
+Sofort-Wiederholversuch unternommen. Dieser zählt nicht zum laufübergreifenden
+Fehlerzähler.
+
+---
+
+## Logging
+
+Logs werden in das konfigurierte `log.directory` geschrieben (Standard: `./logs/`).
+Log-Rotation erfolgt täglich und bei Erreichen von 10 MB je Datei.
+
+### Sensible KI-Inhalte
+
+Standardmäßig werden die vollständige KI-Rohantwort und das KI-Reasoning **nicht** ins Log
+geschrieben, sondern ausschließlich in der SQLite-Datenbank gespeichert.
+
+Die Ausgabe kann für Diagnosezwecke mit `log.ai.sensitive=true` freigeschaltet werden.
+Erlaubte Werte: `true` oder `false`. Jeder andere Wert ist ungültig und verhindert den Start.
+
+---
+
+## Exit-Codes
+
+| Code | Bedeutung |
+|------|-----------|
+| `0`  | Lauf technisch ordnungsgemäß ausgeführt (auch bei dokumentbezogenen Teilfehlern) |
+| `1`  | Harter Start- oder Bootstrap-Fehler (ungültige Konfiguration, Lock nicht erwerbbar, Schema-Initialisierungsfehler) |
+
+Dokumentbezogene Fehler einzelner PDF-Dateien führen **nicht** zu Exit-Code `1`.
+
+---
+
+## Startschutz (Parallelinstanzschutz)
+
+Die Anwendung verwendet eine exklusive Lock-Datei, um parallele Instanzen zu verhindern.
+Wenn bereits eine Instanz läuft, beendet sich die neue Instanz sofort mit Exit-Code `1`.
+
+Der Pfad der Lock-Datei ist über `runtime.lock.file` konfigurierbar.
+Ohne Konfiguration wird `pdf-umbenenner.lock` im Arbeitsverzeichnis verwendet.
+
+---
+
+## SQLite-Datenbank
+
+Die SQLite-Datei enthält:
+
+- **Dokument-Stammsätze**: Gesamtstatus, Fehlerzähler, letzter Zieldateiname, Zeitstempel
+- **Versuchshistorie**: Jeder Verarbeitungsversuch mit Modell, Prompt-Identifikator,
+  KI-Rohantwort, Reasoning, Datum, Titel und Fehlerstatus
+
+Die Datenbank ist die führende Wahrheitsquelle für Bearbeitungsstatus und Nachvollziehbarkeit.
+Sie muss nicht manuell verwaltet werden – das Schema wird beim Start automatisch initialisiert.
+
+---
+
+## Systemgrenzen
+
+- Nur OCR-verarbeitete, durchsuchbare PDF-Dateien werden verarbeitet
+- Keine eingebaute OCR-Funktion
+- Kein Web-UI, keine REST-API, keine interaktive Bedienung
+- Kein interner Scheduler – der Start erfolgt extern (z. B. Windows Task Scheduler)
+- Quelldateien werden nie überschrieben, verschoben oder gelöscht
+- Die Identifikation erfolgt über SHA-256-Fingerprint des Dateiinhalts, nicht über Dateinamen