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

docs/workpackages/M1 - Arbeitspakete.md

@@ -0,0 +1,203 @@
+# M1 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M1 – Vollständiges Maven-Projekt und technisches Grundgerüst**.
+
+Die Arbeitspakete sind so geschnitten, dass jedes Paket in **einem Durchgang** von einer KI umgesetzt werden kann und danach wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
+
+## Konsistenz- und Schnittregeln
+
+- Jedes Arbeitspaket liefert einen in sich geschlossenen, fehlerfreien Zwischenstand.
+- Die Reihenfolge ist verbindlich, weil jedes Paket auf dem vorherigen Stand aufbaut.
+- Der Fokus bleibt strikt auf **M1**.
+- Es erfolgt **kein Vorgriff auf spätere Meilensteine**.
+- Insbesondere sind in M1 noch **nicht** enthalten:
+  - fachliche PDF-Verarbeitung
+  - Batch-Fachablauf
+  - Run-Lock
+  - Fingerprint
+  - SQLite-Persistenz
+  - KI-Aufruf
+  - Prompt-Verarbeitung
+  - Dateinamenbildung
+  - Zielkopie
+  - Retry-Logik
+
+---
+
+## AP-001 Projekt-Skelett und Parent-POM
+
+### Ziel
+Das Multi-Modul-Maven-Projekt wird strukturell korrekt angelegt.
+
+### Inhalt
+- Root-Projekt mit Parent-POM (`packaging=pom`) anlegen
+- folgende Module anlegen:
+  - `pdf-umbenenner-domain`
+  - `pdf-umbenenner-application`
+  - `pdf-umbenenner-adapter-in-cli`
+  - `pdf-umbenenner-adapter-out`
+  - `pdf-umbenenner-bootstrap`
+- minimale Java- und Ressourcenstruktur pro Modul anlegen
+- neutrale Platzhalterklassen nur dort ergänzen, wo sie für einen fehlerfreien Reactor-Build erforderlich sind
+
+### Fertig wenn
+- die Zielstruktur vollständig vorhanden ist
+- der Maven-Reactor grundsätzlich ausführbar ist
+- noch keine fachliche Verarbeitung implementiert ist
+
+---
+
+## AP-002 Modul-POMs, Dependency-Management und Build-Plugins
+
+### Ziel
+Alle Maven-Grundlagen werden vollständig und konsistent konfiguriert.
+
+### Inhalt
+- Child-POMs vollständig anlegen und sauber auf den Parent ausrichten
+- Java 21 zentral konfigurieren
+- zentrale Versionsverwaltung im Parent-POM vorsehen
+- benötigte Dependencies für M1 fest einbinden, insbesondere für:
+  - Log4j2
+  - Apache PDFBox
+  - SQLite JDBC
+  - OpenAI-kompatiblen HTTP-Zugriff
+  - JSON-Verarbeitung
+  - Test-Frameworks
+- benötigte Maven-Plugins konfigurieren, insbesondere:
+  - Compiler
+  - Surefire
+  - Enforcer
+  - Shade im Bootstrap-Modul
+
+### Fertig wenn
+- alle POMs konsistent sind
+- keine zyklischen Modulabhängigkeiten existieren
+- das Projekt fehlerfrei baut
+
+---
+
+## AP-003 Hexagonales Grundgerüst und technischer Startpfad
+
+### Ziel
+Die Hexagonal-Architektur wird technisch sichtbar gemacht und ein minimaler Startpfad wird hergestellt.
+
+### Inhalt
+- modulbezogene Paketstruktur gemäß Architekturverantwortung anlegen
+- minimale technische Verdrahtung über folgende Schichten herstellen:
+  - Bootstrap
+  - Adapter-In CLI
+  - Application
+- kontrollierten No-Op-Startpfad ohne fachliche Verarbeitung implementieren
+- erste JavaDoc- und `package-info`-Beschreibungen für Modulverantwortung und Architekturgrenzen ergänzen
+
+### Fertig wenn
+- ein technischer Startpfad vorhanden ist
+- die Anwendung kontrolliert startet und endet
+- die Hexagonal-Struktur im Projekt klar erkennbar ist
+
+---
+
+## AP-004 Log4j2-Basiskonfiguration
+
+### Ziel
+Das Logging wird technisch sauber und reproduzierbar eingerichtet.
+
+### Inhalt
+- Log4j2-Konfiguration anlegen
+- sinnvolle Basis für Konsolen- und Dateilogging konfigurieren
+- Logging in den technischen Startpfad integrieren
+- Start- und End-Logging des Programms ergänzen
+- sicherstellen, dass keine Logging-Infrastruktur in die Domain eingebracht wird
+
+### Fertig wenn
+- beim Programmstart nachvollziehbare Logs entstehen
+- Logging über die Basiskonfiguration funktioniert
+- die Architekturgrenzen weiterhin eingehalten sind
+
+---
+
+## AP-005 Properties-Konfigurationsmodell und Konfigurationsloader
+
+### Ziel
+Die technische Startkonfiguration kann typisiert geladen werden.
+
+### Inhalt
+- typisiertes Konfigurationsmodell für die M1-relevanten Parameter anlegen
+- Laden einer `.properties`-Datei implementieren
+- Konfigurationszugriff als technische Infrastruktur platzieren
+- Vorrang einer Umgebungsvariable vor `api.key` aus der Properties-Datei umsetzen
+- Beispiel-Konfigurationsdatei für lokale Starts und Teststarts bereitstellen
+
+### Fertig wenn
+- eine gültige `.properties`-Datei sauber geladen werden kann
+- das Konfigurationsobjekt im technischen Startpfad verfügbar ist
+- die Prioritätsregel für den API-Key umgesetzt ist
+
+---
+
+## AP-006 Grundvalidierung der Startkonfiguration und kontrollierter Fehlerabbruch
+
+### Ziel
+Ungültige Startkonfigurationen werden vor jedem Verarbeitungslauf sauber abgefangen.
+
+### Inhalt
+- Pflichtparameter der Startkonfiguration validieren
+- technische Grundvalidierung für Werte und Pfade umsetzen, soweit für M1 erforderlich
+- Fehlerbehandlung für ungültige oder unvollständige Startkonfiguration ergänzen
+- sicherstellen, dass bei ungültiger Konfiguration kein Verarbeitungslauf beginnt
+- den Fehlerfall kontrolliert protokollieren und mit Fehlerstatus beenden
+
+### Fertig wenn
+- ungültige Konfiguration den Start vor jeder fachlichen Verarbeitung beendet
+- Fehler nachvollziehbar geloggt werden
+- der Ablauf kontrolliert fehlschlägt
+
+---
+
+## AP-007 Unit-Tests für Konfigurationsladen und Grundvalidierung
+
+### Ziel
+Die zentralen M1-Bausteine werden automatisiert abgesichert.
+
+### Inhalt
+- Tests für gültiges Konfigurationsladen implementieren
+- Tests für fehlende Pflichtparameter implementieren
+- Tests für ungültige Konfigurationswerte implementieren
+- Tests für den Vorrang der Umgebungsvariable beim API-Key implementieren
+- Tests für das Grundverhalten von Bootstrap, Loader und Validierung ergänzen, soweit innerhalb von M1 sinnvoll
+
+### Fertig wenn
+- die Test-Suite grün ist
+- Konfigurationsladen und Grundvalidierung ausreichend abgesichert sind
+
+---
+
+## AP-008 Smoke-Test des ausführbaren JARs und M1-Abschlussstand
+
+### Ziel
+Der M1-Zielzustand wird als reales, ausführbares Artefakt nachgewiesen.
+
+### Inhalt
+- ausführbares Standalone-JAR final verifizieren
+- Smoke-Test für `java -jar ...` absichern
+- prüfen, dass:
+  - das Projekt vollständig baut
+  - das ausführbare JAR startet
+  - Logging funktioniert
+  - Konfiguration geladen oder sauber validiert wird
+  - das Programm kontrolliert endet
+  - noch keine fachliche Verarbeitung stattfindet
+- den M1-Stand abschließend auf Konsistenz und Vollständigkeit prüfen
+
+### Fertig wenn
+- das ausführbare JAR erfolgreich nachweisbar startbar ist
+- der definierte M1-Zielzustand vollständig erreicht ist
+- ein fehlerfreier, übergabefähiger Stand vorliegt
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete sind inhaltlich konsistent, widerspruchsfrei und sauber auf den Meilenstein **M1** zugeschnitten. Sie decken den vollständigen technischen Zielumfang von M1 ab, ohne fachliche oder infrastrukturelle Inhalte späterer Meilensteine vorwegzunehmen.

