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

# M9 - Arbeitspakete

## Geltungsbereich

Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M9 – GUI-Grundgerüst, neues Betriebsmodell und Packaging-Basis**.

Die Meilensteine **M1** bis **M8** sowie der dokumentierte Ist-Stand **V1.1** werden als vollständig umgesetzt und freigegeben vorausgesetzt.

Die Arbeitspakete sind bewusst so geschnitten, dass:

- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.

Die Reihenfolge der Arbeitspakete ist verbindlich.

## Zusätzliche Schnittregeln für die KI-Bearbeitung

- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter, Bootstrap, Build und Tests ändern.
- Keine Annahmen treffen, die nicht durch die bestehenden Spezifikationen, den dokumentierten V1.1-Ist-Stand oder dieses Dokument gedeckt sind.
- Kein Vorgriff auf **M10+**.
- Kein Umbau bestehender M1–M8-Strukturen ohne direkten M9-Bezug.
- Die neue GUI wird als **eigener Inbound-Adapter** umgesetzt und **nicht** in Bootstrap vermischt.
- Der bestehende **headless Batch-Betrieb** darf weder technisch noch verhaltensseitig still gebrochen werden.
- Änderungen klein, fokussiert und architekturtreu halten.
- Neue Typen, CLI-Optionen, Startpfade, Packaging-Anpassungen und Tests so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus klar benennbar, testbar und reviewbar sind.
- Ein Arbeitspaket darf nur dann auf GUI-Verhalten aufbauen, wenn das technische Startfundament im unmittelbar vorhergehenden Arbeitspaket bereits hergestellt wurde.

## Explizit nicht Bestandteil von M9

- GUI-Konfigurationseditor
- Willkommenstext und vollständige GUI-Benutzerführung aus M10
- Öffnen/Speichern/Speichern unter in der GUI
- Bearbeitung der `.properties`-Inhalte in der GUI
- Datei-/Ordnerdialoge
- Provider-ComboBox, Modellabruf oder Modellfeldlogik
- sofortige Validierung im Editor
- zentraler Meldungsbereich und feldnahe Fehlermeldungen
- technische Tests und Korrekturhilfen in der GUI
- automatische Prompt-Erzeugung
- DB-/Historienanzeige
- manueller Verarbeitungslauf aus der GUI
- EXE
- Installer
- offizieller plattformübergreifender GUI-Support
- neues Konfigurationsformat
- Änderungen an fachlicher Benennungslogik, Statussemantik, Retry-Regeln oder Persistenz-Wahrheiten

## Verbindliche M9-Regeln für **alle** Arbeitspakete

### 1. Betriebsmodell

Ab M9 gilt verbindlich:

- **GUI ist der neue Standardstart**.
- Über **`--headless`** startet weiterhin der bestehende Batch-/Scheduler-Betrieb.
- Die Anwendung bleibt **ein einziges ausführbares JAR**.
- Es gibt in M9 **keine EXE** und **keinen Installer**.

### 2. CLI-Option `--config <pfad>`

Ab M9 gilt verbindlich:

- **`--config <pfad>`** steht für **GUI und headless** zur Verfügung.
- Wird **headless ohne `--config`** gestartet, bleibt das bisherige Default-Verhalten der Konfigurationsauflösung erhalten.
- Zeigt **`--config <pfad>` im GUI-Start** auf eine nicht existente Datei:
  - erscheint eine klare Fehlermeldung,
  - danach verhält sich die GUI so, als wäre `--config` nicht angegeben worden.
- Zeigt **`--config <pfad>` im headless Start** auf eine nicht existente Datei, ist das ein **harter Startfehler**; ein stiller Fallback auf das Default-Verhalten ist in diesem Fall unzulässig.

### 3. Modul- und Architekturregel

Ab M9 gilt verbindlich:

- Die Modulstruktur wird um **genau ein neues Modul** erweitert:
  - `pdf-umbenenner-adapter-in-gui`
- Die GUI ist ein **Inbound-Adapter**.
- **Bootstrap** bleibt verantwortlich für:
  - Startmoduswahl,
  - Konfigurationsauflösung,
  - Objektgraph,
  - kontrollierten Start des passenden Adapters,
  - Exit-Code-Ableitung bei harten Startfehlern.
- Domain und Application bleiben frei von JavaFX-Typen.

### 4. JavaFX- und Headless-Isolation

Ab M9 gilt verbindlich:

