# 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. ## Zusätzliche Schnittregeln für die KI-Bearbeitung - Jedes Arbeitspaket muss so eindeutig sein, dass daraus ein **einzelner Prompt** für eine umsetzende KI abgeleitet werden kann. - Jedes Arbeitspaket beschreibt deshalb: - den **konkreten Implementierungsumfang**, - die **klaren Nicht-Ziele**, - sowie **prüfbare Fertig-Kriterien**. - Es dürfen innerhalb eines Arbeitspakets nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter und Bootstrap geändert werden. - 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**. ## Explizit nicht Bestandteil von M3 - 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 - manuelle Nachbearbeitung --- ## AP-001 M3-Kernobjekte und Outbound-Port-Verträge für Quellkandidaten und PDF-Auslese ### Ziel Die für M3 benötigten fachnahen Kernobjekte und Application-Verträge werden präzise eingeführt, ohne Infrastruktur in Domain oder Application hineinzuziehen. ### Inhalt - neue M3-relevante Kernobjekte bzw. Application-nahe Typen anlegen, insbesondere für: - Verarbeitungskandidat aus dem Quellordner, - Extraktionsergebnis eines einzelnen PDF-Dokuments, - Seitenzahl, - dokumentbezogenes M3-Verarbeitungsergebnis bzw. M3-Entscheidung. - Outbound-Ports definieren für: - Lesen der Verarbeitungskandidaten aus dem Quellordner, - Extraktion von Text und Seitenzahl aus genau einem PDF-Kandidaten. - Port-Verträge so schneiden, dass **weder `Path`/`File` noch PDFBox-Typen** in Domain oder Application durchsickern. - Rückgabemodelle so anlegen, dass spätere APs daraus sauber zwischen - technisch erfolgreich extrahiert, - fachlich nicht verarbeitbar, - und technisch fehlgeschlagen unterscheiden können. - JavaDoc und `package-info` für Verantwortlichkeiten und Architekturgrenzen ergänzen. ### Explizit nicht Teil - Dateisystem-Implementierung - PDFBox-Implementierung - fachliche Bewertung „brauchbarer Text" - Seitenlimit-Prüfung - Logging, Bootstrap oder CLI-Anpassungen ### Fertig wenn - die M3-relevanten Typen und Port-Verträge vorhanden sind, - die neuen Typen frei von Infrastrukturabhängigkeiten sind, - der Build weiterhin fehlerfrei ist. --- ## AP-002 Dateisystem-Adapter für Quellordnerzugriff und deterministische PDF-Kandidatenermittlung ### Ziel Der Batch-Lauf kann den konfigurierten Quellordner lesen und daraus genau die PDFs als Verarbeitungskandidaten bereitstellen, die in M3 berücksichtigt werden dürfen. ### Inhalt - Dateisystem-Adapter für den Quellordnerzugriff implementieren. - Kandidatenermittlung so umsetzen, dass **PDF-Dateien im Quellordner** als Verarbeitungskandidaten geliefert werden. - explizit sicherstellen: - **Nicht-PDF-Dateien** sind keine Kandidaten, - Verzeichnisse sind keine Kandidaten, - eine zusätzliche Rekursion in Unterordnern ist **nicht** Bestandteil von M3. - die Kandidaten in **deterministischer, stabiler Reihenfolge** an die Application liefern. - technische Fehler beim Zugriff auf einzelne Dateisystemobjekte oder beim Lesen des Quellordners kontrolliert in den Port-Vertrag überführen. - JavaDoc für Quellordnerzugriff, Kandidatenbegriff und technische Grenzen ergänzen. ### Explizit nicht Teil - PDF-Textauslese - Seitenzahlerkennung - Persistenz, Fingerprint, KI, Zielkopie - Bewertung „brauchbarer Text" - Exit-Code-Logik ### Fertig wenn - der Quellordner technisch ausgelesen werden kann, - nur zulässige PDF-Kandidaten über den definierten Port verfügbar sind, - die Kandidatenreihenfolge deterministisch ist, - der Stand fehlerfrei buildbar bleibt. --- ## AP-003 PDFBox-Adapter für Textauslese, Seitenzahlerkennung und technische Extraktionsfehler ### Ziel Für genau einen Verarbeitungskandidaten können Textinhalt und Seitenzahl technisch extrahiert werden; technische Extraktionsprobleme werden dabei kontrolliert abgebildet. ### Inhalt - PDFBox-basierten Adapter für die Auslese eines einzelnen PDF-Kandidaten implementieren. - Extraktion von - vollständigem Textinhalt im M3-Sinne, - sowie Seitenzahl in einem konsistenten Rückgabemodell bereitstellen. - technische Extraktionsprobleme kontrolliert in den Port-Vertrag überführen, insbesondere für Fälle wie: - PDF kann nicht gelesen werden, - PDF ist defekt oder unbrauchbar, - sonstige technische Fehler während der Auslese. - sicherstellen, dass PDFBox ausschließlich im Adapter-Out verbleibt. - JavaDoc für PDF-Auslese, Seitenzahl und technisches Fehlerverhalten ergänzen. ### Explizit nicht Teil - fachliche Bewertung des extrahierten Texts - Seitenlimit-Prüfung - Batch-Orchestrierung - Logging-Strategie auf Laufebene - Bootstrap- und CLI-Anpassungen ### Fertig wenn - Text und Seitenzahl für ein PDF technisch extrahierbar sind, - technische Extraktionsfehler kontrolliert als Adapter-Ergebnis vorliegen, - PDFBox ausschließlich im Adapter-Out verankert ist, - der Build weiterhin fehlerfrei ist. --- ## AP-004 Konfigurierbares Seitenlimit und deterministische Bewertung „brauchbarer Text“ ### Ziel Die M3-Vorprüfungen werden fachnah und beobachtbar modelliert, sodass jedes Dokument nach der Extraktion eindeutig bewertet werden kann. ### Inhalt - M3-relevante Konfigurationswerte vervollständigen, insbesondere das **konfigurierbare Seitenlimit**. - fachliche Bewertungslogik für **„brauchbaren Text“** im Kern umsetzen. - für M3 den Begriff **deterministisch** schneiden: - nach Normalisierung des extrahierten Texts bleibt **mindestens ein Buchstabe oder eine Ziffer** erhalten, - reiner Leerraum bzw. nur bedeutungslose Restzeichen gelten **nicht** als brauchbarer Text. - Prüfung auf **Seitenlimitüberschreitung** umsetzen. - das Ergebnis so modellieren, dass die Application pro Dokument eindeutig unterscheiden kann zwischen: - M3-Vorprüfung bestanden, - deterministischem Inhaltsfehler „kein brauchbarer Text", - deterministischem Inhaltsfehler „Seitenlimit überschritten“. - festlegen und technisch absichern, dass bei diesen beiden Inhaltsfehlern die Verarbeitung **dieses Dokuments** in M3 endet. - JavaDoc für Bewertungsregeln, Grenzen und Nicht-Ziele von M3 ergänzen. ### Explizit nicht Teil - technische PDF-Auslese - Batch-Schleife über alle Kandidaten - Persistenz- oder Retry-Logik - KI-Schnittstelle oder KI-Aufruf - Dateinamensbildung oder Zielkopie ### Fertig wenn - brauchbarer Text und Seitenlimit technisch bewertbar sind, - die beiden deterministischen Inhaltsfehler sauber erkannt werden, - die Bewertungsregeln eindeutig und testbar dokumentiert sind, - der Stand weiterhin ohne KI und Persistenz buildbar ist. --- ## AP-005 Integration in den Batch-Use-Case: Scannen, Extrahieren, Vorprüfen und kontrolliertes Ende pro Dokument ### Ziel Der M2-No-Op-Batch-Lauf wird zu einem echten M3-Verarbeitungslauf erweitert, jedoch weiterhin ohne KI, ohne Persistenz 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, - pro Kandidat ein eindeutiges M3-Verarbeitungsergebnis erzeugt. - sicherstellen, dass ein Dokument nach bestandener M3-Vorprüfung **kontrolliert endet**, ohne bereits M4+-Funktionalität anzustoßen. - sicherstellen, dass Dokumente mit den Inhaltsfehlern - „kein brauchbarer Text“ und - „Seitenlimit überschritten“ ebenfalls **pro Dokument kontrolliert enden**. - ersten durchgängigen Metadatenfluss für einzelne Dokumente zwischen Adapter-In, Application und Adapter-Out herstellen. - keinerlei künstliche Vorab-Schnittstelle für KI einführen, nur um M3 abzuschließen. - JavaDoc für Ablaufgrenzen und den M3-Verarbeitungsrahmen ergänzen. ### Explizit nicht Teil - Persistenz - Fingerprints - KI-Aufrufe - Dateinamensbildung - Zielkopie - laufübergreifende Retry-Entscheidungen ### Fertig wenn - der Batch-Lauf den Quellordner tatsächlich verarbeitet, - pro PDF ein kontrollierter M3-Ablauf stattfindet, - auch der M3-Happy-Path ohne KI und ohne Ergebnisdatei sauber endet, - noch keine Funktionalität aus M4+ vorweggenommen wurde. --- ## AP-006 Dokumentbezogene Fehlerklassifikation und M3-Logging ### Ziel Die in M3 bereits relevanten dokumentbezogenen Ergebnisse und Fehlerfälle werden eindeutig klassifiziert und nachvollziehbar protokolliert. ### Inhalt - folgende dokumentbezogenen M3-Fälle sauber unterscheiden und abbilden: - Vorprüfung bestanden, - deterministischer Inhaltsfehler „kein brauchbarer Text", - deterministischer Inhaltsfehler „Seitenlimit überschritten", - technischer Dokumentfehler bei Kandidatenzugriff oder PDF-Extraktion. - Logging für folgende Punkte schärfen: - Kandidat erkannt, - Extraktion erfolgreich oder technisch fehlgeschlagen, - Vorprüfung bestanden oder mit konkretem Grund beendet. - sicherstellen, dass **dokumentbezogene** Fehler den gesamten Lauf nicht unnötig abbrechen. - sicherstellen, dass aus dokumentbezogenen M3-Fehlern keine Folgefunktionalität späterer Meilensteine ausgelöst wird. - dokumentbezogene technische Fehler ausdrücklich **nicht** als deterministische Inhaltsfehler modellieren. - JavaDoc für Fehlersemantik und M3-spezifische Laufentscheidungen ergänzen. ### Explizit nicht Teil - Exit-Code-Neudefinition für den gesamten Prozess - Persistenz einer Historie - Retry-Logik - KI, Dateinamensbildung oder Zielkopie ### Fertig wenn - die dokumentbezogenen M3-Ergebnisse und Fehlerfälle eindeutig unterscheidbar sind, - gemischte Läufe mit erfolgreichen Vorprüfungen, Inhaltsfehlern und technischen Dokumentfehlern kontrolliert weiterlaufen, - die Logs die Dokumententscheidung nachvollziehbar machen, - weiterhin keine M4+-Funktionalität enthalten ist. --- ## AP-007 Bootstrap- und CLI-Anpassungen für M3-Konfiguration, Verdrahtung und Exit-Code-Semantik ### Ziel Der Programmeinstieg ist sauber an den M3-Lauf angepasst; M2-Startschutz und M2-Grundverhalten bleiben erhalten, werden aber für die neuen M3-Fälle präzisiert. ### Inhalt - Bootstrap-Verdrahtung auf die neuen M3-Ports, Adapter und Bewertungsbausteine erweitern. - CLI-/Batch-Startpfad auf den realen M3-Verarbeitungsablauf ausrichten. - M3-relevante Startvalidierung ergänzen, insbesondere für: - Quellordner vorhanden, - Quellordner ist lesbares Verzeichnis, - Seitenlimit ist gültig und technisch nutzbar. - Exit-Code-Semantik für M3 explizit absichern: - **Exit-Code 0**, wenn der Lauf technisch ordnungsgemäß durchgeführt wurde, auch wenn einzelne Dokumente mit M3-Inhaltsfehlern oder technischen Dokumentfehlern enden, - **Exit-Code 1** bei harten Start-, Bootstrap- oder Konfigurationsfehlern, insbesondere wenn der Lauf wegen ungültiger Startvoraussetzungen gar nicht sinnvoll beginnen kann. - sicherstellen, dass der bestehende M2-Startschutz und die kontrollierte Laufbeendigung erhalten bleiben und nicht neu erfunden werden. - JavaDoc und `package-info` für aktualisierte Verdrahtung, Konfiguration und Modulgrenzen ergänzen. ### Explizit nicht Teil - neue fachliche Dokumentverarbeitung jenseits von M3 - Persistenz- oder KI-Verdrahtung - spätere Retry- oder Idempotenzlogik ### Fertig wenn - das Programm im M3-Stand vollständig startbar ist, - die neuen Adapter korrekt verdrahtet sind, - die M3-Startvalidierung greift, - die Exit-Code-Semantik für dokumentbezogene Fehler versus harte Startfehler eindeutig umgesetzt ist, - der Build fehlerfrei bleibt. --- ## AP-008 Tests für Filterlogik, Extraktion, Vorprüfungen, M3-Happy-Path und Exit-Code-Verhalten ### Ziel Der vollständige M3-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen. ### Inhalt - Unit-Tests für die PDF-Kandidatenermittlung implementieren, insbesondere für: - PDF-Datei wird erkannt, - Nicht-PDF-Datei wird ignoriert, - Verzeichnis wird ignoriert, - Reihenfolge ist deterministisch. - Tests für PDF-Textauslese und Seitenzahlerkennung implementieren. - Tests für technische Extraktionsfehler implementieren. - Tests für die deterministische Bewertung „brauchbarer Text“ implementieren. - Tests für den Fehlerfall „Seitenlimit überschritten“ implementieren. - Tests ergänzen, die belegen, dass Dokumente mit - fehlendem brauchbarem Text, - überschrittenem Seitenlimit, - oder technischem Dokumentfehler im M3-Ablauf kontrolliert enden und den Gesamtbatch nicht unnötig abbrechen. - explizite Tests für den **M3-Happy-Path** ergänzen: gültige PDF wird erkannt, extrahiert, vorgeprüft und endet kontrolliert **ohne** KI-Aufruf und **ohne** Zielkopie. - Tests für Exit-Code-Verhalten ergänzen: - `0` bei technisch ordnungsgemäßem Lauf trotz dokumentbezogener Fehler, - `1` bei harten Start-/Bootstrap-/Konfigurationsfehlern. - Tests für Bootstrap- und Use-Case-Verdrahtung ergänzen, soweit in M3 sinnvoll. - den M3-Stand abschließend auf Konsistenz, Architekturtreue und Nicht-Vorgriff auf M4+ prüfen. ### Explizit nicht Teil - Tests für KI, Persistenz, Fingerprint oder Zielkopie - Tests für spätere Retry-Logik ### Fertig wenn - die Test-Suite für den M3-Umfang grün ist, - der definierte M3-Zielzustand vollständig erreicht ist, - die wichtigsten M3-Randfälle einschließlich Happy-Path und Exit-Code-Semantik automatisiert abgesichert sind, - ein fehlerfreier, übergabefähiger Stand vorliegt. --- ## Abschlussbewertung Die Arbeitspakete sind bewusst so nachgeschärft, dass sie für eine **zweistufige KI-Bearbeitung** geeignet sind: Eine KI kann aus jedem Arbeitspaket einen präzisen Prompt ableiten, und eine zweite KI kann das jeweilige Paket anschließend ohne implizite Annahmen vollständig umsetzen. Der vollständige M3-Zielzustand aus `meilensteine.md` wird abgedeckt. Gleichzeitig bleiben die Grenzen zu M1, M2 und allen späteren Meilensteinen gewahrt.