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

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.