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.