# 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.
