Arbeitspakete für M3 definiert

docs/workpackages/M3 - Arbeitspakete.md

@@ -0,0 +1,203 @@
+# M3 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M3 – Dateisystemzugriff, Kandidatenermittlung und PDF-Textauslese**.
+
+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.
+
+Die Meilensteine **M1** und **M2** werden als vollständig umgesetzt vorausgesetzt.
+
+## 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 **M3**.
+- Es erfolgt **kein Vorgriff auf spätere Meilensteine**.
+- Insbesondere sind in M3 noch **nicht** enthalten:
+  - Fingerprint-Berechnung
+  - SQLite-Persistenz
+  - Idempotenzlogik über frühere Läufe
+  - KI-Anbindung
+  - Prompt-Laden oder Prompt-Verarbeitung
+  - Validierung von KI-Antworten
+  - Dateinamensbildung
+  - Zielkopie in den Zielordner
+  - laufübergreifende Retry-Logik
+
+---
+
+## AP-001 Dateikandidat-Modell und Ports für Quellzugriff und PDF-Auslese
+
+### Ziel
+Die für M3 nötigen fachnahen Kernobjekte sowie die neuen Outbound-Ports werden architekturtreu eingeführt.
+
+### Inhalt
+- minimale Domain- bzw. Application-Typen für den M3-Kontext anlegen, insbesondere für:
+  - Quelldokument bzw. Verarbeitungskandidat
+  - extrahierten Dokumenttext
+  - Seitenzahl
+  - fachlich-technische Bewertung des Extraktionsergebnisses
+- Outbound-Ports für M3 definieren, insbesondere für:
+  - Quellordnerzugriff
+  - PDF-Text- und Seitenzahlextraktion
+- Port-Signaturen so schneiden, dass Dateisystem und PDFBox weiterhin ausschließlich in Adapter-Out verbleiben
+- klare Abgrenzung sicherstellen: keine Persistenz, keine KI, keine Zielkopie und keine Dateinamensbildung in Domain oder Application
+- JavaDoc und `package-info` für neue Verantwortlichkeiten und Architekturgrenzen ergänzen
+
+### Fertig wenn
+- die M3-relevanten Kernobjekte und Ports vorhanden sind
+- die neuen Typen frei von Infrastrukturabhängigkeiten sind
+- der Build weiterhin fehlerfrei ist
+
+---
+
+## AP-002 Dateisystem-Adapter für Quellordnerzugriff und Kandidatenermittlung
+
+### Ziel
+Der Batch-Lauf kann den konfigurierten Quellordner technisch lesen und daraus PDF-Verarbeitungskandidaten bestimmen.
+
+### Inhalt
+- Dateisystem-Adapter für den Quellordnerzugriff implementieren
+- Kandidatenermittlung für PDF-Dateien gemäß fachlicher Regel umsetzen, dass PDFs im Quellordner Verarbeitungskandidaten sind
+- die gelieferten Kandidaten in einer stabilen, für die Application nutzbaren Form bereitstellen
+- technische Fehler beim Quellordnerzugriff kontrolliert in den Portvertrag überführen
+- sicherstellen, dass noch keine Fingerprint-, Persistenz- oder KI-Logik in den Adapter einfließt
+- JavaDoc für Quellordnerzugriff, Kandidatenermittlung und technische Grenzen ergänzen
+
+### Fertig wenn
+- der Quellordner technisch ausgelesen werden kann
+- PDF-Verarbeitungskandidaten über den definierten Port verfügbar sind
+- der Stand ohne weitere M3-Funktionalität fehlerfrei buildbar bleibt
+
+---
+
+## AP-003 PDFBox-Adapter für Textauslese und Seitenzahl
+
+### Ziel
+Für einen einzelnen Verarbeitungskandidaten können Textinhalt und Seitenzahl technisch extrahiert werden.
+
+### Inhalt
+- PDFBox-basierten Adapter für die PDF-Auslese implementieren
+- Extraktion von Text und Seitenzahl in einem konsistenten Rückgabemodell bereitstellen
+- technische Fehlerfälle aus PDF-Verarbeitung kontrolliert behandeln
+- keine fachliche Benennungslogik, keine KI-Vorbereitung und keine Persistenz in den Adapter aufnehmen
+- sicherstellen, dass der Adapter nur über den definierten Outbound-Port genutzt wird
+- JavaDoc für PDF-Auslese, Seitenzahl und Fehlerverhalten ergänzen
+
+### Fertig wenn
+- Text und Seitenzahl für ein PDF technisch extrahierbar sind
+- PDFBox ausschließlich im Adapter-Out verankert ist
+- der Build weiterhin fehlerfrei bleibt
+
+---
+
+## AP-004 Konfigurierbares Seitenlimit und Bewertung „brauchbarer Text“
+
+### Ziel
+Die M3-relevanten Inhaltsvorprüfungen werden fachlich-technisch sauber im Kern modelliert.
+
+### Inhalt
+- M3-relevante Konfigurationswerte vervollständigen, insbesondere das Seitenlimit, soweit im bisherigen Stand noch nicht vollständig nutzbar
+- Bewertungslogik für „brauchbaren Text“ im fachnahen Kern umsetzen
+- Prüfung auf Seitenlimitüberschreitung umsetzen
+- Ergebnis so modellieren, dass die Application zwischen verarbeitbaren und nicht verarbeitbaren Kandidaten unterscheiden kann
+- festlegen und technisch absichern, dass bei fehlendem brauchbarem Text oder überschrittenem Seitenlimit die Verarbeitung dieses Dokuments an dieser Stelle endet
+- keine KI-Schnittstelle und keine spätere Retry-/Persistenzlogik vorwegnehmen
+- JavaDoc für Bewertungsregeln, Grenzen und Nicht-Ziele von M3 ergänzen
+
+### Fertig wenn
+- brauchbarer Text und Seitenlimit technisch bewertbar sind
+- nicht verarbeitbare PDFs sauber erkannt werden
+- der Stand weiterhin ohne KI und Persistenz buildbar und startbar ist
+
+---
+
+## AP-005 Integration in den Batch-Use-Case: Scannen, Extrahieren, Vorprüfen
+
+### Ziel
+Der M2-No-Op-Batch-Lauf wird zu einem echten M3-Verarbeitungslauf erweitert, jedoch noch ohne KI und ohne Ergebnisdatei.
+
+### Inhalt
+- bestehenden Batch-Use-Case so erweitern, dass er:
+  - den Quellordner scannt
+  - PDF-Kandidaten lädt
+  - pro Kandidat Text und Seitenzahl extrahiert
+  - die M3-Vorprüfungen ausführt
+- ersten Metadatenfluss für einzelne Dokumente zwischen Adapter-In, Application und Adapter-Out herstellen
+- verarbeitbare und nicht verarbeitbare Kandidaten im Ablauf sauber unterscheiden
+- sicherstellen, dass der Lauf trotz fehlender Folge-Meilensteine kontrolliert endet
+- keine Persistenz, keine Fingerprints, keine KI-Aufrufe und keine Zielkopie einführen
+- JavaDoc für Ablaufgrenzen und den M3-Verarbeitungsrahmen ergänzen
+
+### Fertig wenn
+- der Batch-Lauf den Quellordner tatsächlich verarbeitet
+- pro PDF ein kontrollierter M3-Ablauf stattfindet
+- noch keine Funktionalität aus M4+ vorweggenommen wurde
+
+---
+
+## AP-006 Fehlerklassifikation im M3-Lauf und kontrolliertes Logging
+
+### Ziel
+Die in M3 bereits fachlich relevanten Fehlerfälle werden im Lauf sauber eingeordnet und nachvollziehbar protokolliert.
+
+### Inhalt
+- Fehlerfall „kein brauchbarer Text“ als deterministischen Inhaltsfehler im M3-Kontext abbilden
+- Fehlerfall „Seitenlimit überschritten“ als deterministischen Inhaltsfehler im M3-Kontext abbilden
+- Logging für Kandidatenerkennung, Extraktionsergebnis und Vorprüfungsentscheidungen schärfen
+- sicherstellen, dass diese Fälle pro Dokument kontrolliert behandelt werden und den gesamten Lauf nicht unnötig abbrechen
+- sicherstellen, dass aus diesen Fällen heraus keine Folgefunktionalität späterer Meilensteine angestoßen wird
+- JavaDoc für Fehlersemantik und M3-spezifische Laufentscheidungen ergänzen
+
+### Fertig wenn
+- die M3-Fehlerfälle nachvollziehbar behandelt und geloggt werden
+- der Batch-Lauf bei gemischten Kandidaten kontrolliert weiterlaufen kann
+- weiterhin keine KI-Anbindung oder Persistenz enthalten ist
+
+---
+
+## AP-007 Bootstrap- und CLI-Anpassungen für den M3-Stand
+
+### Ziel
+Der Programmeinstieg ist an den erweiterten M3-Lauf angepasst und der Gesamtstand bleibt als Batch-Anwendung sauber ausführbar.
+
+### Inhalt
+- Bootstrap-Verdrahtung auf die neuen M3-Ports und Adapter erweitern
+- CLI-/Batch-Startpfad auf den M3-Verarbeitungsablauf ausrichten
+- Konfigurationsvalidierung für M3-relevante Parameter im Startpfad ergänzen, soweit für Quellordnerzugriff und Seitenlimit erforderlich
+- sicherstellen, dass Startschutz, Exit-Code-Grundverhalten und kontrollierte Laufbeendigung aus M2 intakt bleiben
+- Smoke-Verhalten des Programms für den M3-Stand nachvollziehbar halten
+- JavaDoc und `package-info` für aktualisierte Verdrahtung und Modulgrenzen ergänzen
+
+### Fertig wenn
+- das Programm im M3-Stand vollständig startbar ist
+- die neuen Adapter korrekt verdrahtet sind
+- der Batch-Lauf kontrolliert endet und der Build fehlerfrei bleibt
+
+---
+
+## AP-008 Tests für Kandidatenermittlung, PDF-Auslese, Vorprüfungen und M3-Abschlussstand
+
+### Ziel
+Der vollständige M3-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen.
+
+### Inhalt
+- Unit-Tests für die Kandidatenermittlung von PDF-Dateien implementieren
+- Tests für PDF-Textauslese und Seitenzahlerkennung implementieren
+- Tests für die Bewertung „brauchbarer Text“ implementieren
+- Tests für den Fehlerfall „Seitenlimit überschritten“ implementieren
+- Tests ergänzen, die belegen, dass Dokumente mit fehlendem brauchbarem Text oder überschrittenem Seitenlimit im M3-Ablauf kontrolliert enden und keine Folgefunktionalität späterer Meilensteine auslösen
+- Tests für Batch-Use-Case-Integration und Bootstrap-Verdrahtung ergänzen, soweit in M3 sinnvoll
+- den M3-Stand abschließend auf Konsistenz, Architekturtreue und Nicht-Vorgriff auf M4+ prüfen
+
+### Fertig wenn
+- die Test-Suite für den M3-Umfang grün ist
+- der definierte M3-Zielzustand vollständig erreicht ist
+- ein fehlerfreier, übergabefähiger Stand vorliegt
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete sind inhaltlich konsistent, widerspruchsfrei und sauber auf den Meilenstein **M3** zugeschnitten. Sie decken den vollständigen Zielumfang von **„Dateisystemzugriff, Kandidatenermittlung und PDF-Textauslese“** ab, ohne Inhalte späterer Meilensteine wie Fingerprint, Persistenz, KI-Integration, Dateinamensbildung oder Zielkopie vorwegzunehmen.