docs/workpackages/M2 - Arbeitspakete.md

@@ -0,0 +1,198 @@
+# M2 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M2 – Hexagonaler Kern, Batch-Startfall und Startschutz**.
+
+Die Arbeitspakete sind so geschnitten, dass jedes Paket in **einem Durchgang** von einer KI umgesetzt werden kann und danach wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
+
+## Konsistenz- und Schnittregeln
+
+- Jedes Arbeitspaket liefert einen in sich geschlossenen, fehlerfreien Zwischenstand.
+- Die Reihenfolge ist verbindlich, weil jedes Paket auf dem vorherigen Stand aufbaut.
+- Der Fokus bleibt strikt auf **M2**.
+- Es erfolgt **kein Vorgriff auf spätere Meilensteine**.
+- Insbesondere sind in M2 noch **nicht** enthalten:
+  - Dateisystemscan des Quellordners
+  - PDF-Filterung oder PDF-Textauslese
+  - Fingerprint-Berechnung
+  - SQLite-Persistenz
+  - KI-Anbindung
+  - Prompt-Verarbeitung
+  - Dateinamensbildung
+  - Zielkopie
+  - fachliche Retry-Logik
+  - Verarbeitung einzelner Dokumente
+
+---
+
+## AP-001 Domain-Grundobjekte und Statusmodell
+
+### Ziel
+Der hexagonale Kern für den Batch-Lauf wird fachlich und technisch sauber vorbereitet.
+
+### Inhalt
+- minimale, für M2 erforderliche Domain-Grundobjekte anlegen
+- Statusmodell für den Batch-Kontext anlegen, insbesondere die in M2 bereits relevanten Statuswerte
+- zentrale Value Objects für den Laufkontext vorbereiten, soweit für M2 erforderlich
+- klare Abgrenzung sicherstellen: keine Infrastrukturklassen, keine Adapterdetails, keine Dateisystem- oder Lock-Implementierungen in der Domain
+- erste JavaDoc- und `package-info`-Beschreibungen für Domain-Verantwortung und Architekturgrenzen ergänzen
+
+### Fertig wenn
+- die Domain enthält die für M2 nötigen Kernobjekte und Statuswerte
+- die Typen sind frei von Infrastrukturabhängigkeiten
+- der Reactor-Build bleibt fehlerfrei
+
+---
+
+## AP-002 Zentrale Ports und Inbound-Vertrag für den Batch-Lauf
+
+### Ziel
+Die Anwendungsgrenzen des M2-Stands werden explizit und architektonisch sauber definiert.
+
+### Inhalt
+- zentralen Inbound-Port für den Batch-Startfall anlegen, insbesondere `RunBatchProcessingUseCase`
+- für M2 erforderliche Outbound-Ports definieren, insbesondere für:
+  - Run-Lock
+  - Clock bzw. Zeitbezug, soweit für Laufkontext sinnvoll
+- saubere Port-Signaturen für den Batch-Lauf modellieren
+- Rückgabemodell für den Batch-Lauf so schneiden, dass Bootstrap und CLI später Exit-Codes kontrolliert ableiten können
+- JavaDoc für Port-Zweck, Verantwortlichkeiten und erlaubte Abhängigkeitsrichtungen ergänzen
+
+### Fertig wenn
+- die Ports vollständig im Application-Kern definiert sind
+- Inbound- und Outbound-Rollen klar getrennt sind
+- noch keine technische Implementierung in Ports oder Domain eingebracht wurde
+
+---
+
+## AP-003 Lauf-ID-Konzept und Batch-Laufkontext
+
+### Ziel
+Jeder Programmlauf erhält einen konsistenten technischen Kontext, ohne bereits in fachliche Dokumentverarbeitung einzusteigen.
+
+### Inhalt
+- Lauf-ID-Konzept einführen
+- technische Repräsentation eines Batch-Laufs bzw. Laufkontexts modellieren
+- Start- und Endbezug des Laufs für M2 vorbereiten
+- Schnittstelle zwischen Use Case, CLI-Adapter und Bootstrap für Übergabe bzw. Erzeugung des Laufkontexts festlegen
+- sicherstellen, dass das Laufkonzept unabhängig von späterer PDF-Verarbeitung nutzbar bleibt
+
+### Fertig wenn
+- ein konsistenter Laufkontext vorhanden ist
+- eine Lauf-ID je Programmlauf eindeutig bereitgestellt werden kann
+- der Stand weiterhin ohne Dokumentverarbeitung buildbar und startbar ist
+
+---
+
+## AP-004 No-Op-Implementierung des Batch-Use-Cases
+
+### Ziel
+Der zentrale Batch-Startfall wird erstmals ausführbar, jedoch noch ohne echte Dokumentverarbeitung.
+
+### Inhalt
+- Application-Implementierung für den Inbound-Use-Case anlegen
+- kontrollierten No-Op-Batch-Ablauf implementieren
+- Ablaufrahmen für M2 herstellen:
+  - Batch-Lauf initialisieren
+  - Laufkontext übernehmen
+  - Startschutz einbinden
+  - sauber beenden
+- noch keine Quellordnerverarbeitung, keine PDF-Verarbeitung und keine Persistenz einführen
+- JavaDoc für Use-Case-Verantwortung und explizite Nicht-Ziele von M2 ergänzen
+
+### Fertig wenn
+- der Batch-Use-Case technisch aufrufbar ist
+- der Ablauf kontrolliert startet und kontrolliert endet
+- noch keine fachliche Dokumentverarbeitung stattfindet
+
+---
+
+## AP-005 CLI-/Batch-Adapter und Bootstrap-Verdrahtung
+
+### Ziel
+Der Batch-Lauf wird über einen klaren Inbound-Adapter gestartet und sauber aus dem Bootstrap verdrahtet.
+
+### Inhalt
+- CLI-/Batch-Adapter für den Programmeinstieg implementieren
+- Adapter so anbinden, dass der Inbound-Use-Case ausschließlich über seine Schnittstelle aufgerufen wird
+- Bootstrap-Verdrahtung für M2 vervollständigen
+- Objektgraph für den M2-Stand ohne Framework-Magie und ohne Architekturbruch aufbauen
+- Startpfad so strukturieren, dass spätere Meilensteine anschlussfähig bleiben
+- JavaDoc und `package-info` für Adapter-In, Bootstrap und Verantwortungsgrenzen ergänzen
+
+### Fertig wenn
+- das Programm als Batch-Prozess über den CLI-Adapter startet
+- der Inbound-Use-Case aus dem Bootstrap korrekt erreicht wird
+- die Abhängigkeitsrichtung technisch sichtbar nach innen zeigt
+
+---
+
+## AP-006 Run-Lock-Port und Dateibasiertes Startschutz-Adapter
+
+### Ziel
+Der technische Startschutz wird eingeführt, damit parallele Instanzen kontrolliert verhindert werden.
+
+### Inhalt
+- Run-Lock-Port konkret für M2 ausmodellieren, falls noch nicht vollständig geschehen
+- erste technische Run-Lock-Implementierung im Adapter-Out anlegen
+- exklusive Lock-Datei als technische Umsetzung einführen
+- Lock-Erwerb, Lock-Freigabe und sauberes Ressourcenhandling umsetzen
+- Verhalten für bereits laufende Instanz definieren und in den Batch-Ablauf integrieren
+- sicherstellen, dass keine Lock-Implementierungsdetails in Domain oder Application durchsickern
+- JavaDoc für Startschutz, Lock-Lebensdauer und technische Grenzen ergänzen
+
+### Fertig wenn
+- eine Instanz den Lock korrekt setzt und wieder freigibt
+- eine zweite parallele Instanz kontrolliert sofort beendet wird
+- der Build und der normale Einzelstart weiterhin fehlerfrei funktionieren
+
+---
+
+## AP-007 Exit-Code-Grundverhalten und kontrollierte Laufbeendigung
+
+### Ziel
+Der M2-Stand beendet sich in allen bereits relevanten Start- und Startschutzsituationen kontrolliert und technisch eindeutig.
+
+### Inhalt
+- Exit-Code-Grundverhalten für M2 umsetzen:
+  - `0` für technisch ordnungsgemäß ausgeführten Lauf
+  - `1` für harte Start-/Bootstrap-Fehler
+- Startschutz-Fall sauber in die Exit-Code-Ableitung integrieren
+- kontrollierte Fehlerbehandlung zwischen Bootstrap, CLI-Adapter und Use Case vervollständigen
+- M2-relevante Start- und End-Logs schärfen
+- sicherstellen, dass die Exit-Code-Logik ohne spätere Fachlogik bereits stabil nutzbar ist
+
+### Fertig wenn
+- der M2-Stand in normalen und fehlerhaften Startsituationen kontrolliert endet
+- Exit-Codes für M2 konsistent gesetzt werden
+- der Stand weiterhin keine fachliche Dokumentverarbeitung enthält
+
+---
+
+## AP-008 Tests für Statusmodell, Startschutz, Verdrahtung und M2-Abschlussstand
+
+### Ziel
+Der vollständige M2-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen.
+
+### Inhalt
+- Unit-Tests für Domain-Grundobjekte und Statusmodell implementieren
+- Tests für Lauf-ID- und Laufkontext-Grundverhalten implementieren
+- Tests für Lock-Verhalten implementieren, insbesondere:
+  - Lock wird gesetzt
+  - Lock wird freigegeben
+  - zweite Instanz scheitert kontrolliert
+- Tests für Bootstrap- und Use-Case-Verdrahtung ergänzen, soweit in M2 sinnvoll
+- Tests für Exit-Code-Verhalten bei Startschutz- und Bootstrap-Fehlern ergänzen
+- den M2-Stand abschließend auf Konsistenz, Architekturtreue und Nicht-Vorgriff auf M3+ prüfen
+
+### Fertig wenn
+- die Test-Suite für den M2-Umfang grün ist
+- der definierte M2-Zielzustand vollständig erreicht ist
+- ein fehlerfreier, übergabefähiger Stand vorliegt
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete sind inhaltlich konsistent, widerspruchsfrei und sauber auf den Meilenstein **M2** zugeschnitten. Sie decken den vollständigen Zielumfang von **„Hexagonaler Kern, Batch-Startfall und Startschutz“** ab, ohne Inhalte späterer Meilensteine wie PDF-Verarbeitung, Persistenz, KI-Integration oder Dateinamensbildung vorwegzunehmen.