- JavaFX wird für den GUI-Betrieb **mit dem ausführbaren JAR ausgeliefert**.
- Der **headless Start** darf **keine externe JavaFX-Installation** voraussetzen.
- GUI-Code und JavaFX dürfen im **headless Pfad** nicht unnötig früh initialisiert oder geladen werden.
- Fehlen GUI-Voraussetzungen beim tatsächlichen GUI-Start, ist das ein **kontrollierter GUI-Startfehler** mit klarer Rückmeldung.

### 5. Plattformziel

Ab M9 gilt verbindlich:

- Die GUI wird offiziell nur für **Windows** vorgesehen.
- Der headless Betrieb bleibt für **Windows Server / Task Scheduler** kompatibel.
- M9 führt noch keine GUI-Funktionalität ein, die gemappte Laufwerke oder Datei-Dialoge fachlich ausreizt; die technische Grundlage darf dem späteren Windows-zentrierten Pfadverhalten jedoch nicht widersprechen.

### 6. GUI-Zielstand innerhalb von M9

M9 liefert **kein** vollständiges GUI-Produkt, sondern nur ein **technisch lauffähiges Grundgerüst**.

Daraus folgt:

- Es ist eine **minimale JavaFX-GUI-Shell** zulässig und zweckmäßig.
- Diese Shell dient nur dem Nachweis des GUI-Startpfads.
- Ein echter Konfigurationseditor ist ausdrücklich erst Gegenstand von **M10**.

### 7. GUI-Threadingmodell

Ab M9 gilt verbindlich für alle V2.0-Meilensteine:

- Jede potenziell blockierende Operation der GUI – insbesondere providerseitiger Modellabruf, providerseitige technische Tests, Pfad- und Dateisystemprüfungen, SQLite-Prüfungen sowie das Lesen und Schreiben der `.properties`-Datei – läuft auf einem **Hintergrund-Worker-Thread**.
- **UI-Updates erfolgen ausschließlich über den JavaFX Application Thread** (`Platform.runLater`).
- Die GUI darf während laufender Hintergrund-Operationen **nicht einfrieren**.
- Diese Regel ist Referenz für alle threadingbezogenen Formulierungen in M9–M13; Wiederholungen sind in einzelnen Meilensteinen nicht erforderlich.

### 8. Exit-Codes

Ab M9 gilt verbindlich für alle V2.0-Meilensteine:

- **Exit-Code `0`**: normale erfolgreiche Beendigung eines headless Laufs sowie für das reguläre Beenden der GUI.
- **Exit-Code `1`**: harte Start-, Bootstrap-, Verdrahtungs-, Konfigurations- oder Initialisierungsfehler, einschließlich ungültiger CLI-Verwendung, nicht existenter `--config`-Datei im headless Start und GUI-Startfehlern vor erfolgreicher Anzeige der Oberfläche.
- Dokumentbezogene Verarbeitungsfehler im headless Lauf ändern dieses Exit-Code-Modell nicht; sie bleiben Teil des fachlichen Laufresultats wie bereits in V1.1.

### 9. GUI-Logging

Ab M9 gilt verbindlich:

- Der GUI-Adapter nutzt denselben Log4j2-Stack wie der headless Pfad.
- Logformat und Log-Verzeichnis bleiben gegenüber dem headless Betrieb unverändert.
- Mindesteintrag für GUI-nahe Ereignisse sind: Start- und Beendigungsereignisse der GUI, Modellabruf-Versuche (Provider, Erfolg/Misserfolg, **ohne API-Key**), Dateischreibvorgänge inkl. Zielpfad, Ergebnisse der Aktionen `Validieren` und `Technische Tests ausführen`, sowie alle schreibenden Korrekturen.

### 10. GUI-Teststrategie

Ab M9 gilt verbindlich für alle V2.0-Meilensteine:

- **View-Modelle und Application-nahe GUI-Logik** werden mit JUnit unit-getestet. Testfokus liegt auf Zustandsübergängen, Validierungsregeln und Datenflüssen, nicht auf Rendering.
- **GUI-Smoke-Tests** laufen unter **headless JavaFX (Monocle)** in der Maven-Test-Phase. Sie prüfen, dass zentrale GUI-Pfade (Start, Laden, grundlegende Interaktionen) technisch durchlaufen, ohne einen sichtbaren Desktop vorauszusetzen.
- Es wird **kein TestFX** und **kein weiteres GUI-Testframework** über Monocle hinaus eingeführt.
- Diese Teststrategie gilt als Referenz für alle testbezogenen Formulierungen in den Arbeitspaketen von M9 bis M13.

### 11. JavaDoc-Standard für V2.0

Ab M9 gilt verbindlich für alle V2.0-Meilensteine:

Für jede **neu hinzugefügte** oder **substanziell geänderte** öffentliche Klasse, öffentliche Methode und jedes neue Java-Package gilt:

