diff --git a/docs/workpackages/M3 - Arbeitspakete.md b/docs/workpackages/M3 - Arbeitspakete.md new file mode 100644 index 0000000..0295f8b --- /dev/null +++ b/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.