M1-Fix: Exit-Code für ungültige Konfiguration auf 1 geändert

docs/specs/meilensteine.md

@@ -0,0 +1,334 @@
+# Meilensteine – KI-gestützte Umbenennung OCR-verarbeiteter PDFs
+
+## Grundsätze für alle Meilensteine
+
+- Jeder Meilenstein liefert einen **in sich geschlossenen, lauffähigen Entwicklungsstand**.
+- Jeder Meilenstein umfasst **Implementierung, Konfiguration, JavaDoc und Tests**, soweit für den jeweiligen Stand sinnvoll.
+- Die Lösung wird von Beginn an in **strenger hexagonaler Architektur** umgesetzt.
+- Jeder Meilenstein baut auf dem vorherigen Stand auf, ohne Architekturbrüche oder provisorische Seiteneffekte zu erzeugen.
+- Die Meilensteine bilden zusammen vollständig die fachlichen Anforderungen sowie das technische Zielbild ab.
+- Fachliche Entscheidungen werden nicht in technische Adapter verschoben, technische Infrastruktur nicht in die Domain.
+
+---
+
+## M1 – Vollständiges Maven-Projekt und technisches Grundgerüst
+
+### Ziel
+Erstellung eines vollständig lauffähigen Multi-Modul-Maven-Projekts als stabile Basis der Gesamtentwicklung.
+
+### Inhalt
+- vollständige Maven-Projektstruktur in strenger Hexagonal-Architektur erstellen:
+  - `domain`
+  - `application`
+  - `adapter-in`
+  - `adapter-out`
+  - `bootstrap`
+- Parent-POM mit `packaging=pom` anlegen
+- Modul-POMs vollständig konfigurieren
+- alle benötigten Dependencies fest einbinden, insbesondere für:
+  - Log4j2
+  - Apache PDFBox
+  - SQLite JDBC
+  - OpenAI-kompatiblen HTTP-Zugriff
+  - JSON-Verarbeitung
+  - Test-Frameworks
+- benötigte Maven-Plugins vollständig konfigurieren, insbesondere für:
+  - Compiler
+  - Surefire
+  - Enforcer
+  - Shade im Bootstrap-Modul
+- Logging-Konfiguration mit Log4j2 anlegen
+- lauffähigen Bootstrap-Einstiegspunkt bereitstellen
+- `.properties`-Konfiguration grundlegend laden
+- Grundvalidierung der Startkonfiguration vorsehen
+- Build-, Start- und Testfähigkeit herstellen
+
+### Lauffähiger Stand
+- das Projekt baut vollständig mit Maven
+- das ausführbare JAR startet erfolgreich
+- Logging funktioniert
+- Konfiguration wird geladen oder sauber validiert
+- das Programm beendet sich kontrolliert ohne fachliche Verarbeitung
+
+### Tests
+- Build-/Smoke-Test für Programmstart
+- Tests für Konfigurationsladen und Grundvalidierung
+- Tests für Logging-/Bootstrap-Grundverhalten, soweit sinnvoll
+
+---
+
+## M2 – Hexagonaler Kern, Batch-Startfall und Startschutz
+
+### Ziel
+Der fachliche Kern, der Batch-Einstieg und der technische Startschutz sind sauber modelliert, jedoch noch ohne vollständige Dokumentverarbeitung.
+
+### Inhalt
+- Domain-Objekte und Statusmodell anlegen
+- zentrale Ports definieren
+- zentralen Inbound-Use-Case für den Batch-Lauf implementieren
+- CLI-/Batch-Adapter implementieren
+- Bootstrap-Verdrahtung vervollständigen
+- Run-Lock-Port und erste Lock-Implementierung einführen
+- Lauf-ID-Konzept einführen
+- Exit-Code-Grundverhalten vorbereiten:
+  - `0` für technisch ordnungsgemäß ausgeführten Lauf
+  - `1` für harte Start-/Bootstrap-Fehler
+- JavaDoc für Architekturgrenzen, Ports und zentrale Typen ergänzen
+
+### Lauffähiger Stand
+- das Programm startet als Batch-Prozess
+- Lauf-Sperre wird gesetzt und freigegeben
+- eine zweite Instanz beendet sich kontrolliert sofort
+- der Use-Case wird über den Inbound-Adapter erreicht
+- Architekturgrenzen sind technisch sichtbar und eingehalten
+- noch keine echte PDF-Verarbeitung, aber kontrollierter Batch-Ablauf vorhanden
+
+### Tests
+- Unit-Tests für Domain-Objekte und Statusmodell
+- Tests für Lock-Verhalten
+- Tests für Bootstrap- und Use-Case-Verdrahtung
+- Tests für Exit-Code-Verhalten bei Startschutz- und Bootstrap-Fehlern, soweit in diesem Stand sinnvoll
+
+---
+
+## M3 – Dateisystemzugriff, Kandidatenermittlung und PDF-Textauslese
+
+### Ziel
+Der Batch-Prozess kann PDFs im Quellordner finden, fachlich als Verarbeitungskandidaten behandeln sowie Text und Seitenzahl extrahieren.
+
+### Inhalt
+- Dateisystem-Adapter für Quellordnerzugriff implementieren
+- PDF-Dateifilter gemäß fachlicher Regeln umsetzen
+- PDFBox-Adapter zur Textauslese implementieren
+- Seitenzahlermittlung integrieren
+- Prüfung auf „brauchbaren Text“ umsetzen
+- konfigurierbares Seitenlimit einführen
+- erste Dateiobjekte und Metadatenfluss im Use-Case herstellen
+- sicherstellen, dass bei fehlendem brauchbarem Text oder überschrittenem Seitenlimit **kein KI-Aufruf** erfolgt
+- JavaDoc für Adapter, Fehlerfälle und Kandidatenbegriff ergänzen
+
+### Lauffähiger Stand
+- das Programm scannt den Quellordner
+- passende PDFs werden erkannt
+- Text und Seitenzahl werden extrahiert
+- Dateien ohne brauchbaren Text oder oberhalb des Seitenlimits werden erkannt und protokolliert
+- diese Fälle werden als deterministische Inhaltsfehler behandelt
+- noch keine KI-Anbindung und noch keine Ergebnisdatei
+
+### Tests
+- Unit-Tests für PDF-Filterlogik
+- Tests für Textauslese und Seitenzahlerkennung
+- Tests für Fehlerfälle „kein brauchbarer Text“ und „Seitenlimit überschritten“
+- Tests dafür, dass in diesen Fehlerfällen kein KI-Aufruf stattfindet
+
+---
+
+## M4 – Fingerprint, SQLite-Persistenz und Idempotenz
+
+### Ziel
+Die Anwendung kann verarbeitete Dateien stabil wiedererkennen, Bearbeitungszustände dauerhaft speichern und jeden Verarbeitungsversuch nachvollziehbar historisieren.
+
+### Inhalt
+- Fingerprint-Port und SHA-256-basierte Implementierung einführen
+- SQLite-Schema vollständig implementieren
+- Persistenzmodell explizit in **zwei Ebenen** umsetzen:
+  - Dokument-Stammsatz pro Fingerprint
+  - Versuchshistorie mit einem Datensatz pro Verarbeitungsversuch
+- Statusmodell persistent nutzbar machen
+- Retry-Zähler und Fehlstatus speichern
+- Regeln für „bereits erfolgreich verarbeitet“ und „final fehlgeschlagen“ umsetzen
+- Versuchshistorie explizit mit mindestens folgenden technischen Metadaten anlegen:
+  - Lauf-ID
+  - Versuchsnummer
+  - Start- und Endzeitpunkt
+  - Ergebnisstatus
+  - Fehlerklasse
+  - Fehlermeldung bzw. fachliche/systemische Begründung
+  - Retryable-Flag
+- JavaDoc für Persistenzmodell, Statusübergänge und Idempotenz ergänzen
+
+### Lauffähiger Stand
+- das Programm erkennt identische Quelldateien über Fingerprint wieder
+- erfolgreich verarbeitete Dateien werden in späteren Läufen übersprungen
+- final fehlgeschlagene Dateien werden in späteren Läufen übersprungen
+- Bearbeitungsstände werden in SQLite gespeichert
+- jeder Verarbeitungsversuch wird separat historisiert
+- der Batch-Lauf ist idempotent gegenüber Wiederholungen
+- noch keine KI-Anbindung und noch keine Zielkopie
+
+### Tests
+- Unit-Tests für Fingerprint-Erzeugung
+- Repository-Tests gegen SQLite
+- Tests für Statusübergänge, Retry-Zähler und Skip-Logik
+- Tests für Versuchshistorie pro Lauf und pro Versuch
+
+---
+
+## M5 – KI-Integration, Prompt-Bezug und validierter Benennungsvorschlag
+
+### Ziel
+Die Anwendung kann aus extrahiertem PDF-Text per KI einen validierten Benennungsvorschlag erzeugen und alle KI-bezogenen Nachvollziehbarkeitsdaten persistent festhalten.
+
+### Inhalt
+- externe Prompt-Datei laden und versionierbar anbinden
+- OpenAI-kompatiblen HTTP-Adapter implementieren
+- Basis-URL, Modellname, Timeout und API-Zugriff vollständig konfigurierbar machen
+- Priorität Umgebungsvariable vor Properties für API-Key umsetzen
+- Begrenzung des an die KI gesendeten Inhalts umsetzen
+- parsebares JSON-Ergebnis mit `date`, `title`, `reasoning` verarbeiten
+- Validierung umsetzen:
+  - `title` ist verpflichtend
+  - `reasoning` ist verpflichtend
+  - `date` ist optional
+- fachliche Validierung für Datum und Titel umsetzen
+- falls die KI **kein** belastbares Datum liefert, den Fallback **durch die Anwendung** über die technische Uhr/Clock vorsehen
+- unbrauchbare KI-Antworten als Fehlerfälle behandeln
+- Versuchshistorie um KI-Nachvollziehbarkeit explizit erweitern, insbesondere um:
+  - Modellname
+  - Prompt-Identifikator oder Prompt-Dateiname
+  - verarbeitete Seitenzahl
+  - an KI gesendete Zeichenzahl
+  - KI-Rohantwort
+  - KI-Reasoning
+  - aufgelöstes Datum
+  - Datumsquelle
+- JavaDoc für KI-Port, Antwortvalidierung und Datumsauflösung ergänzen
+
+### Lauffähiger Stand
+- das Programm kann für verarbeitbare PDFs einen gültigen Benennungsvorschlag erzeugen
+- gültige und ungültige KI-Antworten werden korrekt unterschieden
+- bei fehlendem belastbarem KI-Datum wird das Datum durch die Anwendung als Fallback aufgelöst
+- KI-Nachvollziehbarkeit ist persistent gespeichert
+- noch keine physische Zielkopie, aber der vollständige Benennungsvorschlag ist verfügbar und gespeichert
+
+### Tests
+- Unit-Tests für Response-Validierung
+- Tests für Prompt-Laden und Konfigurationsauflösung
+- Tests für Fehlerfälle wie Timeout, ungültiges JSON und unbrauchbaren Titel
+- Tests für Datums-Fallback durch die Anwendung
+- Mock-/Adapter-Tests für den KI-Port
+
+---
+
+## M6 – Dateinamensbildung, Dublettenbehandlung und Zielkopie
+
+### Ziel
+Der vollständige Erfolgspfad wird umgesetzt: Aus KI-Ergebnis und technischer Datumsauflösung wird ein zulässiger Zielname erzeugt und eine Kopie im Zielordner abgelegt.
+
+### Inhalt
+- technische Dateinamensbildung implementieren
+- verbindliches Zielformat umsetzen: `YYYY-MM-DD - Titel.pdf`
+- Windows-Zeichenbereinigung ergänzen
+- Titellängenregel für den **Basistitel** umsetzen
+- feste deutsche Titelregeln technisch absichern
+- fachliche Titelregel „keine Sonderzeichen außer Leerzeichen“ technisch absichern
+- Dubletten-Suffix `(1)`, `(2)` usw. implementieren
+- Zielordnerprüfung und Zielpfadbildung vervollständigen
+- Kopierlogik in den Zielordner implementieren
+- temporäre Zieldatei mit finalem Rename bzw. atomisches Schreiben umsetzen, soweit möglich
+- Erfolgsstatus erst nach erfolgreichem Schreiben **und** erfolgreicher Persistenz setzen
+- finalen Zieldateinamen und Zielpfad persistent speichern
+- JavaDoc für Dateinamensregeln, Dubletten und Zielerzeugung ergänzen
+
+### Lauffähiger Stand
+- das Programm verarbeitet PDFs Ende-zu-Ende erfolgreich
+- bei Erfolg entsteht eine korrekt benannte Kopie im Zielordner
+- die Quelldatei bleibt unverändert erhalten
+- Dubletten werden korrekt ab `(1)` behandelt
+- Erfolgsstatus, Zieldateiname und Zielpfad werden konsistent gespeichert
+
+### Tests
+- Unit-Tests für Dateinamensbildung und Dubletten-Suffixe
+- Tests für technische Zeichenbereinigung
+- Tests für Basistitel-Längenregel und Zielformat
+- integrationsnahe Tests für Zielkopie und Erfolgsstatus
+
+---
+
+## M7 – Fehlerbehandlung, Retry-Logik, Logging und betriebliche Robustheit
+
+### Ziel
+Die Lösung wird robust gegen typische Fehlerfälle und verhält sich in wiederholten Task-Scheduler-Läufen stabil, nachvollziehbar und konsistent.
+
+### Inhalt
+- fachliche Retry-Logik über spätere Läufe vollständig umsetzen
+- deterministische Inhaltsfehler mit genau **1 Retry** in späterem Lauf umsetzen
+- transiente technische Fehler mit Retry bis zum konfigurierten Maximalwert umsetzen
+- finalen Fehlerstatus nach Ausschöpfen der jeweiligen Retry-Regeln umsetzen
+- Sofort-Wiederholversuch nur für Schreibfehler der Zielkopie implementieren
+- Skip-Logik für bereits erfolgreich verarbeitete und final fehlgeschlagene Dateien vervollständigen
+- Logging auf den final geforderten Mindestumfang bringen, insbesondere mit:
+  - Laufstart
+  - Laufende
+  - Lauf-ID
+  - erkannte Quelldatei
+  - Überspringen bereits erfolgreicher Dateien
+  - Überspringen final fehlgeschlagener Dateien
+  - erzeugter Zielname
+  - Retry-Entscheidung
+  - Fehler mit Klassifikation
+- Sensibilitätsregel für Logs umsetzen:
+  - vollständige KI-Rohantwort standardmäßig **nicht** ins Log
+  - vollständige KI-Rohantwort **in SQLite**
+  - Ausgabe sensibler Inhalte konfigurierbar
+- Exit-Code-Verhalten finalisieren:
+  - `0` auch bei Teilfehlern einzelner Dateien, solange der Lauf technisch ordnungsgemäß ausgeführt wurde
+  - `1` nur bei harten Start-/Bootstrap-Fehlern
+- Konfigurationsvalidierung vervollständigen
+- Fehlernachvollziehbarkeit in Logs und SQLite konsistent machen
+- JavaDoc zu Fehlersemantik, Retry-Regeln, Exit-Codes und Logging ergänzen
+
+### Lauffähiger Stand
+- die Anwendung verhält sich in Erfolg, Teilfehlern und Endfehlern stabil
+- wiederholte Scheduler-Läufe führen zu keinem inkonsistenten Verhalten
+- Fehler einzelner Dateien blockieren nicht den Gesamtlauf
+- Retry-Zähler, Endstatus und Überspringen funktionieren konsistent
+- Exit-Code und Logging entsprechen dem definierten Betriebsmodell
+
+### Tests
+- Tests für Retry-Abläufe über mehrere Läufe
+- Tests für finale Fehlerzustände
+- Tests für Skip-Logik bei bereits verarbeiteten Dateien
+- Tests für Sofort-Wiederholversuch bei Zielkopierfehlern
+- Tests für Logging-Sensibilitätsregel, soweit automatisierbar
+- Tests für Konfigurationsfehler und finales Exit-Code-Verhalten
+
+---
+
+## M8 – Abschlussmeilenstein: Qualitätssicherung, Feinschliff und vollständige Entwicklungsfreigabe
+
+### Ziel
+Die Entwicklung wird vollständig abgeschlossen und der Gesamtstand auf Produktionsreife innerhalb des definierten Projektumfangs gebracht.
+
+### Inhalt
+- Review aller Architekturgrenzen und Sicherstellung der strengen Hexagonal-Architektur
+- Abgleich aller Meilenstein-Ergebnisse mit Fachlichkeit sowie Technik/Architektur
+- letzte technische und fachliche Restlücken schließen
+- JavaDoc vervollständigen
+- Testabdeckung gezielt vervollständigen
+- Konfigurationsbeispiel und Startdokumentation konsolidieren
+- Logging- und Fehlermeldungen sprachlich und inhaltlich schärfen
+- letzte Inkonsistenzen in Statusmodell, Persistenz und Adapterverhalten bereinigen
+- End-to-End-Gesamtprüfung des vollständigen Soll-Ablaufs durchführen
+
+### Lauffähiger Stand
+- die Lösung ist innerhalb des definierten Umfangs vollständig implementiert
+- alle Kernanforderungen aus Fachlichkeit sowie Technik/Architektur sind umgesetzt
+- der Stand ist stabil, testbar, dokumentiert und für den geplanten Betrieb bereit
+
+### Tests
+- vollständige End-to-End-Tests, soweit im Projekt sinnvoll automatisierbar
+- Regressionstests für Kernregeln
+- Konsistenztests für Persistenz, Dateinamensbildung, Retry-Logik und Skip-Verhalten
+- abschließende Smoke-Tests für Build, Start und Batch-Lauf
+
+---
+
+## Abschlussbewertung
+
+Die Meilensteine sind mit diesem Stand:
+
+- vollständig auf das fachliche Zielbild ausgerichtet
+- mit dem technischen Architekturziel konsistent
+- widerspruchsfrei und logisch aufeinander aufbauend
+- für eine schrittweise produktive Umsetzung geeignet