- **Klassen-JavaDoc**: Zweck, Verantwortung und Abgrenzung der Klasse.
- **Methoden-JavaDoc**: Zweck, Parameter, Rückgabewert und dokumentierte Ausnahmen.
- **`package-info.java`**: pro neuem Package, mit Kurzbeschreibung der Paketverantwortung.

Dieser Standard gilt als Bestandteil jedes „Fertig wenn"-Abschnitts in V2.0. Ein Arbeitspaket ist erst dann fertig, wenn die betroffenen öffentlichen Klassen und Methoden dem JavaDoc-Standard entsprechen.

---

## AP-001 Neues GUI-Modul und Maven-/Reactor-Basis einführen

### Voraussetzung
Keine. Dieses Arbeitspaket ist der M9-Startpunkt.

### Ziel
Die Projektstruktur wird um ein eigenständiges GUI-Modul erweitert, ohne die bestehende Architektur oder den bisherigen headless Stand zu beschädigen.

### Muss umgesetzt werden
- Neues Modul **`pdf-umbenenner-adapter-in-gui`** anlegen.
- Modul korrekt in Parent-POM und Reactor aufnehmen.
- Abhängigkeiten so schneiden, dass das GUI-Modul als **Inbound-Adapter** auf die bestehenden inneren Schichten aufsetzen kann.
- JavaFX-Grundabhängigkeiten nur dort einführen, wo sie für das GUI-Modul technisch erforderlich sind.
- Sicherstellen, dass Domain, Application, Adapter-Out und CLI-Adapter frei von JavaFX-Abhängigkeiten bleiben.
- Erste neutrale Paket- und Klassenstruktur im neuen Modul anlegen, soweit für einen buildbaren Stand nötig.
- JavaDoc und `package-info` für die neue Modulverantwortung ergänzen.

### Explizit nicht Teil
- tatsächlicher GUI-Start
- CLI-Parsing für neue Optionen
- Bootstrap-Anpassungen
- Packaging des gemeinsamen JARs
- GUI-Inhalt jenseits einer neutralen Modulbasis

### Fertig wenn
- das neue GUI-Modul im Reactor vorhanden ist,
- die Abhängigkeitsrichtung architekturtreu bleibt,
- der Gesamtbuild weiterhin fehlerfrei ist,
- noch kein M10+-Verhalten vorweggenommen wurde.

---

## AP-002 Startmodus- und CLI-Optionsmodell für GUI, `--headless` und `--config` einführen

### Voraussetzung
AP-001 ist abgeschlossen.

### Ziel
Die Anwendung kann Startmodus und Konfigurationspfad formal eindeutig interpretieren, ohne den bestehenden headless Betrieb zu verlieren.

### Muss umgesetzt werden
- Technisches Modell für die Startmodi einführen:
  - GUI-Standardstart,
  - expliziter `--headless`-Start.
- Neue CLI-Option **`--config <pfad>`** für beide Startarten einführen.
- Parsing und Validierung der relevanten Optionen im Startpfad modellieren.
- Bestehendes Default-Verhalten für headless Starts **ohne** `--config` ausdrücklich erhalten.
- Klare Behandlung für fehlerhafte CLI-Verwendungen modellieren, insbesondere für:
  - `--config` ohne Wert,
  - unbekannte oder widersprüchliche Startparameter, soweit für M9 erforderlich.
- Rückgabemodell so schneiden, dass Bootstrap daraus kontrolliert GUI-Start, headless Start oder harten Startfehler ableiten kann.
- JavaDoc für Startmodussemantik und Konfigurationspfadbezug ergänzen.

### Explizit nicht Teil
- tatsächliches Laden einer GUI-Oberfläche
- konkrete Behandlung nicht existenter Konfigurationsdateien im fertigen Startfluss
- Packaging
- GUI-Benutzerführung

### Fertig wenn
- Startmodus und Konfigurationspfad technisch eindeutig interpretierbar sind,
- headless ohne `--config` weiterhin anschlussfähig bleibt,
- der Build weiterhin fehlerfrei ist.

---

## AP-003 Bootstrap-Verdrahtung für zwei Startpfade und kontrollierte Fehlerableitung erweitern

### Voraussetzung
AP-001 und AP-002 sind abgeschlossen.

### Ziel
Bootstrap kann zwischen GUI und headless sauber umschalten, ohne seine Verantwortung zu überschreiten.

