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.