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. Logging-Basis und bestehender Log4j2-Stack

Ab M9 gilt verbindlich:

- Der GUI-Adapter nutzt denselben bestehenden Log4j2-Stack wie der headless Pfad.
- Es wird **keine** zweite Logging-Konfiguration für die GUI eingeführt.
- Logformat und Log-Pfad bleiben gegenüber dem bestehenden headless Betrieb unverändert.

### 6. 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.

### 7. Exit-Code-Semantik

Ab M9 gilt verbindlich:

- **`0`** für die normale erfolgreiche Beendigung eines headless Laufs sowie für das reguläre Beenden der GUI.
- **`1`** für 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 des bestehenden headless Laufs verändern dieses Exit-Code-Modell nicht.

### 8. 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**.

---

## 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.
- Sicherstellen, dass das GUI-Modul den vorhandenen Log4j2-Stack des Projekts ohne neue Logging-Konfiguration mitbenutzt.
- 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.
- Exit-Code-Modell für V2.0 an die bestehende V1.1-/M7-Semantik anschließen: `0` für normale erfolgreiche GUI-/headless-Beendigung, `1` für harte Start-, Bootstrap-, Konfigurations- oder Initialisierungsfehler.
- 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 ergänzen, soweit im Projekt technisch sinnvoll automatisierbar.
- 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.
- Mindestens einen technischen Test ergänzen, der das GUI-Threadingmodell belegt, z. B. den Nachweis, dass der UI-Thread während eines simulierten langen Hintergrundvorgangs nicht blockiert.
- Tests für das verbindliche Exit-Code-Modell von GUI- und headless Startpfad ergänzen, soweit im Projekt stabil automatisierbar.
- 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.