### Muss umgesetzt werden
- Bootstrap so erweitern, dass es abhängig vom geparsten Startmodus den passenden Inbound-Adapter startet.
- Sicherstellen, dass der bestehende headless Pfad fachlich und technisch erhalten bleibt.
- Kontrollierte Fehlerableitung für harte Startfehler ergänzen, soweit M9 dies bereits erfordert.
- Behandlung des Konfigurationspfadbezugs im Bootstrap vervollständigen.
- Sicherstellen, dass Bootstrap keine GUI-Fachlogik oder M10-Editorlogik aufnimmt.
- JavaDoc und `package-info` für aktualisierte Bootstrap-Verantwortung ergänzen.

### Explizit nicht Teil
- minimale GUI-Shell selbst
- JavaFX-Packaging
- GUI-Benutzerführung
- Dateieditor oder Validierungslogik

### Fertig wenn
- Bootstrap technisch zwischen GUI und headless umschalten kann,
- der headless Pfad weiterhin fehlerfrei und anschlussfähig bleibt,
- harte Startfehler kontrolliert ableitbar sind,
- der Build weiterhin fehlerfrei ist.

---

## AP-004 Minimale JavaFX-GUI-Shell als Standardstartpfad bereitstellen

### Voraussetzung
AP-001 bis AP-003 sind abgeschlossen.

### Ziel
Der neue Standardstartpfad führt in eine minimale, technisch saubere JavaFX-GUI-Shell, ohne bereits Editorlogik aus M10 vorzuziehen.

### Muss umgesetzt werden
- Minimale JavaFX-Einstiegsklasse im GUI-Modul implementieren.
- Neutrale GUI-Shell bereitstellen, die den erfolgreichen GUI-Start technisch sichtbar macht.
- Die GUI-Shell so schneiden, dass sie später ohne Architekturbruch zum Konfigurationseditor ausgebaut werden kann.
- Sicherstellen, dass beim tatsächlichen GUI-Start klare Rückmeldungen für GUI-bezogene Startfehler möglich sind.
- Sicherstellen, dass die GUI-Shell keine M10-Funktionalität vorwegnimmt, insbesondere:
  - kein Konfigurationseditor,
  - keine Dateioperationen,
  - keine Validierung,
  - keine Providerbedienung.
- JavaDoc für Zweck und klare Nicht-Ziele der minimalen GUI-Shell ergänzen.

### Explizit nicht Teil
- Willkommenstext im finalen V2.0-Sinne
- bearbeitbare Eingabefelder
- Buttons **Neu**, **Öffnen**, **Speichern** usw.
- Meldungsbereich
- technische Tests

### Fertig wenn
- die Anwendung im Standardstart in eine minimale GUI-Shell startet,
- die Shell technisch sauber vom headless Pfad getrennt ist,
- noch kein M10+-Verhalten implementiert wurde,
- der Build weiterhin fehlerfrei ist.

---

## AP-005 Konfigurationspfad-Semantik für GUI und headless vervollständigen

### Voraussetzung
AP-001 bis AP-004 sind abgeschlossen.

### Ziel
Das Verhalten von `--config <pfad>` ist für beide Startarten vollständig, abwärtskompatibel und kontrolliert umgesetzt.

### Muss umgesetzt werden
- Verhalten für **existierende** Konfigurationsdateien in GUI und headless vervollständigen.
- Verhalten für **nicht existente** Konfigurationsdateien explizit umsetzen:
  - GUI: Fehlermeldung, danach GUI-Start wie ohne `--config`
  - headless: harter Startfehler
- Sicherstellen, dass das bestehende Default-Verhalten für headless **ohne** `--config` unangetastet bleibt.
- Kontrollierte Rückmeldungen für problematische Konfigurationspfade ergänzen.
- Keine GUI-Editorlogik oder Dateibearbeitung einführen; es geht ausschließlich um Startsemantik.
- JavaDoc für die endgültige M9-Semantik von `--config` ergänzen.

### Explizit nicht Teil
- Bearbeiten oder Speichern der Konfiguration in der GUI
- Datei-Dialoge
- neue Konfigurationswerte
- inhaltliche Validierung der `.properties`

### Fertig wenn
- `--config` für GUI und headless kontrolliert funktioniert,
- die unterschiedlichen Fehlerpfade wie festgelegt umgesetzt sind,
- headless ohne `--config` weiterhin kompatibel bleibt,
- der Build weiterhin fehlerfrei ist.

---

## AP-006 Packaging-Basis für gemeinsames JAR mit integrierter JavaFX-Laufzeit herstellen

### Voraussetzung
AP-001 bis AP-005 sind abgeschlossen.

### Ziel
Das Projekt erzeugt weiterhin genau ein ausführbares Artefakt, das den GUI-Standardstart technisch ermöglicht und den headless Pfad nicht unnötig belastet.

