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

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.