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.

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.