### Muss umgesetzt werden
- Build-/Packaging-Konfiguration so erweitern, dass weiterhin **ein gemeinsames ausführbares JAR** entsteht.
- JavaFX-Laufzeit und erforderliche GUI-Bestandteile in das Artefakt integrieren, soweit für den Windows-GUI-Start von M9 erforderlich.
- Sicherstellen, dass der headless Startpfad keine unnötig frühe JavaFX-Initialisierung erzwingt.
- Konkret absichern, dass der headless Startpfad ohne Initialisierung der JavaFX-Application-Klasse durchlaufen kann.
- Packaging so schneiden, dass keine EXE und kein Installer eingeführt werden.
- Bestehende Artefakterzeugung aus V1.1 nicht still zerstören.
- Dokumentierende Build-Hinweise ergänzen, soweit für M9 zwingend nötig.

### Explizit nicht Teil
- vollständige Enddokumentation von V2.0
- M10-GUI-Funktionalität
- plattformübergreifendes Packaging
- EXE-/Installer-Bau

### Fertig wenn
- weiterhin genau ein ausführbares JAR erzeugt wird,
- dieses JAR den M9-GUI-Start technisch tragen kann,
- der headless Startpfad weiterhin anschlussfähig ist und ohne JavaFX-Application-Initialisierung nachweisbar bleibt,
- der Build weiterhin fehlerfrei ist.

---

## AP-007 Start-, Fehler- und Packaging-Tests für den vollständigen M9-Zielstand vervollständigen

### Voraussetzung
AP-001 bis AP-006 sind abgeschlossen.

### Ziel
Der vollständige M9-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen.

### Muss umgesetzt werden
- Tests für den GUI-Standardstart gemäß der in M9 festgelegten GUI-Teststrategie ergänzen.
- Tests für **`--headless`** ergänzen.
- Automatisierten Nachweis ergänzen, dass der headless Start ohne Initialisierung der JavaFX-Application-Klasse durchlaufen kann.
- Tests für **`--config <pfad>`** in beiden Startarten ergänzen.
- Negativtests für ungültige oder fehlende Konfigurationspfade ergänzen, insbesondere:
  - GUI mit nicht existenter Konfigurationsdatei,
  - headless mit nicht existenter Konfigurationsdatei,
  - `--config` ohne Wert.
- Tests ergänzen, die belegen, dass headless ohne `--config` weiterhin das bisherige Default-Verhalten nutzt.
- Smoke-Tests für die Artefakterzeugung und Packaging-Basis ergänzen.
- Sicherstellen, dass dokumentbezogene Batch-Funktionalität nicht versehentlich regressiert ist.
- Den M9-Stand abschließend auf Architekturtreue, Abwärtskompatibilität und Nicht-Vorgriff auf M10+ prüfen.

### Explizit nicht Teil
- GUI-Editor-Tests aus M10
- Validierungs- und Modellabruf-Tests aus M11
- technische Test- und Korrekturhilfe-Tests aus M12
- Abschlussdokumentation aus M13

### Fertig wenn
- der vollständige M9-Zielstand automatisiert abgesichert ist,
- GUI- und headless Startpfade kontrolliert nachgewiesen sind,
- das gemeinsame JAR reproduzierbar gebaut wird,
- der definierte M9-Zielzustand vollständig erreicht ist,
- ein fehlerfreier, übergabefähiger Stand vorliegt.

---

## Abschlussbewertung

Die Arbeitspakete decken den vollständigen Zielumfang von **M9 – GUI-Grundgerüst, neues Betriebsmodell und Packaging-Basis** ab:

- neues GUI-Modul als eigener Inbound-Adapter
- GUI als Standardstart
- `--headless` als erhaltener Batch-/Scheduler-Pfad
- neue CLI-Option `--config <pfad>` für beide Startarten
- kontrollierte, unterschiedliche Fehlersemantik für GUI und headless bei nicht existenter Konfigurationsdatei
- saubere Bootstrap-Umschaltung zwischen zwei Startpfaden
- minimale JavaFX-GUI-Shell als technischer Nachweis des GUI-Starts
- ein gemeinsames ausführbares JAR mit integrierter JavaFX-Basis
- Absicherung, dass headless ohne unnötige GUI-Initialisierung weiter nutzbar bleibt
- Tests für Startverhalten, Fehlerpfade und Packaging

Damit ist M9 bewusst klar von den späteren GUI-Funktionalitäten aus **M10** bis **M13** getrennt und liefert dennoch einen eigenständig lauffähigen, architekturtreuen und reviewbaren Zwischenstand.