pdf-umbenenner/docs/workpackages/M1 - Arbeitspakete.md

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.