From dc2d3e8cd2930a05fdeebeb1b1faf077c9a555c2 Mon Sep 17 00:00:00 2001 From: Marcus van Elst Date: Sat, 11 Apr 2026 07:16:33 +0200 Subject: [PATCH] =?UTF-8?q?Meilensteine=20f=C3=BCr=20V2.0=20in=20der=20Pre?= =?UTF-8?q?-Version=20angelegt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/specs/meilensteine-v2_0.md | 628 +++++++++++++++++++++++ docs/workpackages/M10 - Arbeitspakete.md | 401 +++++++++++++++ docs/workpackages/M11 - Arbeitspakete.md | 407 +++++++++++++++ docs/workpackages/M12 - Arbeitspakete.md | 429 ++++++++++++++++ docs/workpackages/M13 - Arbeitspakete.md | 384 ++++++++++++++ docs/workpackages/M9 - Arbeitspakete.md | 381 ++++++++++++++ 6 files changed, 2630 insertions(+) create mode 100644 docs/specs/meilensteine-v2_0.md create mode 100644 docs/workpackages/M10 - Arbeitspakete.md create mode 100644 docs/workpackages/M11 - Arbeitspakete.md create mode 100644 docs/workpackages/M12 - Arbeitspakete.md create mode 100644 docs/workpackages/M13 - Arbeitspakete.md create mode 100644 docs/workpackages/M9 - Arbeitspakete.md diff --git a/docs/specs/meilensteine-v2_0.md b/docs/specs/meilensteine-v2_0.md new file mode 100644 index 0000000..8d0b53f --- /dev/null +++ b/docs/specs/meilensteine-v2_0.md @@ -0,0 +1,628 @@ +# Meilensteine V2.0 – JavaFX-GUI, Konfigurationskomfort und technischer Ausbau + +## Zweck dieses Dokuments + +Dieses Dokument beschreibt den geplanten Ausbau des Projekts **ab dem final freigegebenen Stand V1.1** hin zu **V2.0** sowie einen klar abgegrenzten **Ausblick auf spätere Ausbaustufen**. + +Es ergänzt die bestehenden Spezifikationsdokumente und den dokumentierten Ist-Stand V1.1 um eine neue, bewusst größere Produktstufe. V2.0 erweitert die bisher reine Batch-Anwendung um eine **lokale JavaFX-Desktop-GUI**, ohne die bestehende Architektur, das Standalone-JAR-Betriebsmodell oder den headless Scheduler-Betrieb aufzugeben. + +Das Dokument ist als Planungs- und Strukturierungsgrundlage gedacht. Es definiert **keine Arbeitspakete**, sondern die **neuen Meilensteine, Abgrenzungen und Ausbaustufen** für den nächsten Entwicklungsschritt. + +--- + +## Einordnung von V2.0 + +### Ausgangsbasis + +V1.1 ist der aktuelle, fertig implementierte und abgenommene Stand des Projekts. + +Darauf aufbauend gilt: + +- V1 ist fachlich und technisch vollständig umgesetzt. +- V1.1 erweitert V1 minimal-invasiv um native Claude-Unterstützung. +- Das bisherige Betriebsmodell bleibt ein **lokal gestartetes Standalone-JAR**. +- Der Batch-Betrieb über **Windows Task Scheduler** bleibt weiterhin erhalten. +- Die Anwendung arbeitet bisher **ohne GUI**, **ohne Webserver**, **ohne App-Server**. +- Die technische Konfiguration erfolgt weiterhin über **`.properties`**. +- Es gibt bereits **mehrere Provider-Konfigurationen**, aber immer **genau einen aktiven Provider**. + +### Warum V2.0 und nicht V1.x + +Der geplante GUI-Ausbau ist kein kleiner Nachschlag zu V1.1, sondern eine neue Produktstufe. + +V2.0 ist gerechtfertigt, weil gleichzeitig neu hinzukommen: + +- neuer Standard-Startmodus über eine Desktop-GUI +- zusätzlicher Inbound-Adapter für JavaFX +- neuer Benutzerzugang zur Konfiguration +- technische Tests und Korrekturhilfen in der GUI +- neue CLI-Option `--config ` für beide Startarten +- Windows-zentrierte Desktop-Unterstützung mit gemappten Laufwerken + +V2.0 bleibt jedoch architekturtreu und bewahrt das bisherige Kernziel der Anwendung: + +> PDFs automatisiert scannen, fachlich verarbeiten und korrekt benannte Zielkopien erzeugen. + +--- + +## Unveränderte Leitplanken auch in V2.0 + +Die folgenden Grundprinzipien bleiben in V2.0 ausdrücklich erhalten: + +- **Java 21** +- **Maven Multi-Module** +- **ausführbares Standalone-JAR** +- **kein Webserver** +- **kein Applikationsserver** +- **keine Dauerlauf-Anwendung** +- **kein interner Scheduler** +- **strikte hexagonale Architektur / Ports and Adapters** +- **Abhängigkeiten zeigen nach innen** +- **`.properties` bleibt die einzige Konfigurationswahrheit** +- **bestehender headless Batch-Betrieb bleibt erhalten** +- **genau ein aktiver Provider** +- **keine neue Persistenz-Wahrheit** +- **fachliche Kernlogik des PDF-Umbenenners bleibt unverändert** + +--- + +## Zielbild von V2.0 + +V2.0 erweitert die Anwendung um eine **lokale JavaFX-Desktop-GUI**. + +### Start- und Betriebsmodell in V2.0 + +- Die Anwendung bleibt **ein einziges ausführbares JAR**. +- **GUI ist der neue Standardstart**. +- Über `--headless` startet weiterhin der bestehende Server-/Scheduler-Betrieb. +- Über `--config ` kann sowohl der GUI- als auch der headless Start auf eine konkrete Konfigurationsdatei zeigen. +- Bestehendes headless Standardverhalten ohne `--config` bleibt aus Abwärtskompatibilitätsgründen erhalten. +- Wenn `--config ` im **headless** Start auf eine nicht existente Datei zeigt, ist dies ein **harter Startfehler**; ein stiller Fallback auf das Default-Verhalten ist in diesem Fall unzulässig. +- Wenn `--config ` im **GUI-Start** auf eine nicht existente Datei zeigt: + - erscheint eine Fehlermeldung, + - danach verhält sich die GUI so, als wäre `--config` nicht angegeben worden. + +### Plattformziel + +- V2.0-GUI wird **offiziell nur unter Windows** unterstützt. +- Der headless Betrieb bleibt für den Windows Server-Betrieb geeignet. +- **Gemappte Laufwerke** wie `S:\` oder `H:\` sind ausdrücklich zu unterstützen. +- Eine Ablehnung solcher Pfade allein wegen eines dahinterliegenden UNC-Backings ist unzulässig. + +### GUI-Threadingmodell + +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. + +### Packaging-Ziel + +- JavaFX wird **mit dem JAR ausgeliefert**. +- Es gibt in V2.0 **keine EXE**. +- Es gibt in V2.0 **keinen Installer**. +- `--headless` darf logisch weiterhin ohne GUI-Pfadzweige funktionieren; GUI-Code darf den headless Ablauf nicht unnötig früh initialisieren. + +### Modulziel in V2.0 + +Die Modulstruktur wird um **genau ein neues Modul** erweitert: + +- `pdf-umbenenner-domain` +- `pdf-umbenenner-application` +- `pdf-umbenenner-adapter-in-cli` +- `pdf-umbenenner-adapter-in-gui` +- `pdf-umbenenner-adapter-out` +- `pdf-umbenenner-bootstrap` + +Die GUI wird **nicht** im Bootstrap-Modul vermischt, sondern als eigener Inbound-Adapter umgesetzt. + +### Logging in der GUI + +Der GUI-Adapter nutzt denselben Log4j2-Stack wie der headless Pfad. Mindestens geloggt werden: 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. Das Logformat und der Log-Pfad bleiben gegenüber dem headless Betrieb unverändert. + +### Exit-Codes + +- **`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 im headless Lauf ändern dieses Exit-Code-Modell nicht; sie bleiben Teil des fachlichen Laufresultats wie bereits in V1.1. + +--- + +## V2.0-Funktionsumfang + +### 1. GUI als Konfigurations- und Diagnose-Frontend + +V2.0 führt **noch keinen manuellen Verarbeitungslauf** in der GUI ein. + +Die V2.0-GUI dient zunächst ausschließlich als: + +- Editor für die bestehende `.properties`-Konfiguration +- technische Validierungsoberfläche +- technische Test- und Diagnoseoberfläche +- komfortable Dateiauswahl- und Speichermaske + +### 2. Struktur der V2.0-GUI + +V2.0 enthält **genau einen Tab** mit einer klaren, festen Gliederung. + +Reihenfolge: + +1. **Header mit Konfigurationsdatei** +2. **Pfade** +3. **Provider** +4. **Verarbeitungslimits** +5. **Tests** +6. **Meldungen** + +Beim Start ohne geladene Konfiguration wird **kein leerer Standardentwurf** angezeigt. Stattdessen erscheint ein **deutscher Willkommenstext** mit Hinweis auf **„Neu“** und **„Öffnen“**. + +### 3. Dateiverhalten der GUI + +- Es wird **keine Konfiguration automatisch geladen**. +- Die GUI kann bestehende `.properties`-Dateien **öffnen**. +- Die GUI kann **neue Konfigurationen** anlegen. +- Eine neue Konfiguration startet mit einer **vollständigen Standardvorlage** mit sinnvollen Standardwerten. +- Beide bekannten Provider-Blöcke sind in der Datei vorhanden. +- Standardmäßig ist der **alphabetisch erste vorhandene Provider** aktiv; im aktuellen Stand ist das **Claude**. +- **Speichern** ist immer erlaubt. +- Bei einer neuen, noch nie gespeicherten Konfiguration verhält sich **„Speichern“** wie **„Speichern unter“**. +- **„Speichern unter“** schlägt standardmäßig denselben Standardpfad vor, den der bestehende headless Betrieb in V1.1 verwendet, also `config/application.properties` relativ zum Arbeitsverzeichnis. Dadurch ist die in der GUI gespeicherte Datei ohne weitere Schritte für den nächsten headless Scheduler-Lauf nutzbar. +- Bei existierender Zieldatei erscheint die Rückfrage **„Datei überschreiben?“**. +- Vor dem Überschreiben einer bestehenden `.properties`-Datei legt die GUI eine `.bak`-Sicherung im selben Schema wie der bestehende V1.1-Migrationspfad an (`.bak`, bei Kollision `.bak.1`, `.bak.2`, …). +- Datei-Dialoge filtern auf **`*.properties`**. +- Ungespeicherte Änderungen werden im **Fenstertitel** und im **Header** markiert. +- Vor **Neu**, **Öffnen** oder **Schließen** erscheint bei ungespeicherten Änderungen ein Dialog mit: + - **Speichern** + - **Verwerfen** + - **Abbrechen** + +### 4. Umgang mit der bestehenden Konfigurationsdatei + +- Die GUI liest, bearbeitet und schreibt dieselbe `.properties`-Datei wie der headless Betrieb. +- Wenn die GUI eine Datei in der Legacy-Form aus Vor-V1.1 öffnet, wendet sie dieselbe Migrationslogik wie der headless Pfad an: zuerst `.bak`-Sicherung der Originaldatei, dann Überführung in das neue Mehrprovider-Schema, dann Anzeige im Editor. Dem Benutzer wird die durchgeführte Migration sichtbar im zentralen Meldungsbereich gemeldet. +- Kommentare und Reihenfolge dürfen beim Speichern **normalisiert** werden. +- Die GUI darf **alle aktuell bekannten Konfigurationswerte** bearbeiten. +- Es wird **kein neues Konfigurationsformat** eingeführt. + +### 5. Provider-Bereich in V2.0 + +- Es gibt eine **Provider-ComboBox**. +- Sichtbar ist immer nur der **aktuell ausgewählte Provider-Bereich**. +- Ein Provider-Wechsel löscht die Daten des anderen Providers **nicht**. +- Die GUI muss also mit der bestehenden Mehrprovider-Dateistruktur kompatibel bleiben. +- Sichtbare Providerbezeichnungen können zunächst pragmatisch sein, z. B.: + - **Claude** + - **OpenAI-kompatibel** + +### 6. Modellwahl in V2.0 + +- Nach Providerwechsel startet der **Modellabruf automatisch**. +- Wenn eine Modellliste erfolgreich geladen werden kann: + - erscheint eine **nicht editierbare ComboBox**, + - die **nie leer** ist, + - deren **erstes Modell automatisch vorbelegt** ist. +- Wenn keine Modellliste verfügbar ist: + - erscheint statt der ComboBox ein **leeres Texteingabefeld**, + - das Modell muss dann manuell eingetragen werden. +- Ein zuvor manuell eingetragener Modellname wird verworfen, wenn später eine echte Modellliste geladen wird und der Wert dort nicht vorkommt. + +### 7. Felder, Picker und Pfadangaben + +Für folgende Pfade gibt es jeweils: + +- ein **Texteingabefeld** +- plus einen **kleinen nativen Datei-/Ordnerdialog-Button** + +Dies gilt mindestens für: + +- Quellordner +- Zielordner +- SQLite-Datei +- Prompt-Datei + +### 8. API-Key in V2.0 + +- Der API-Key wird direkt in der `.properties`-Datei gespeichert und bearbeitet. +- Die GUI respektiert dabei die bestehende V1.1-Auflösungsreihenfolge: + 1. providerspezifische Umgebungsvariable, + 2. bei **OpenAI-kompatibel** zusätzlich die bestehende Legacy-Umgebungsvariable, + 3. Property-Wert aus der `.properties`-Datei. +- Die GUI macht diese Herkunft für den Benutzer sichtbar, insbesondere wenn aktuell eine Umgebungsvariable Vorrang vor dem in der Datei eingetragenen Wert hat. +- Das GUI-Feld ist bewusst als **normales, unmaskiertes Textfeld** vorgesehen; dies ist eine pragmatische V2.0-Entscheidung und keine Sicherheitsbehauptung. +- Ein leeres GUI-Feld darf einen bereits vorhandenen Property-Wert **nicht stillschweigend löschen**, wenn keine Umgebungsvariable greift. In diesem Fall bleibt der bestehende Property-Wert erhalten und es erscheint eine deutliche Warnung. + +### 9. Meldungen und feldnahe Validierung + +V2.0 enthält zwei Ebenen der Benutzerführung: + +#### A. zentraler Meldungsbereich unten + +Der Meldungsbereich ist: + +- groß +- nicht editierbar +- dauerhaft sichtbar + +Er nutzt vier feste Stufen: + +- **Info** +- **Hinweis** +- **Warnung** +- **Fehler** + +Dabei gilt: + +- nur das Präfix (**„Info:“**, **„Hinweis:“**, **„Warnung:“**, **„Fehler:“**) ist farbig +- der eigentliche Text derselben Zeile bleibt schwarz + +#### B. feldnahe Validierung + +Bei Eingabefehlern erscheint direkt unter dem betroffenen Feld: + +- eine **kleine** +- **rote** +- **deutschsprachige** +- **hilfreiche** Fehlermeldung + +### 10. Automatische Validierung beim Öffnen und während der Bearbeitung + +- **Automatische Validierung** bezeichnet in V2.0 die im Hintergrund laufende Prüfung aus M11. +- Eine geladene Konfiguration wird **sofort beim Öffnen** geprüft. +- Es gibt **Fehler**, **Warnungen** und **Hinweise**. +- Auch **unsinnige, aber formal gültige Einstellungen** werden als Warnung bewertet. +- `max.text.characters` erhält in V2.0 bewusst wirtschaftliche Warnschwellen: + - bis **1.000**: unkritisch + - **1.001–3.000**: Warnung + - ab **3.001**: starke Warnung +- `max.pages` dient in V2.0 nur als **Plausibilitäts-/Performance-Hinweis**, nicht als primäre Kostenwarnung. +- Warnungen verhindern das Speichern nicht. +- Fehler markieren den Zustand als **nicht lauffähig**. +- **Speichern bleibt trotzdem erlaubt**. +- Vor dem Speichern eines als **nicht lauffähig** markierten Stands erscheint jedoch eine deutlich sichtbare Warnung im zentralen Meldungsbereich, die ausdrücklich auf mögliche Auswirkungen auf den nächsten headless Lauf hinweist. + +### 11. Aktion „Validieren“ und technische Tests + +- **Aktion „Validieren“** bezeichnet in V2.0 die explizite M12-Bedienhandlung über den gleichnamigen Button. +- Diese Aktion nutzt denselben Kernregelrahmen wie die automatische Validierung, darf aber zusätzliche **lokale** Prüfpunkte zusammenführen und schreibt nichts auf die Platte. + +V2.0 enthält mindestens diese Aktionen: + +- **Neu** +- **Öffnen** +- **Speichern** +- **Speichern unter** +- **Validieren** +- **Technische Tests ausführen** +- **Modelle neu laden** + +Für **Aktion „Validieren“** und **„Technische Tests ausführen“** gilt: + +- sie arbeiten auf dem **aktuellen GUI-Zustand** +- also auch auf **ungespeicherten Änderungen** +- die Datei wird dabei **nicht implizit gespeichert** +- ein Hinweis auf ungespeicherte Prüfgrundlage ist zweckmäßig + +### 12. Umfang der technischen Tests in V2.0 + +Die technischen Tests werden in V2.0 **nur als Gesamttest** angeboten. + +- kein Einzeltasten-Test pro Prüfpunkts +- kein Abbruch beim ersten Fehler +- alle Prüfpunkte werden vollständig durchlaufen +- alle Befunde werden gesammelt ausgegeben + +Zu prüfen sind mindestens: + +- Properties-Datei validieren +- Provider-Konfiguration prüfen +- Base-URL/Endpoint erreichbar +- API-Key vorhanden, auch wenn der effektive Wert ausschließlich über eine passende Umgebungsvariable bereitgestellt wird +- API-Key technisch akzeptiert +- Modellliste abrufbar +- gewähltes Modell plausibel +- Prompt-Datei vorhanden/lesbar +- Quellordner vorhanden/lesbar +- Zielordner vorhanden oder anlegbar/schreibbar +- SQLite-Datei bzw. Pfad nutzbar + +### 13. Korrigierende technische Tests + +V2.0 erlaubt bei technischen Tests auch **korrigierende Maßnahmen**, soweit diese sicher und lokal sinnvoll sind. + +Beispiele: + +- Zielordner anlegen +- SQLite-Datei anlegen +- Prompt-Datei anlegen +- technische Kleinkorrekturen übernehmen + +Dabei gilt: + +- Es erfolgt **kein stilles Schreiben im Hintergrund**. +- Vor schreibenden Korrekturen erscheint **ein gesammelter Bestätigungsdialog**: + - „Folgende Korrekturen werden durchgeführt … Fortfahren?“ + +Nicht automatisch korrigierbar bleiben insbesondere: + +- falscher API-Key +- unerreichbare Base-URL +- nicht verfügbare Modellliste +- sonstige externe technische Fehler + +### 14. Prompt-Datei in V2.0 + +- Wenn die konfigurierte Prompt-Datei fehlt, darf V2.0 automatisch eine **sinnvolle Standard-Prompt-Datei** erzeugen. +- Diese Standard-Prompt-Datei ist **deutschsprachig**. +- Standardmäßig liegt sie **im selben Ordner wie die `.properties`-Datei**. + +--- + +## Explizit nicht Bestandteil von V2.0 + +Die folgenden Themen wurden bewusst angesprochen, aber aus V2.0 ausdrücklich ausgegrenzt: + +- manueller Verarbeitungslauf aus der GUI +- Start eines echten Batch-Laufs per GUI +- Visualisierung der SQLite-Datenbank in der GUI +- Anzeige der Historie in einem eigenen GUI-Tab +- Kosten-Tracking +- exakte Token-Schätzung +- echte Kostenprognose +- echter Mini-KI-Testaufruf mit fachlicher Antwortauswertung +- EXE-Datei +- Installer +- zusätzliche Provider über Claude und OpenAI-kompatibel hinaus +- automatischer Fallback zwischen Providern +- mehrere benannte Profile pro Provider +- plattformübergreifender offizieller GUI-Support +- neues Konfigurationsformat +- Änderung der fachlichen Kernverarbeitung des PDF-Umbenenners +- Änderung der bestehenden Status-, Retry- oder Persistenz-Wahrheit +- neuer Parameter zur gesonderten Steuerung der für die KI berücksichtigten Seiten + +--- + +# Neue Meilensteine für V2.0 + +## Grundsätze für alle V2.0-Meilensteine + +- Jeder Meilenstein liefert einen **in sich geschlossenen, buildbaren Entwicklungsstand**. +- Jeder Meilenstein bleibt **architekturtreu**. +- Die Erweiterung darf den bestehenden **headless Betrieb** nicht still brechen. +- GUI und headless greifen auf **dieselbe `.properties`-Konfigurationswelt** zu. +- V2.0 führt **keine neue Persistenz-Wahrheit** und **keine neue Fachlogik** für die PDF-Benennung ein. +- Der Fokus liegt auf **Benutzerkomfort, Konfigurationssicherheit und Diagnosefähigkeit**. + +--- + +## M9 – GUI-Grundgerüst, neues Betriebsmodell und Packaging-Basis + +### Ziel + +Die Anwendung erhält das technische Grundgerüst für eine JavaFX-GUI, ohne den bestehenden headless Batch-Betrieb zu verlieren. + +### Inhalt + +- neues Modul `pdf-umbenenner-adapter-in-gui` einführen +- Startumschaltung zwischen GUI-Standardstart und `--headless` umsetzen +- neue CLI-Option `--config ` für GUI und headless einführen +- bestehendes headless Default-Verhalten ohne `--config` erhalten +- Bootstrap so erweitern, dass GUI und headless sauber verdrahtet werden +- JavaFX in das ausführbare JAR integrieren +- sicherstellen, dass GUI-Code den headless Pfad nicht unnötig früh initialisiert +- Windows als offizielles GUI-Zielsystem festlegen + +### Lauffähiger Stand + +- ein gemeinsames ausführbares JAR kann GUI oder headless starten +- `--headless` bleibt abwärtskompatibel nutzbar +- `--config` ist für beide Startarten funktionsfähig +- GUI-Start schlägt bei fehlender GUI-Voraussetzung kontrolliert mit klarer Fehlermeldung fehl + +### Tests + +- Starttests für GUI-Standardstart +- Starttests für `--headless` +- Starttests für `--config` +- Negativtests für ungültige oder fehlende Konfigurationspfade +- Smoke-Tests für Packaging und Artefakterzeugung + +--- + +## M10 – GUI-Konfigurationseditor, Dateihandling und Benutzerführung + +### Ziel + +Die GUI kann bestehende `.properties`-Dateien komfortabel öffnen, neue anlegen, bearbeiten und speichern. + +### Inhalt + +- Header mit aktuell genutztem Konfigurationspfad implementieren +- Aktionen **Neu**, **Öffnen**, **Speichern**, **Speichern unter** einführen +- Startzustand ohne geladene Konfiguration mit Willkommenstext umsetzen +- vollständige Standardvorlage mit sinnvollen Defaults für neue Konfigurationen bereitstellen +- alle aktuell bekannten Konfigurationswerte in der GUI abbilden +- Texteingabefelder plus Datei-/Ordnerdialoge für relevante Pfade umsetzen +- ungespeicherte Änderungen in Fenstertitel und Header markieren +- Dialoglogik für Speichern/Verwerfen/Abbrechen bei offenen Änderungen einführen +- Speicherlogik mit Normalisierung der `.properties` umsetzen + +### Lauffähiger Stand + +- neue und bestehende Konfigurationen können komfortabel bearbeitet werden +- neue Konfigurationen können unter `config/application.properties` relativ zum Arbeitsverzeichnis vorgeschlagen gespeichert werden +- bestehende Konfigurationen können sicher geöffnet und überschrieben werden +- die GUI arbeitet vollständig auf der bestehenden `.properties`-Wahrheit + +### Tests + +- Tests für Öffnen/Speichern/Speichern unter +- Tests für neue Konfiguration mit Standardwerten +- Tests für Dialogverhalten bei ungespeicherten Änderungen +- Tests für Normalisierung und korrekten Schreibstand der `.properties` + +--- + +## M11 – Provider-Bedienung, Modellabruf und automatische Validierung + +### Ziel + +Die GUI bildet die bestehende Mehrprovider-Konfiguration komfortabel ab und validiert den Editorstand sofort und benutzerfreundlich. + +### Inhalt + +- Provider-ComboBox für Claude und OpenAI-kompatibel umsetzen +- nur den aktuell gewählten Provider-Bereich sichtbar machen +- Providerwechsel ohne Datenverlust des jeweils anderen Provider-Blocks umsetzen +- automatischen Modellabruf bei Providerwechsel einführen +- explizite Aktion **„Modelle neu laden“** an denselben Modellabruf anbinden +- Umschaltung zwischen Modell-ComboBox und manuellem Modell-Textfeld umsetzen +- automatische Validierung beim Öffnen und während der Bearbeitung einführen +- zentralen Meldungsbereich mit vier Stufen implementieren +- feldnahe rote Fehlermeldungen unter problematischen Eingabefeldern ergänzen +- wirtschaftliche Warnlogik für `max.text.characters` ergänzen +- `max.pages` als Plausibilitäts-/Performance-Hinweis behandeln + +### Lauffähiger Stand + +- Provider können komfortabel gewählt werden +- Modelllisten können automatisch geladen und dargestellt werden +- die GUI erkennt Fehler, Warnungen und Hinweise unmittelbar +- unvollständige oder riskante Konfigurationen werden benutzerfreundlich sichtbar gemacht + +### Tests + +- Tests für Providerwechsel und Provider-spezifische Felder +- Tests für Modellabruf mit Liste und ohne Liste +- Tests für automatische Validierung beim Öffnen +- Tests für Meldungsstufen, Warnschwellen und feldnahe Fehleranzeige + +--- + +## M12 – Technische Tests, Korrekturhilfen und Windows-/Netzlaufwerksfähigkeit + +### Ziel + +Die GUI kann den aktuellen Editorstand technisch prüfen, alle Befunde gesammelt anzeigen und sinnvolle technische Korrekturen nach Benutzerbestätigung durchführen. + +### Inhalt + +- Aktion **Validieren** umsetzen +- Aktion **Technische Tests ausführen** als Gesamttest umsetzen +- alle definierten Prüfpunkte vollständig und gesammelt ausführen +- Prüfungen gegen den aktuellen GUI-Zustand ohne implizites Speichern ausführen +- korrigierende technische Maßnahmen mit gesammeltem Bestätigungsdialog einführen +- automatische Standard-Prompt-Erzeugung bei fehlender Prompt-Datei einführen +- Netzlaufwerke über gemappte Laufwerksbuchstaben ausdrücklich unterstützen +- Pfadprüfungen für Quellordner, Zielordner, SQLite-Datei und Prompt-Datei vervollständigen + +### Lauffähiger Stand + +- technische Gesamtprüfung liefert vollständige, verständliche Diagnose +- lokale Korrekturen können kontrolliert durchgeführt werden +- gemappte Laufwerke wie `S:\` werden im Windows-Kontext korrekt akzeptiert +- fehlende Prompt-Datei kann automatisch sinnvoll erzeugt werden + +### Tests + +- Tests für Gesamttest ohne Frühabbruch +- Tests für Korrektur-Bestätigungsdialog +- Tests für technische Korrekturen (Ordner/Datei/Prompt) +- Tests für gemappte Laufwerke und Windows-Pfadannahmen +- Tests für Validierung und Tests mit ungespeicherten Änderungen + +--- + +## M13 – V2.0-Abschluss, Dokumentation und Qualitätsnachweis + +### Ziel + +Der V2.0-Ausbau wird dokumentiert, stabilisiert und als freigabefähiger Gesamtstand abgesichert. + +### Inhalt + +- technische und betriebliche Dokumentation auf GUI + headless erweitern +- neue Startoptionen (`--headless`, `--config`) dokumentieren +- Verhalten bei fehlender Konfiguration, ungültigen Pfaden und GUI-Fehlern dokumentieren +- Build- und Packaging-Dokumentation für das gemeinsame JAR ergänzen +- Regressionstests für headless Abwärtskompatibilität ergänzen +- GUI-nahe Tests für zentrale Bedienpfade und Fehlersituationen ergänzen +- Qualitäts- und Freigabenachweis für den V2.0-Gesamtstand erstellen + +### Lauffähiger Stand + +- GUI und headless sind gemeinsam dokumentiert und belastbar testbar +- bestehender Serverbetrieb bleibt kompatibel +- der V2.0-Stand ist freigabefähig und nachvollziehbar beschrieben + +### Tests + +- Reactor-Build des Gesamtprojekts +- GUI-/Headless-Smoke-Tests +- Regressionstests für bisherigen Batch-Betrieb +- Dokumentations- und Konfigurationsbeispielprüfung + +--- + +# Ausbaustufen und Ausblick jenseits von V2.0 + +## V2.1 – erster funktionaler Ausbau der GUI + +Naheliegende Themen für V2.1: + +- manueller Verarbeitungslauf aus der GUI +- Start eines echten Batch-Laufs aus der GUI +- ggf. erste laufbezogene Statusanzeige während der Ausführung +- erster separater Zusatz-Tab für weitergehende GUI-Funktionalität + +## V2.x – Komfort- und Transparenzausbau + +Naheliegende Themen für spätere V2.x-Stufen: + +- Visualisierung der SQLite-Datenbank in einem separaten Tab +- Anzeige von Historie und Verarbeitungsergebnissen +- Kosten-Tracking +- spätere, bewusst getrennte Erweiterung technischer Testfunktionen +- ggf. echter Mini-KI-Testaufruf +- ggf. feinere technische Steuerung der an die KI gegebenen Eingabemenge + +## V3 – größerer Funktionsausbau + +Naheliegende Themen für V3: + +- weitere Provider über Claude und OpenAI-kompatibel hinaus +- mehrere Profile pro Provider +- automatischer Fallback zwischen Providern +- größere Packaging-/Distributionsausbauten wie EXE oder Installer +- optional späterer plattformübergreifender offizieller GUI-Support + +--- + +## Kompakte Entscheidungsliste für V2.0 + +Zur schnellen Einordnung gilt für V2.0: + +- GUI ist **Standardstart** +- `--headless` bleibt erhalten +- `--config ` gilt für GUI und headless +- ein gemeinsames **ausführbares JAR** +- **JavaFX integriert** +- **kein Installer**, **keine EXE** +- neues Modul **`pdf-umbenenner-adapter-in-gui`** +- `.properties` bleibt die **einzige Konfigurationswahrheit** +- GUI dient in V2.0 **nur** Konfiguration, Validierung und technischen Tests +- **kein** manueller Lauf in V2.0 +- **kein** DB-/Historien-Tab in V2.0 +- **kein** Kosten-Tracking in V2.0 +- **Windows** ist offizielles GUI-Zielsystem +- **gemappte Laufwerke** sind zwingend zu unterstützen +- Provider bleiben in V2.0 auf **Claude** und **OpenAI-kompatibel** begrenzt +- exakt **ein aktiver Provider** bleibt erhalten + +--- + +## Ergebnis + +Mit diesem Zuschnitt bleibt V2.0: + +- **deutlich nützlicher** für den Benutzer, +- **architekturtreu** zum bestehenden System, +- **abwärtskompatibel** für den headless Serverbetrieb, +- und gleichzeitig **bewusst begrenzt**, damit spätere GUI-Ausbaustufen nicht schon in V2.0 vorweggenommen werden. \ No newline at end of file diff --git a/docs/workpackages/M10 - Arbeitspakete.md b/docs/workpackages/M10 - Arbeitspakete.md new file mode 100644 index 0000000..c2a288b --- /dev/null +++ b/docs/workpackages/M10 - Arbeitspakete.md @@ -0,0 +1,401 @@ +# M10 - Arbeitspakete + +## Geltungsbereich + +Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M10 – GUI-Konfigurationseditor, Dateihandling und Benutzerführung**. + +Die Meilensteine **M1** bis **M9** 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 GUI-Modul, Bootstrap, Konfigurationszugriff, Build und Tests ändern. +- Keine Annahmen treffen, die nicht durch die bestehenden Spezifikationen, den dokumentierten V1.1-Ist-Stand, die V2.0-Meilensteine oder dieses Dokument gedeckt sind. +- Kein Vorgriff auf **M11+**. +- Kein Umbau bestehender M1–M9-Strukturen ohne direkten M10-Bezug. +- Die GUI arbeitet weiterhin ausschließlich auf der bestehenden **`.properties`-Konfigurationswelt**. +- Die GUI darf in M10 **Dateien lesen, schreiben und normalisiert speichern**, aber noch **keine** sofortige Validierung, keinen Modellabruf und keine technischen Gesamttests ausführen. +- Das Ergebnis jedes Arbeitspakets muss für Benutzer bereits nachvollziehbar und bedienbar sein, auch wenn der volle V2.0-Komfort erst in M11/M12 erreicht wird. +- Neue Typen, View-Modelle, Dateidialoge, Editorzustände und Tests so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus klar benennbar, testbar und reviewbar sind. + +## Explizit nicht Bestandteil von M10 + +- sofortige Validierung beim Öffnen oder während der Eingabe +- zentraler Meldungsbereich mit Info/Hinweis/Warnung/Fehler +- feldnahe rote Fehlermeldungen unter Eingabefeldern +- Provider-ComboBox +- automatischer Modellabruf +- Umschaltung zwischen Modell-ComboBox und Modell-Textfeld +- technische Aktion **„Validieren“** +- technische Aktion **„Technische Tests ausführen“** +- Aktion **„Modelle neu laden“** +- wirtschaftliche Warnschwellen für `max.text.characters` +- Plausibilitäts-/Performance-Hinweise für `max.pages` +- automatische Prompt-Erzeugung +- technische Korrekturhilfen mit Bestätigungsdialog +- SQLite-/Historienanzeige +- manueller Verarbeitungslauf aus der GUI +- EXE +- Installer +- neues Konfigurationsformat +- Änderungen an fachlicher Kernverarbeitung, Statussemantik, Retry-Regeln oder Persistenz-Wahrheiten + +## Verbindliche M10-Regeln für **alle** Arbeitspakete + +### 1. Konfigurationswahrheit + +Ab M10 gilt verbindlich: + +- Die GUI liest, bearbeitet und schreibt dieselbe **`.properties`-Datei** wie der headless Betrieb. +- Es wird **kein** neues Konfigurationsformat eingeführt. +- Kommentare, Reihenfolge und Formatierung dürfen beim Speichern **technisch normalisiert** werden. +- Die GUI bearbeitet **alle aktuell bekannten Konfigurationswerte** des bestehenden Produkts. + +### 2. Startzustand der GUI + +Ab M10 gilt verbindlich: + +- Beim GUI-Start wird **keine Konfiguration automatisch geladen**, sofern nicht eine gültige Konfigurationsdatei explizit über den Startpfad aus M9 übergeben wurde. +- Ohne geladene Konfiguration zeigt die GUI einen **deutschen Willkommenstext** mit kurzer Anleitung. +- Der Benutzer kann von dort aus mindestens **„Neu“** und **„Öffnen“** auslösen. + +### 3. Neue Konfiguration + +Ab M10 gilt verbindlich: + +- **„Neu“** erzeugt eine **vollständige Standardvorlage** mit sinnvollen Default-Werten. +- Diese Vorlage enthält die **bestehende Mehrprovider-Struktur**. +- Standardmäßig ist der **alphabetisch erste vorhandene Provider** aktiv. +- Eine neue, noch nie gespeicherte Konfiguration gilt als eigener Editorzustand und darf bearbeitet werden, ohne sofort auf Platte geschrieben zu werden. + +### 4. Dateiverhalten + +Ab M10 gilt verbindlich: + +- **„Öffnen“** und **„Speichern unter“** filtern auf **`*.properties`**. +- **„Speichern“** verhält sich bei einer neuen, noch nie gespeicherten Konfiguration wie **„Speichern unter“**. +- **„Speichern unter“** schlägt standardmäßig denselben Standardpfad vor, den der bestehende headless Betrieb in V1.1 verwendet, also **`config/application.properties`** relativ zum Arbeitsverzeichnis. Dadurch ist die in der GUI gespeicherte Datei ohne weitere Schritte für den nächsten headless Scheduler-Lauf nutzbar. +- Beim Speichern auf eine bereits existierende Datei erscheint eine klare Rückfrage **„Datei überschreiben?“**. +- Vor dem Überschreiben einer bestehenden `.properties`-Datei legt die GUI eine `.bak`-Sicherung im selben Schema wie der bestehende V1.1-Migrationspfad an (**`.bak`**, bei Kollision **`.bak.1`**, **`.bak.2`**, …). + +### 5. Editorzustand und ungespeicherte Änderungen + +Ab M10 gilt verbindlich: + +- Ungespeicherte Änderungen werden im **Fenstertitel** und im **Header** sichtbar markiert. +- Vor **Neu**, **Öffnen** oder **Schließen** erscheint bei ungespeicherten Änderungen ein Dialog mit: + - **Speichern** + - **Verwerfen** + - **Abbrechen** +- In M10 sind diese Entscheidungen rein editorbezogen; sie lösen noch **keine** Validierungs- oder Testlogik aus. + +### 6. GUI-Struktur in M10 + +M10 liefert bereits den echten Konfigurationseditor, aber noch ohne M11/M12-Komfortlogik. + +Daraus folgt: + +- Es bleibt bei **genau einem Tab**. +- Die Oberfläche ist in feste, sichtbare Bereiche gegliedert: + 1. **Header / Konfigurationsdatei** + 2. **Pfade** + 3. **Provider** + 4. **Verarbeitungslimits** + 5. **Tests** + 6. **Meldungen** +- In M10 dürfen Bereiche **„Tests“** und **„Meldungen“** bereits strukturell sichtbar sein, auch wenn ihre echte Funktionalität erst in M11/M12 vervollständigt wird. +- Die Oberfläche muss scrollbar und benutzbar bleiben; einklappbare Gruppen oder zusätzliche Tabs sind in M10 nicht Ziel. + +### 7. Datei- und Ordnerdialoge + +Ab M10 gilt verbindlich: + +- Für mindestens folgende Pfadangaben stehen ein Texteingabefeld und ein kleiner nativer Datei-/Ordnerdialog-Button bereit: + - Quellordner + - Zielordner + - SQLite-Datei + - Prompt-Datei +- Die GUI darf dabei Windows-typische Pfadangaben nicht künstlich einschränken. +- Gemappte Laufwerksbuchstaben dürfen nicht durch GUI-Dateilogik beschädigt oder unbrauchbar gemacht werden. + +### 8. API-Key-Feld und bestehende Vorrangregel + +Ab M10 gilt verbindlich: + +- Die GUI bildet den API-Key pro Provider weiterhin innerhalb der bestehenden `.properties`-Konfigurationswelt ab. +- Die spätere Bewertung des **effektiven** API-Keys muss die bestehende Vorrangregel respektieren: + 1. providerspezifische Umgebungsvariable, + 2. bei **OpenAI-kompatibel** zusätzlich die bestehende Legacy-Umgebungsvariable, + 3. Property-Wert aus der Datei. +- Der Editorzustand muss deshalb zwischen bearbeitetem Property-Wert und später anzeigbarer Herkunft des effektiven API-Keys anschlussfähig bleiben. +- Das API-Key-Feld bleibt bewusst ein normales, unmaskiertes Textfeld. +- Ein leeres API-Key-Feld darf einen bereits vorhandenen Property-Wert nicht stillschweigend entfernen, solange keine ausdrückliche Löschsemantik eingeführt wurde. + +--- + +## AP-001 Editorzustand, Konfigurationsabbild und Standardvorlage einführen + +### Voraussetzung +Keine. Dieses Arbeitspaket ist der M10-Startpunkt. + +### Ziel +Der GUI-Editor erhält ein sauberes internes Zustandsmodell für bestehende und neue Konfigurationen, einschließlich vollständiger Standardvorlage und Dirty-State-Grundlage. + +### Muss umgesetzt werden +- GUI-seitiges Editor-/View-Model für die bearbeitbare Konfiguration einführen. +- Abbildung aller aktuell bekannten Konfigurationswerte in einen GUI-tauglichen Bearbeitungszustand modellieren. +- Den Bearbeitungszustand so schneiden, dass für den API-Key je Provider sowohl der editierbare Property-Wert als auch die spätere Herkunft des effektiven Werts gemäß bestehender Vorrangregel anschlussfähig bleiben. +- Saubere Trennung zwischen: + - geladener Dateirepräsentation, + - bearbeitbarem Editorzustand, + - neu erzeugter Standardvorlage, + - Dirty-State/Änderungsstand. +- Vollständige Standardvorlage für **„Neu“** bereitstellen. +- Sicherstellen, dass die Standardvorlage die bestehende Mehrprovider-Struktur erhält und mit sinnvollen Defaults startet. +- Mapping so schneiden, dass spätere M11-/M12-Logik darauf aufsetzen kann, ohne ein neues Konfigurationsmodell zu erfinden. +- JavaDoc und `package-info` für Verantwortlichkeiten und Grenzen ergänzen. + +### Explizit nicht Teil +- JavaFX-Layout +- Datei öffnen oder speichern +- Dirty-State-Anzeige im Fenster +- Dialoge +- Validierung oder Tests + +### Fertig wenn +- ein konsistenter GUI-Editorzustand modelliert ist, +- neue Standardkonfigurationen erzeugt werden können, +- alle aktuell bekannten Konfigurationswerte im Editorzustand abbildbar sind, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-002 Header, leerer Startzustand und Aktionsgrundgerüst der GUI vervollständigen + +### Voraussetzung +AP-001 ist abgeschlossen. + +### Ziel +Die GUI zeigt bei fehlender Konfiguration einen benutzerfreundlichen Startzustand und bietet die zentralen Dateiaktionen in einer stabilen Grundstruktur an. + +### Muss umgesetzt werden +- Header-Bereich mit Anzeige des aktuell verwendeten Konfigurationspfads implementieren. +- Verhalten ohne geladene Konfiguration umsetzen: + - leerer Pfad im Header, + - deutscher Willkommenstext, + - sichtbare Aktionen für **„Neu“** und **„Öffnen“**. +- Aktionsgrundgerüst für mindestens diese Bedienhandlungen sichtbar und verdrahtbar anlegen: + - **Neu** + - **Öffnen** + - **Speichern** + - **Speichern unter** +- Sicherstellen, dass die GUI ohne geladene Konfiguration nicht verwirrend einen impliziten Standardentwurf zeigt. +- Grundstruktur des einen GUI-Tabs mit den festen Bereichen anlegen, soweit für M10 erforderlich. +- JavaDoc/Kommentare für den GUI-Startzustand ergänzen. + +### Explizit nicht Teil +- tatsächliches Dateiladen +- tatsächliches Speichern +- unsaved-changes-Dialoge +- provider-spezifische Komfortlogik aus M11 +- technische Tests oder Meldungslogik + +### Fertig wenn +- die GUI ohne geladene Konfiguration benutzerfreundlich startet, +- Header und Grundaktionen sichtbar vorhanden sind, +- der Benutzer klar zwischen **„Neu“** und **„Öffnen“** geführt wird, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-003 Öffnen bestehender `.properties`-Dateien und Übernahme in den Editorzustand umsetzen + +### Voraussetzung +AP-001 und AP-002 sind abgeschlossen. + +### Ziel +Bestehende Konfigurationsdateien können über den GUI-Dateidialog geladen und in den Editorzustand übernommen werden. + +### Muss umgesetzt werden +- Native Dateiauswahl für **„Öffnen“** mit Filter auf **`*.properties`** implementieren. +- Bestehende `.properties`-Datei technisch laden und in den Editorzustand überführen. +- Beim Öffnen einer erkannten Legacy-Konfiguration aus Vor-V1.1 die bestehende Migrationslogik des headless Pfads wiederverwenden; die GUI führt keinen zweiten, separaten Migrationspfad ein. +- Sicherstellen, dass die Dateiübernahme mit dem aus M9 bereits vorhandenen GUI-Start über gültiges `--config ` zusammenarbeiten kann. +- Header-Anzeige nach erfolgreichem Laden auf den vollständigen Pfad aktualisieren. +- Fehlersituationen beim Laden kontrolliert behandeln, soweit für M10 nötig. +- Noch nicht implementierte Validierungs- oder Testlogik aus M11/M12 nicht vorwegnehmen. +- JavaDoc für Dateiladeverantwortung und Editorübernahme ergänzen. + +### Explizit nicht Teil +- Speichern oder Speichern unter +- Dirty-State-Dialoge +- sofortige Validierung +- Modellabruf +- technische Tests + +### Fertig wenn +- bestehende `.properties`-Dateien per GUI geöffnet werden können, +- ihr Inhalt im Editorzustand sichtbar und bearbeitbar ist, +- die Header-Anzeige den geladenen Pfad korrekt darstellt, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-004 Speichern, Speichern unter und normalisierte `.properties`-Schreiblogik implementieren + +### Voraussetzung +AP-001 bis AP-003 sind abgeschlossen. + +### Ziel +Der Editor kann neue und bestehende Konfigurationen zuverlässig, normalisiert und benutzerfreundlich als `.properties` schreiben. + +### Muss umgesetzt werden +- Schreiblogik für bestehende und neue Konfigurationen implementieren. +- **„Speichern“** für bereits bekannte Dateipfade umsetzen. +- **„Speichern“** für neue, noch nie gespeicherte Konfigurationen wie **„Speichern unter“** behandeln. +- **„Speichern unter“** mit Vorschlag desselben Standardpfads implementieren, den der bestehende headless Betrieb in V1.1 verwendet, also **`config/application.properties`** relativ zum Arbeitsverzeichnis. +- Dialogfilter auf **`*.properties`** anwenden. +- Rückfrage **„Datei überschreiben?“** bei existierender Zieldatei umsetzen. +- Vor dem Überschreiben einer bestehenden `.properties`-Datei eine `.bak`-Sicherung im selben Schema wie der bestehende V1.1-Migrationspfad anlegen (**`.bak`**, bei Kollision **`.bak.1`**, **`.bak.2`**, …); diese Sicherung ist verbindlicher Teil der Speicherlogik. +- Speicherung als normalisierte `.properties` sicherstellen. +- Für API-Key-Felder sicherstellen, dass ein leeres GUI-Feld einen bereits vorhandenen Property-Wert nicht stillschweigend entfernt; stattdessen muss ein kontrolliertes Ergebnis für die spätere Warnanzeige aus M11/M12 bereitstehen. +- Header-Pfad nach erfolgreichem Erstspeichern bzw. Speichern unter korrekt fortschreiben. +- JavaDoc für Dateischreibverhalten, API-Key-Erhaltung und Normalisierung ergänzen. + +### Explizit nicht Teil +- Dirty-State-Anzeige im Fenstertitel +- Dialogverhalten bei ungespeicherten Änderungen vor Neu/Öffnen/Schließen +- Validierung oder technische Tests +- automatische Prompt-Erzeugung + +### Fertig wenn +- neue und bestehende Konfigurationen zuverlässig gespeichert werden können, +- Speichern/Speichern unter benutzerfreundlich und nachvollziehbar arbeiten, +- normalisierte `.properties`-Dateien geschrieben werden, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-005 Dirty-State, optische Kennzeichnung und Schutzdialoge bei ungespeicherten Änderungen umsetzen + +### Voraussetzung +AP-001 bis AP-004 sind abgeschlossen. + +### Ziel +Ungespeicherte Änderungen werden sichtbar gemacht und vor verlustbehafteten Bedienhandlungen kontrolliert abgefragt. + +### Muss umgesetzt werden +- Dirty-State aus dem Editorzustand in die GUI übertragen. +- Optische Kennzeichnung ungespeicherter Änderungen an **beiden** Stellen umsetzen: + - Fenstertitel + - Header neben dem Konfigurationspfad +- Schutzdialog vor **Neu**, **Öffnen** und **Schließen** bei ungespeicherten Änderungen implementieren. +- Dialogoptionen exakt wie definiert bereitstellen: + - **Speichern** + - **Verwerfen** + - **Abbrechen** +- Sicherstellen, dass der Dialogfluss mit neuer Konfiguration, bestehender Konfiguration und erstmaligem Speichern konsistent zusammenwirkt. +- Noch keine M11/M12-Validierungs- oder Testlogik mit diesem Dialog vermischen. +- JavaDoc für Dirty-State- und Schutzdialog-Verhalten ergänzen. + +### Explizit nicht Teil +- sofortige Validierung +- technischer Gesamttest +- Meldungsbereichslogik +- provider-spezifische Komfortlogik + +### Fertig wenn +- ungespeicherte Änderungen sichtbar markiert werden, +- verlustbehaftete Bedienhandlungen kontrolliert abgefragt werden, +- die Dialogoptionen konsistent funktionieren, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-006 Vollständige Editoroberfläche mit allen Konfigurationswerten und nativen Datei-/Ordnerdialogen vervollständigen + +### Voraussetzung +AP-001 bis AP-005 sind abgeschlossen. + +### Ziel +Die GUI bildet alle aktuell bekannten Konfigurationswerte sichtbar und bearbeitbar ab, einschließlich der relevanten Pfad-Picker. + +### Muss umgesetzt werden +- Die feste Oberflächenstruktur für den einen Tab vollständig ausbauen. +- Alle aktuell bekannten Konfigurationswerte in geeigneten Eingabefeldern abbilden. +- Für mindestens diese Pfade jeweils Texteingabefeld plus kleinen nativen Datei-/Ordnerdialog-Button umsetzen: + - Quellordner + - Zielordner + - SQLite-Datei + - Prompt-Datei +- Sicherstellen, dass Eingabefelder und Dialoge auf denselben Editorzustand arbeiten. +- Windows-typische Pfadangaben und gemappte Laufwerksbuchstaben technisch unbeeinträchtigt übernehmen. +- Provider-bezogene Felder so einhängen, dass spätere M11-Komfortlogik darauf aufsetzen kann, ohne das Grundlayout neu zu erfinden. +- Noch keine sofortige Validierung, keinen Modellabruf und keine technische Testfunktion aktivieren. +- JavaDoc für GUI-Bereichsverantwortung und Pfadbedienung ergänzen. + +### Explizit nicht Teil +- Provider-ComboBox +- Modelllistenlogik +- feldnahe Fehlermeldungen +- zentraler Meldungsbereich mit echter Semantik +- technische Tests oder Korrekturhilfen + +### Fertig wenn +- alle aktuell bekannten Konfigurationswerte im GUI-Editor sichtbar und bearbeitbar sind, +- die relevanten Datei-/Ordnerdialoge funktional vorhanden sind, +- Windows-Pfade und gemappte Laufwerke nicht künstlich beschädigt werden, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-007 M10-Integration, GUI-Dateifluss über `--config` und benutzernahe Regressionstests absichern + +### Voraussetzung +AP-001 bis AP-006 sind abgeschlossen. + +### Ziel +Der vollständige M10-Datei- und Editorfluss wird integriert abgesichert, einschließlich des Zusammenspiels mit dem in M9 eingeführten Startpfad. + +### Muss umgesetzt werden +- Sicherstellen, dass ein gültiger übergebener GUI-Konfigurationspfad aus M9 direkt als Editorinhalt geladen werden kann. +- Sicherstellen, dass der GUI-Start ohne Konfiguration weiterhin im definierten Willkommenstext-Zustand landet. +- Regressionstests für die wesentlichen M10-Bedienflüsse ergänzen, insbesondere für: + - GUI-Start ohne geladene Konfiguration, + - **Neu** mit Standardvorlage, + - **Öffnen** bestehender `.properties`, + - Wiederverwendung der bestehenden headless Migrationslogik beim Öffnen einer Legacy-Konfiguration, + - **Speichern** und **Speichern unter**, + - Überschreibdialog, + - `.bak`-Sicherung beim Überschreiben einer bestehenden `.properties`-Datei, + - Dirty-State-Markierung, + - Schutzdialog bei offenen Änderungen, + - gültigen GUI-Start mit `--config`. +- Tests so schneiden, dass sie M10 zuverlässig absichern, ohne M11/M12-Funktionalität künstlich zu simulieren. +- Abschließende Konsistenzprüfung des M10-Stands gegen den definierten Scope durchführen. + +### Explizit nicht Teil +- sofortige Validierung beim Öffnen +- technischer Gesamttest +- Modellabruf +- Korrekturhilfen +- DB-/Historienfunktionalität + +### Fertig wenn +- der vollständige M10-Datei- und Editorfluss integriert funktioniert, +- die wesentlichen Bedienpfade automatisiert abgesichert sind, +- der Stand buildbar, testbar und übergabefähig ist, +- noch keine Funktionalität aus M11+ vorweggenommen wurde. + +--- + +## Abschlussbewertung + +Die Arbeitspakete sind inhaltlich konsistent, widerspruchsfrei und sauber auf den Meilenstein **M10 – GUI-Konfigurationseditor, Dateihandling und Benutzerführung** zugeschnitten. Sie liefern einen echten, benutzerfreundlichen Konfigurationseditor auf Basis der bestehenden `.properties`-Wahrheit, ohne bereits Provider-Komfortlogik, sofortige Validierung oder technische Test-/Korrekturfunktionen aus **M11/M12** vorwegzunehmen. \ No newline at end of file diff --git a/docs/workpackages/M11 - Arbeitspakete.md b/docs/workpackages/M11 - Arbeitspakete.md new file mode 100644 index 0000000..8fdbe93 --- /dev/null +++ b/docs/workpackages/M11 - Arbeitspakete.md @@ -0,0 +1,407 @@ +# M11 - Arbeitspakete + +## Geltungsbereich + +Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M11 – Provider-Bedienung, Modellabruf und automatische Validierung**. + +Die Meilensteine **M1** bis **M10** 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, GUI und Tests ändern. +- Keine Annahmen treffen, die nicht durch die bestehenden Spezifikationen, den dokumentierten V1.1-Ist-Stand, `meilensteine-v2_0.md` oder dieses Dokument gedeckt sind. +- Kein Vorgriff auf **M12+**. +- Kein Umbau bestehender M1–M10-Strukturen ohne direkten M11-Bezug. +- Die GUI muss mit der bestehenden **Mehrprovider-Konfigurationsstruktur** kompatibel bleiben. +- Es bleibt bei **genau einem aktiven Provider**; die GUI darf dabei die nicht sichtbaren Providerdaten nicht verlieren. +- Der Modellabruf ist in M11 **Komfortfunktion**, kein manueller Gesamttest und kein KI-Funktionsnachweis. +- Automatische Validierung in M11 ist **editornah und benutzerführend**; sie läuft beim Öffnen und während der Bearbeitung im Hintergrund und ersetzt noch nicht die explizite **Aktion „Validieren“** oder **„Technische Tests ausführen“** aus M12. +- Änderungen klein, fokussiert und architekturtreu halten. +- Neue Typen, View-Modelle, Ports, Provider-Resolver, Meldungsmodelle und Tests so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus klar benennbar, testbar und reviewbar sind. + +## Explizit nicht Bestandteil von M11 + +- Aktion **„Validieren“** +- Aktion **„Technische Tests ausführen“** +- Aktion **„Modelle neu laden“** als vollständige Bedienlogik, soweit dafür M12-spezifische Gesamtprüfung oder Korrekturhilfen nötig wären +- technische Gesamtprüfung aller Konfigurations- und Laufzeitvoraussetzungen +- schreibende Korrekturhilfen oder Sammel-Bestätigungsdialoge +- automatische Erzeugung fehlender Prompt-Dateien +- DB-/Historienanzeige +- manueller Verarbeitungslauf aus der GUI +- EXE +- Installer +- neues Konfigurationsformat +- neue Provider über Claude und OpenAI-kompatibel hinaus +- Änderungen an fachlicher Kernverarbeitung, Statussemantik, Retry-Regeln oder Persistenz-Wahrheiten + +## Verbindliche M11-Regeln für **alle** Arbeitspakete + +### 1. Provider-Bedienung + +Ab M11 gilt verbindlich: + +- Es gibt genau **eine Provider-ComboBox**. +- Sichtbar ist immer nur der **aktuell ausgewählte Provider-Bereich**. +- Die GUI darf die Daten des jeweils nicht sichtbaren Providers **nicht löschen**. +- Die bestehende Mehrprovider-Struktur in der `.properties`-Datei bleibt erhalten. +- In M11 werden genau die bereits vorhandenen Provider unterstützt: + - **Claude** + - **OpenAI-kompatibel** + +### 2. Modellabruf und Modellfeldlogik + +Ab M11 gilt verbindlich: + +- Nach Providerwechsel startet der **Modellabruf automatisch**. +- Der Modellabruf darf auch dann angestoßen werden, wenn die Konfiguration noch unvollständig ist. +- Fehlende Voraussetzungen führen **nicht** zu einem Absturz, sondern zu benutzerfreundlichen Befunden. +- Wenn eine Modellliste erfolgreich geladen werden kann: + - erscheint eine **nicht editierbare ComboBox**, + - sie ist **nie leer**, + - das **erste Modell** wird automatisch vorbelegt. +- Wenn keine Modellliste verfügbar ist: + - erscheint statt der ComboBox ein **leeres Texteingabefeld**, + - der Modellname muss manuell eingetragen werden. +- Ein zuvor manuell eingetragener Modellname wird **verworfen**, wenn später eine echte Modellliste geladen wird und der Wert dort nicht vorkommt. + +### 3. Automatische Validierung + +Ab M11 gilt verbindlich: + +- Die GUI validiert den aktuellen Editorzustand **sofort beim Öffnen** einer Konfiguration. +- Die GUI validiert den aktuellen Editorzustand außerdem **während der Bearbeitung**. +- Die Validierung arbeitet mit dem **aktuellen GUI-Zustand**, nicht mit dem zuletzt gespeicherten Dateistand. +- Die Validierung speichert **nichts implizit**. +- Die Validierung darf Befunde der Stufen **Info**, **Hinweis**, **Warnung** und **Fehler** erzeugen. + +### 4. Meldungsbereich + +Ab M11 gilt verbindlich: + +- Es gibt einen großen, nicht editierbaren, dauerhaft sichtbaren **zentralen Meldungsbereich**. +- Es gibt genau vier Stufen: + - **Info** + - **Hinweis** + - **Warnung** + - **Fehler** +- Nur das Präfix der Zeile ist farbig. +- Der eigentliche Text derselben Zeile bleibt **schwarz**. +- Modellabruf, automatische Validierung und GUI-nahe technische Befunde laufen in diesen Meldungsbereich ein. + +### 5. Feldnahe Fehlerrückmeldung + +Ab M11 gilt verbindlich: + +- Problematische Eingabefelder erhalten zusätzlich **feldnahe Fehlermeldungen**. +- Diese Meldungen sind: + - **klein**, + - **rot**, + - **deutschsprachig**, + - **direkt unter dem betroffenen Feld**. +- Feldnahe Meldungen ergänzen den zentralen Meldungsbereich; sie ersetzen ihn nicht. + +### 6. Warnlogik für Grenzen und Risiken + +Ab M11 gilt verbindlich: + +- **`max.text.characters`** wird wirtschaftlich bewertet mit folgenden Schwellen: + - bis **1.000**: unkritisch + - **1.001–3.000**: Warnung + - ab **3.001**: starke Warnung +- Diese Warnlogik ist ausdrücklich **zeichenbasiert** und verspricht **keine exakte Token- oder Kostenschätzung**. +- **`max.pages`** wird **nicht** als direkte Kostenwarnung behandelt, sondern höchstens als **Plausibilitäts-/Performance-Hinweis**. +- Weitere riskante, aber formal zulässige Konfigurationen dürfen als Warnung oder Hinweis sichtbar gemacht werden, soweit sie aus dem vorhandenen Zielbild klar ableitbar sind. + +### 7. Grenzen von M11 + +M11 liefert eine sofort reagierende, benutzerfreundliche Provider- und Validierungsoberfläche, aber noch **keine** vollständige technische Gesamtprüfung des Systems. + +Daraus folgt: + +- M11 darf Provider-nahe Remote-Kommunikation für **Modelllisten** einführen. +- M11 führt **keine** schreibenden Korrekturen durch. +- M11 vervollständigt noch **nicht** die M12-Gesamtprüfungen für Pfade, SQLite, Prompt-Datei oder anlegbare Ressourcen. + +--- + +## AP-001 Provider-/Modell-Kernobjekte, GUI-Zustandssemantik und Port-Verträge präzisieren + +### Voraussetzung +Keine. Dieses Arbeitspaket ist der M11-Startpunkt. + +### Ziel +Die M11-relevanten GUI-Zustände, Provider-/Modellmodelle, Meldungsstufen und Verträge werden eindeutig eingeführt, damit spätere Arbeitspakete ohne Interpretationsspielraum implementiert werden können. + +### Muss umgesetzt werden +- Neue M11-relevante Typen bzw. GUI-/Application-nahe Modelle anlegen, insbesondere für: + - auswählbaren Provider, + - sichtbaren Providerbereich, + - Modellquelle, + - Modelllisten-Ergebnis, + - manuellen Modellfallback, + - API-Key-Herkunft des effektiven Werts, + - Meldungsstufe, + - feldnahen Validierungsbefund, + - zentralen Meldungseintrag, + - Validierungsergebnis des aktuellen Editorzustands. +- Verträge so schneiden, dass spätere Arbeitspakete unterscheiden können zwischen: + - erfolgreichem Modellabruf mit Liste, + - technisch fehlgeschlagenem Modellabruf, + - Modellabruf ohne nutzbare Liste, + - automatischer Validierung mit Fehlern, + - automatischer Validierung mit Warnungen/Hinweisen. +- Outbound-Port bzw. Application-Vertrag für das providerabhängige Laden einer Modellliste definieren. +- Sicherstellen, dass Domain und Application frei von JavaFX-, HTTP- und JSON-Bibliothekstypen bleiben. +- JavaDoc und `package-info` für Verantwortlichkeiten und Grenzen ergänzen. + +### Explizit nicht Teil +- konkrete GUI-Widgets +- konkrete HTTP-Implementierung für Modelllisten +- Validierungsregeln selbst +- Meldungsbereich-Rendering +- Bootstrap-Verdrahtung + +### Fertig wenn +- die M11-relevanten Typen und Verträge vorhanden sind, +- technische und fachnahe GUI-Befunde klar unterscheidbar modelliert sind, +- Domain und Application frei von Infrastrukturtypen bleiben, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-002 Provider-ComboBox, sichtbarer Providerbereich und zustandsbewahrender Providerwechsel umsetzen + +### Voraussetzung +AP-001 ist abgeschlossen. + +### Ziel +Die GUI bildet die bestehende Mehrprovider-Struktur benutzerfreundlich ab, zeigt aber nur den aktuell ausgewählten Providerbereich an. + +### Muss umgesetzt werden +- Provider-ComboBox mit genau den zwei vorhandenen Providern implementieren. +- Sichtbarkeit der providerabhängigen Eingabefelder so umsetzen, dass immer nur der aktuell ausgewählte Providerbereich sichtbar ist. +- Sicherstellen, dass ein Providerwechsel die Werte des jeweils anderen Providers nicht verliert. +- Sicherstellen, dass die GUI weiterhin mit der bestehenden Mehrprovider-Konfigurationsstruktur kompatibel bleibt. +- Providerwechsel sauber in den Editorzustand zurückschreiben. +- Die GUI so schneiden, dass M11 später den automatischen Modellabruf andocken kann, ohne den Providerbereich erneut umzubauen. +- JavaDoc/Kommentare für die Zustandsbewahrung und die GUI-Verantwortung ergänzen. + +### Explizit nicht Teil +- Modellabruf +- automatische Validierung +- Meldungsbereich +- feldnahe Fehlermeldungen +- M12-Gesamttests + +### Fertig wenn +- der Provider komfortabel per ComboBox gewählt werden kann, +- immer nur die passenden Providerfelder sichtbar sind, +- die Werte des nicht sichtbaren Providers erhalten bleiben, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-003 Providerabhängigen Modellabruf für Claude und OpenAI-kompatibel technisch einführen + +### Voraussetzung +AP-001 und AP-002 sind abgeschlossen. + +### Ziel +Für den aktuell ausgewählten Provider kann eine Modellliste technisch geladen und gekapselt an die GUI zurückgegeben werden. + +### Muss umgesetzt werden +- Den in AP-001 definierten Modelllisten-Port technisch im Adapter-Out implementieren. +- Providerabhängige Modelllistenabfrage für: + - **Claude**, + - **OpenAI-kompatibel** + implementieren. +- Den Modellabruf so kapseln, dass GUI und Application keine HTTP- oder JSON-Details kennen. +- Kontrolliertes Fehlerverhalten mindestens für folgende Fälle bereitstellen: + - Providerkonfiguration unvollständig, + - Endpunkt nicht erreichbar, + - Authentifizierung schlägt technisch fehl, + - Provider liefert keine nutzbare Modellliste, + - sonstige technische Kommunikationsfehler. +- Sicherstellen, dass diese Fälle als benutzerfreundliche Befunde weitergegeben werden können und die GUI nicht abbrechen lassen. +- Modellabruf läuft asynchron auf einem Worker-Thread; das Ergebnis wird über den JavaFX Application Thread in die GUI zurückgespielt. +- Versuche und Ergebnisse des Modellabrufs werden im bestehenden Log4j2-Log nachvollziehbar protokolliert. +- Bootstrap-Verdrahtung nur im minimal erforderlichen Umfang ergänzen. +- JavaDoc für Modellabruf, Providergrenzen und Nicht-Ziele von M11 ergänzen. + +### Explizit nicht Teil +- Umschaltung zwischen ComboBox und Textfeld in der GUI +- automatische Validierung des gesamten Editorzustands +- Gesamtprüfung aus M12 +- schreibende Korrekturhilfen + +### Fertig wenn +- für beide vorhandenen Provider ein technischer Modellabruf möglich ist, +- Fehler kontrolliert und GUI-tauglich zurückgegeben werden, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-004 Automatischen Modellabruf, Aktion „Modelle neu laden“ und Umschaltung zwischen Modell-ComboBox und Modell-Textfeld integrieren + +### Voraussetzung +AP-001 bis AP-003 sind abgeschlossen. + +### Ziel +Die GUI reagiert auf Providerwechsel sofort mit Modellabruf, bietet zusätzlich eine explizite Aktion **„Modelle neu laden“** und zeigt je nach Ergebnis entweder eine nicht editierbare Modell-ComboBox oder ein manuelles Modell-Textfeld an. + +### Muss umgesetzt werden +- Automatischen Modellabruf bei Providerwechsel verdrahten. +- Die explizite Aktion **„Modelle neu laden“** an denselben Modellabruf anbinden, ohne eine zweite Modelllisten-Implementierung einzuführen. +- Sicherstellen, dass der Modellabruf auch bei unvollständiger Konfiguration angestoßen wird und dann benutzerfreundliche Befunde liefert. +- Bei erfolgreicher Modellliste: + - nicht editierbare ComboBox anzeigen, + - erstes Modell automatisch vorbelegen, + - leeren Zustand ausschließen. +- Bei fehlender oder unbrauchbarer Modellliste: + - manuelles Textfeld anzeigen, + - leeren Startwert zulassen, + - Benutzer zur manuellen Eingabe befähigen. +- Sicherstellen, dass ein früherer manueller Modellwert verworfen wird, wenn später eine echte Liste geladen wird und der Wert dort nicht vorkommt. +- Die Modellwert-Übernahme so schneiden, dass die `.properties`-Struktur später korrekt geschrieben werden kann. +- Modellabruf läuft asynchron auf einem Worker-Thread; das Ergebnis wird über den JavaFX Application Thread in die GUI zurückgespielt. +- Erfolgreiche Listenladung, manueller Fallback und technische Fehlschläge werden im bestehenden Log4j2-Log nachvollziehbar protokolliert. +- Benötigte Meldungen für erfolgreichen Modellabruf bzw. Fallback vorbereiten. +- JavaDoc/Kommentare für die Modellfeldsemantik ergänzen. + +### Explizit nicht Teil +- vollständiger zentraler Meldungsbereich +- feldnahe rote Fehlermeldungen +- allgemeine Editorvalidierung über alle Konfigurationsbereiche + +### Fertig wenn +- Modellabruf automatisch beim Providerwechsel ausgelöst wird, +- die Aktion **„Modelle neu laden“** denselben Modellabruf gezielt erneut auslösen kann, +- ComboBox und Textfeld korrekt umgeschaltet werden, +- die Liste nie leer dargestellt wird, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-005 Automatische Validierungslogik für geladenen und bearbeiteten Editorzustand umsetzen + +### Voraussetzung +AP-001 bis AP-004 sind abgeschlossen. + +### Ziel +Der aktuelle GUI-Zustand wird beim Öffnen und während der Bearbeitung sofort ausgewertet und liefert Fehler, Warnungen und Hinweise. + +### Muss umgesetzt werden +- Einen zentralen Validierungsbaustein für den aktuellen Editorzustand implementieren. +- Die Bewertung des API-Key-Zustands so umsetzen, dass die bestehende Vorrangregel respektiert wird: + 1. providerspezifische Umgebungsvariable, + 2. bei **OpenAI-kompatibel** zusätzlich die bestehende Legacy-Umgebungsvariable, + 3. Property-Wert aus der Datei. +- Validierung beim Öffnen einer Konfiguration automatisch ausführen. +- Revalidierung bei relevanten Änderungen während der Bearbeitung ausführen. +- Mindestens folgende Befundarten sicher unterscheiden: + - harte Fehler für unvollständige oder unzulässige Pflichtwerte, + - Warnungen für riskante, aber formal zulässige Einstellungen, + - Hinweise/Infos für nützliche Kontextinformationen. +- Die wirtschaftliche Warnlogik für **`max.text.characters`** mit den definierten Schwellen umsetzen. +- **`max.pages`** ausdrücklich nur als Plausibilitäts-/Performance-Hinweis behandeln. +- Sicherstellen, dass die Validierung mit dem aktuellen GUI-Zustand arbeitet und kein implizites Speichern auslöst. +- Sichtbar machen können, wenn aktuell eine Umgebungsvariable den Property-Wert übersteuert. +- Sicherstellen, dass ein leeres API-Key-Feld einen bereits vorhandenen Property-Wert nicht stillschweigend entfernt; stattdessen ist ein deutlicher Befund für den zentralen Meldungsbereich vorzubereiten. +- Wesentliche Ergebnisse der automatischen Validierung werden im bestehenden Log4j2-Log nachvollziehbar protokolliert. +- Validierungsmodell so schneiden, dass es später sowohl zentrale Meldungen als auch feldnahe Befunde speisen kann. +- JavaDoc für Validierungsgrenzen, API-Key-Vorrangregel und Nicht-Ziele von M11 ergänzen. + +### Explizit nicht Teil +- explizite Aktion **„Validieren“** +- technische Gesamtprüfungen für Pfade, Prompt-Datei, SQLite oder anlegbare Ressourcen +- schreibende Korrekturen +- Bestätigungsdialoge für Korrekturen + +### Fertig wenn +- beim Öffnen und Bearbeiten automatische Befunde erzeugt werden, +- `max.text.characters` und `max.pages` korrekt bewertet werden, +- kein implizites Speichern erfolgt, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-006 Zentralen Meldungsbereich und feldnahe rote Fehlermeldungen benutzerfreundlich anbinden + +### Voraussetzung +AP-001 bis AP-005 sind abgeschlossen. + +### Ziel +Die GUI zeigt automatische Modellabruf- und Validierungsbefunde sowohl zentral als auch feldnah in der vereinbarten Form an. + +### Muss umgesetzt werden +- Den vorhandenen Meldungsbereich funktional anbinden. +- Vier feste Meldungsstufen umsetzen: + - Info, + - Hinweis, + - Warnung, + - Fehler. +- Darstellung so umsetzen, dass nur das Präfix farbig ist und der restliche Zeilentext schwarz bleibt. +- Feldnahe rote, kleine, deutschsprachige Fehlermeldungen direkt unter problematischen Eingabefeldern anbinden. +- Sicherstellen, dass zentrale und feldnahe Befunde konsistent aus demselben Validierungs-/Meldungsmodell gespeist werden. +- Modellabruf-Ergebnisse in den Meldungsbereich integrieren, z. B. erfolgreiche Listenladung oder manueller Fallback. +- Die GUI so schneiden, dass M12 später zusätzliche Meldungen aus expliziten Gesamtprüfungen anschließen kann, ohne M11 neu zu zerlegen. +- JavaDoc/Kommentare für Meldungssemantik und Renderinggrenzen ergänzen. + +### Explizit nicht Teil +- technische Gesamtprüfung aus M12 +- schreibende Korrekturen und Sammel-Bestätigungsdialog +- automatische Prompt-Erzeugung +- DB-/Historienanzeige + +### Fertig wenn +- automatische Befunde zentral sichtbar sind, +- feldnahe Fehlermeldungen unter den betroffenen Feldern erscheinen, +- die Darstellung den vereinbarten Farbund Textregeln entspricht, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-007 Tests für Providerwechsel, Modellabruf, automatische Validierung und Meldungsdarstellung ergänzen + +### Voraussetzung +AP-001 bis AP-006 sind abgeschlossen. + +### Ziel +Der vollständige M11-Zielzustand wird automatisiert abgesichert und als stabiler Übergabestand nachgewiesen. + +### Muss umgesetzt werden +- Tests für Providerwechsel und zustandsbewahrende Providerdaten ergänzen. +- Tests für Modellabruf mit erfolgreicher Liste ergänzen. +- Tests für Modellabruf ohne nutzbare Liste und manuellen Fallback ergänzen. +- Tests für das Verwerfen eines manuellen Modellwerts ergänzen, wenn später eine echte Liste verfügbar ist und der Wert dort nicht vorkommt. +- Tests für automatische Validierung beim Öffnen und bei Eingabeänderungen ergänzen. +- Tests für die Warnschwellen von `max.text.characters` ergänzen. +- Tests dafür ergänzen, dass `max.pages` nur als Plausibilitäts-/Performance-Hinweis behandelt wird. +- Tests für Meldungsstufen und feldnahe Fehlerrückmeldungen ergänzen, soweit in der GUI-Teststrategie sinnvoll. +- Den M11-Stand abschließend auf Konsistenz, Benutzerführung und Nicht-Vorgriff auf M12 prüfen. + +### Explizit nicht Teil +- End-to-End-Gesamtprüfungen aus M12 +- schreibende Korrekturtests +- Prompt-Erzeugung +- DB-/Historienfunktionen + +### Fertig wenn +- der definierte M11-Zielzustand automatisiert abgesichert ist, +- Provider-Bedienung, Modellabruf und sofortige Validierung stabil nachgewiesen sind, +- der Stand fehlerfrei buildbar und übergabefähig ist. + +--- + +## Abschlussbewertung + +Die Arbeitspakete sind inhaltlich konsistent, widerspruchsfrei und sauber auf den Meilenstein **M11 – Provider-Bedienung, Modellabruf und automatische Validierung** zugeschnitten. Sie decken den geplanten M11-Umfang vollständig ab, ohne technische Gesamttests, Korrekturhilfen oder andere V2.0-Bausteine späterer Meilensteine vorwegzunehmen. \ No newline at end of file diff --git a/docs/workpackages/M12 - Arbeitspakete.md b/docs/workpackages/M12 - Arbeitspakete.md new file mode 100644 index 0000000..7bfe817 --- /dev/null +++ b/docs/workpackages/M12 - Arbeitspakete.md @@ -0,0 +1,429 @@ +# M12 - Arbeitspakete + +## Geltungsbereich + +Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M12 – Technische Tests, Korrekturhilfen und Windows-/Netzlaufwerksfähigkeit**. + +Die Meilensteine **M1** bis **M11** 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, GUI und Tests ändern. +- Keine Annahmen treffen, die nicht durch die bestehenden Spezifikationen, den dokumentierten V1.1-Ist-Stand, `meilensteine-v2_0.md` oder dieses Dokument gedeckt sind. +- Kein Vorgriff auf **M13+**. +- Kein Umbau bestehender M1–M11-Strukturen ohne direkten M12-Bezug. +- **„Validieren“** und **„Technische Tests ausführen“** arbeiten mit dem **aktuellen GUI-Zustand**, nicht mit dem zuletzt gespeicherten Dateistand. +- Es erfolgt **kein implizites Speichern**. +- Der Gesamttest läuft **immer vollständig** durch und bricht **nicht** beim ersten Fehler ab. +- Schreibende Korrekturen dürfen nur nach **einem gesammelten Bestätigungsdialog** erfolgen. +- Netzlaufwerke über **gemappte Laufwerksbuchstaben** sind im Windows-Kontext ausdrücklich zu unterstützen. +- Änderungen klein, fokussiert und architekturtreu halten. +- Neue Testmodelle, Prüfergebnisse, Korrekturpläne, Ports, Services und GUI-Zustände so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus klar benennbar, testbar und reviewbar sind. + +## Explizit nicht Bestandteil von M12 + +- DB-/Historienanzeige +- manueller Verarbeitungslauf aus der GUI +- EXE +- Installer +- neues Konfigurationsformat +- neue Provider über Claude und OpenAI-kompatibel hinaus +- Cost-Tracking oder Token-/Preisberechnung +- mehrseitige GUI oder weitere Tabs +- Änderungen an fachlicher Kernverarbeitung, Statussemantik, Retry-Regeln oder Persistenz-Wahrheiten +- plattformübergreifende GUI-Unterstützung außerhalb des definierten Windows-Ziels + +## Verbindliche M12-Regeln für **alle** Arbeitspakete + +### 1. Unterschied zwischen „automatischer Validierung“, Aktion „Validieren“ und „Technische Tests ausführen“ + +Ab M12 gilt verbindlich: + +- **Automatische Validierung** bleibt die in M11 definierte Hintergrundprüfung beim Öffnen und während der Bearbeitung. +- **Aktion „Validieren“** ist die explizite, **nicht schreibende, lokale Gesamtprüfung** des aktuellen Editorzustands. +- **Aktion „Validieren“** arbeitet ohne implizites Speichern und ohne schreibende Korrekturen. +- **„Technische Tests ausführen“** ist ein **vollständiger Gesamttest** des aktuellen Editorzustands. +- Der Gesamttest darf zusätzlich zu lokalen Prüfungen auch technische Prüfungen gegen Dateisystem und Provider durchführen. +- Der Gesamttest darf **korrigierende Maßnahmen** vorschlagen, aber erst nach Bestätigung durchführen. + +### 2. Vollständiger Gesamttest ohne Frühabbruch + +Ab M12 gilt verbindlich: + +- Der Gesamttest führt **alle definierten Prüfpunkte** aus. +- Ein einzelner Fehler darf **nicht** dazu führen, dass spätere Prüfpunkte ausgelassen werden. +- Alle Befunde werden gesammelt im zentralen Meldungsbereich ausgegeben. +- Die Ausführung basiert auf dem **aktuellen GUI-Zustand**, auch wenn dieser noch ungespeichert ist. + +### 3. Definierte Prüfpunkte des Gesamttests + +Ab M12 gilt verbindlich, dass der Gesamttest mindestens folgende Prüfpunkte unterstützt: + +- Konfiguration grundsätzlich validierbar +- Provider-Konfiguration prüfbar +- Base-URL/Endpoint technisch erreichbar +- API-Key vorhanden, auch wenn der effektive Wert ausschließlich über eine passende Umgebungsvariable bereitgestellt wird +- API-Key technisch akzeptiert +- Modellliste abrufbar +- ausgewähltes Modell plausibel +- Prompt-Datei vorhanden und lesbar +- Quellordner vorhanden und lesbar +- Zielordner vorhanden oder anlegbar sowie schreibbar +- SQLite-Datei bzw. SQLite-Pfad technisch nutzbar + +### 4. Schreibende Korrekturhilfen + +Ab M12 gilt verbindlich: + +- Schreibende Korrekturen werden **nicht still** durchgeführt. +- Vor schreibenden Korrekturen wird **ein gesammelter Bestätigungsdialog** angezeigt. +- Nur **sichere technische Korrekturen** dürfen angeboten werden. +- Nicht automatisch korrigierbar bleiben insbesondere: + - falscher API-Key, + - unerreichbare Base-URL, + - nicht verfügbare Modellliste, + - fachlich unplausible, aber formal zulässige Werte. + +### 5. Automatische Prompt-Erzeugung + +Ab M12 gilt verbindlich: + +- Wenn die konfigurierte Prompt-Datei fehlt, darf eine **sinnvolle Standard-Prompt-Datei** automatisch erzeugt werden. +- Diese Standard-Prompt-Datei ist **deutschsprachig**. +- Sie liegt standardmäßig **im selben Ordner wie die `.properties`-Datei**. +- Die Erzeugung ist eine **schreibende Korrektur** und unterliegt dem gesammelten Bestätigungsdialog. + +### 6. Windows- und Netzlaufwerksfähigkeit + +Ab M12 gilt verbindlich: + +- Die GUI und ihre Prüflogik unterstützen ausdrücklich **gemappte Laufwerksbuchstaben** wie `S:\` oder `H:\`. +- Solche Pfade dürfen **nicht** allein deshalb abgelehnt oder umgedeutet werden, weil dahinter technisch ein UNC-Pfad stehen könnte. +- Maßgeblich ist, dass Windows den Pfad als gültigen Pfad bereitstellt. +- Diese Regel gilt mindestens für: + - Quellordner, + - Zielordner, + - SQLite-Datei, + - Prompt-Datei. + +### 7. Grenzen von M12 + +M12 liefert die vollständige technische Prüf- und Korrekturunterstützung der V2.0-GUI, aber noch **nicht** den V2.0-Abschluss mit finaler Dokumentation und Gesamtqualitätsnachweis. + +--- + +## AP-001 Prüf- und Korrektur-Kernobjekte, Ergebnissemantik und Port-Verträge präzisieren + +### Voraussetzung +Keine. Dieses Arbeitspaket ist der M12-Startpunkt. + +### Ziel +Die M12-relevanten Prüf-, Korrektur- und Dialogmodelle werden eindeutig eingeführt, damit spätere Arbeitspakete ohne Interpretationsspielraum implementiert werden können. + +### Muss umgesetzt werden +- Neue M12-relevante Typen bzw. GUI-/Application-nahe Modelle anlegen, insbesondere für: + - explizite Validierungsanforderung, + - Gesamttestanforderung, + - Prüfpunktergebnis, + - Korrekturvorschlag, + - gesammelten Korrekturplan, + - Bestätigungsdialog-Inhalt, + - schreibenden vs. nicht schreibenden Prüfschritt, + - Ergebnis eines vollständigen Gesamttests. +- Verträge so schneiden, dass spätere Arbeitspakete unterscheiden können zwischen: + - lokalem Validierungsbefund, + - technischem Prüfbefund, + - korrigierbarem Befund, + - nicht korrigierbarem Befund, + - bestätigtem Korrekturplan, + - abgelehntem Korrekturplan. +- Outbound-Ports bzw. Application-Verträge definieren oder schärfen für: + - Provider-nahe technische Tests, + - Dateisystem-/Pfadtests, + - schreibende Korrekturhilfen, + - Prompt-Datei-Erzeugung. +- Sicherstellen, dass Domain und Application frei von JavaFX-, HTTP-, NIO- und JDBC-Bibliothekstypen bleiben. +- JavaDoc und `package-info` für Verantwortlichkeiten und Grenzen ergänzen. + +### Explizit nicht Teil +- konkrete GUI-Buttons +- konkrete Prüflogik +- konkrete Korrekturen +- Bootstrap-Verdrahtung +- Gesamttest-Orchestrierung + +### Fertig wenn +- die M12-relevanten Typen und Verträge vorhanden sind, +- Validieren, Gesamttest und Korrekturplan klar unterscheidbar modelliert sind, +- Domain und Application frei von Infrastrukturtypen bleiben, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-002 Aktion „Validieren“ als explizite, nicht schreibende Gesamtprüfung des Editorzustands umsetzen + +### Voraussetzung +AP-001 ist abgeschlossen. + +### Ziel +Die GUI bietet eine explizite Validierungsaktion, die den aktuellen Editorzustand lokal und vollständig prüft, ohne etwas zu speichern oder zu verändern. + +### Muss umgesetzt werden +- Die Aktion **„Validieren“** funktionsfähig anbinden. +- Sicherstellen, dass die Aktion mit dem **aktuellen GUI-Zustand** arbeitet, nicht mit dem zuletzt gespeicherten Dateistand. +- Keine implizite Speicherung auslösen. +- Keine schreibenden Korrekturen durchführen. +- Alle lokalen Befunde gesammelt erzeugen und dem vorhandenen Meldungsmodell zuführen. +- Relevante feldnahe Fehlermeldungen ergänzen oder schärfen. +- Eindeutige deutsche Meldungen für Fehler, Warnungen, Hinweise und Infos verwenden. +- Ausführung und Ergebnis der Aktion **„Validieren“** werden im bestehenden Log4j2-Log nachvollziehbar protokolliert. +- JavaDoc/Kommentare für die Abgrenzung zur M12-Gesamttestaktion ergänzen. + +### Explizit nicht Teil +- Provider-nahe Remote-Tests +- schreibende Korrekturen +- Bestätigungsdialog für Korrekturmaßnahmen +- Prompt-Datei-Erzeugung + +### Fertig wenn +- **„Validieren“** den aktuellen Editorzustand explizit und nicht schreibend prüfen kann, +- keine implizite Speicherung stattfindet, +- die Befunde verständlich und vollständig angezeigt werden, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-003 Provider-nahe technische Prüflogik für Endpoint, API-Key, Modellliste und Modellplausibilität umsetzen + +### Voraussetzung +AP-001 und AP-002 sind abgeschlossen. + +### Ziel +Die für V2.0 geforderten providerbezogenen technischen Prüfpunkte können kontrolliert und providerabhängig ausgeführt werden. + +### Muss umgesetzt werden +- Die technische Prüflogik für mindestens folgende providerbezogene Prüfpunkte implementieren: + - Base-URL/Endpoint erreichbar, + - API-Key vorhanden, + - API-Key technisch akzeptiert, + - Modellliste abrufbar, + - ausgewähltes Modell plausibel. +- Für den Prüfpunkt **„Modellliste abrufbar“** ausdrücklich denselben Outbound-Port und denselben Adapter verwenden, die bereits in M11 für den Modellabruf eingeführt wurden; der Prüfpunkt ist ein zusätzlicher Aufruf, keine zweite Implementierung. +- Die Prüflogik für Claude und OpenAI-kompatibel sauber kapseln. +- Beim Prüfpunkt **„API-Key vorhanden“** die bestehende Vorrangregel respektieren, sodass reine Umgebungsvariablen-Setups nicht fälschlich als fehlender API-Key bewertet werden. +- Sicherstellen, dass providerbezogene technische Fehler verständlich in das bestehende Meldungsmodell überführt werden. +- Sichere Abgrenzung zwischen: + - fehlender Voraussetzung, + - technischer Unerreichbarkeit, + - Authentifizierungsproblem, + - nicht verfügbarer Modellliste, + - unplausibler Modellauswahl. +- Provider-nahe technische Prüfungen und Dateisystem-/SQLite-Prüfungen laufen asynchron; die Ergebnisrückführung in die GUI erfolgt über den JavaFX Application Thread. +- Ausführung und Ergebnis der providernahen technischen Prüfpunkte werden im bestehenden Log4j2-Log nachvollziehbar protokolliert. +- Keine impliziten Korrekturen durchführen. +- JavaDoc/Kommentare für technische Prüfpunkte und Nicht-Ziele ergänzen. + +### Explizit nicht Teil +- schreibende Korrekturen +- Pfad-/Dateisystemtests +- Gesamttest-Orchestrierung +- Prompt-Datei-Erzeugung + +### Fertig wenn +- alle providerbezogenen technischen Prüfpunkte separat ausführbar und auswertbar sind, +- Befunde verständlich im vorhandenen Meldungsmodell ankommen, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-004 Windows-Pfadprüfung und ausdrückliche Unterstützung gemappter Laufwerke umsetzen + +### Voraussetzung +AP-001 und AP-002 sind abgeschlossen. + +### Ziel +Die GUI und ihre Prüflogik behandeln Windows-Pfade einschließlich gemappter Laufwerksbuchstaben korrekt und benutzerfreundlich. + +### Muss umgesetzt werden +- Pfadprüfungen für folgende Konfigurationswerte vervollständigen: + - Quellordner, + - Zielordner, + - SQLite-Datei, + - Prompt-Datei. +- Gemappte Laufwerksbuchstaben wie `S:\` oder `H:\` im Windows-Kontext ausdrücklich akzeptieren. +- Sicherstellen, dass solche Pfade nicht allein wegen möglicher UNC-Backings abgelehnt oder umgedeutet werden. +- Lokale Validierungs- und Testbefunde für Pfadprobleme sauber unterscheiden, insbesondere: + - fehlt, + - nicht lesbar, + - nicht schreibbar, + - ungültig, + - anlegbar. +- JavaDoc/Kommentare für Windows-/Netzlaufwerksfähigkeit und technische Grenzen ergänzen. + +### Explizit nicht Teil +- schreibende Erstellung fehlender Ressourcen +- Prompt-Datei-Erzeugung +- Gesamttest-Orchestrierung +- Provider-nahe Remote-Tests + +### Fertig wenn +- Windows-Pfade korrekt validiert werden, +- gemappte Laufwerke als gültige Pfade akzeptiert werden, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-005 Aktion „Technische Tests ausführen“ als vollständigen Gesamttest ohne Frühabbruch umsetzen + +### Voraussetzung +AP-001 bis AP-004 sind abgeschlossen. + +### Ziel +Die GUI kann einen vollständigen technischen Gesamttest des aktuellen Editorzustands ausführen und alle Befunde gesammelt zurückgeben. + +### Muss umgesetzt werden +- Die Aktion **„Technische Tests ausführen“** funktionsfähig anbinden. +- Sicherstellen, dass sie mit dem **aktuellen GUI-Zustand** arbeitet und nichts implizit speichert. +- Die definierten Prüfpunkte vollständig orchestrieren, insbesondere: + - Konfiguration grundsätzlich validierbar, + - Provider-Konfiguration prüfbar, + - Base-URL/Endpoint erreichbar, + - API-Key vorhanden, + - API-Key technisch akzeptiert, + - Modellliste abrufbar, + - ausgewähltes Modell plausibel, + - Prompt-Datei vorhanden und lesbar, + - Quellordner vorhanden und lesbar, + - Zielordner vorhanden oder anlegbar sowie schreibbar, + - SQLite-Datei bzw. SQLite-Pfad technisch nutzbar. +- Sicherstellen, dass der Gesamttest **nicht** beim ersten Fehler abbricht. +- Provider-nahe technische Prüfungen und Dateisystem-/SQLite-Prüfungen laufen asynchron; die Ergebnisrückführung in die GUI erfolgt über den JavaFX Application Thread. +- Alle Befunde gesammelt und verständlich im zentralen Meldungsbereich ausgeben. +- Deutlich kenntlich machen, dass sich das Ergebnis auf den aktuellen Editorzustand bezieht. +- Ausführung, Teilresultate und Gesamtergebnis der Aktion **„Technische Tests ausführen“** werden im bestehenden Log4j2-Log nachvollziehbar protokolliert. +- JavaDoc/Kommentare zur Gesamttest-Semantik ergänzen. + +### Explizit nicht Teil +- schreibende Korrekturen +- Sammel-Bestätigungsdialog +- Prompt-Datei-Erzeugung +- Abschlussdokumentation + +### Fertig wenn +- die Aktion **„Technische Tests ausführen“** vollständig arbeitet, +- kein Frühabbruch stattfindet, +- alle Befunde gesammelt sichtbar werden, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-006 Schreibende Korrekturhilfen und gesammelten Bestätigungsdialog einführen + +### Voraussetzung +AP-001 bis AP-005 sind abgeschlossen. + +### Ziel +Die GUI kann sichere technische Korrekturen gesammelt vorschlagen und nach einmaliger Bestätigung kontrolliert durchführen. + +### Muss umgesetzt werden +- Einen gesammelten Korrekturplan aus Prüfbefunden ableiten. +- Einen einmaligen Bestätigungsdialog implementieren, der die geplanten schreibenden Maßnahmen gesammelt anzeigt. +- Nur sichere technische Korrekturen zulassen, insbesondere dort, wo Ressourcen fehlend, aber technisch anlegbar sind. +- Sicherstellen, dass ohne Bestätigung keine schreibenden Änderungen ausgeführt werden. +- Nach Durchführung die Ergebnisse erneut verständlich in den Meldungsbereich zurückführen. +- Schreibende Korrekturen, Bestätigung und Ergebnisrückmeldung werden im bestehenden Log4j2-Log nachvollziehbar protokolliert. +- Keine stillen Auto-Korrekturen im Hintergrund zulassen. +- JavaDoc/Kommentare für die Korrekturgrenzen ergänzen. + +### Explizit nicht Teil +- providerbezogene Auto-Heilung +- Änderung fachlich riskanter Werte +- automatische Lauf-/Verarbeitungsstarts +- Abschlussdokumentation + +### Fertig wenn +- sichere technische Korrekturen gesammelt vorgeschlagen werden können, +- genau ein Bestätigungsdialog vor der Ausführung erscheint, +- ohne Bestätigung nichts geschrieben wird, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-007 Automatische deutsche Standard-Prompt-Erzeugung und anlegbare Ressourcen vervollständigen + +### Voraussetzung +AP-001 bis AP-006 sind abgeschlossen. + +### Ziel +Fehlende, technisch anlegbare Ressourcen können im Rahmen der Korrekturhilfen sinnvoll hergestellt werden; insbesondere kann eine fehlende Prompt-Datei automatisch als deutsche Standarddatei erzeugt werden. + +### Muss umgesetzt werden +- Die automatische Erzeugung einer sinnvollen **deutschsprachigen Standard-Prompt-Datei** implementieren. +- Sicherstellen, dass diese standardmäßig **im selben Ordner wie die `.properties`-Datei** angelegt wird. +- Die Erzeugung nur dann als Korrekturmaßnahme anbieten, wenn der vorgesehene Zielpfad tatsächlich beschreibbar ist. +- Wenn der Standardpfad nicht beschreibbar ist, im Bestätigungsdialog entweder einen alternativen Ablageort vorschlagen oder die Erzeugung ausdrücklich als **„nicht möglich, bitte manuell anlegen“** melden. +- Die Erzeugung in den Korrekturplan und Bestätigungsdialog aus AP-006 integrieren. +- Weitere sichere technische Korrekturen für anlegbare Ressourcen dort ergänzen, wo sie für V2.0 explizit gefordert sind, insbesondere: + - Zielordner anlegen, + - SQLite-Datei bzw. nutzbaren SQLite-Pfad vorbereiten, + - Prompt-Datei anlegen. +- Verständliche deutsche Meldungen für Erfolg, Teilfehler und Nichtdurchführbarkeit bereitstellen. +- Prompt-Erzeugung, Ressourcenkorrekturen und deren Ergebnisse werden im bestehenden Log4j2-Log nachvollziehbar protokolliert. +- JavaDoc/Kommentare für Prompt-Generierung und Ressourcenkorrektur ergänzen. + +### Explizit nicht Teil +- fachliche Prompt-Evolution über die Standarddatei hinaus +- manuelle Prompt-Bearbeitung in Spezialansichten +- neue Betriebsfeatures +- Abschlussdokumentation + +### Fertig wenn +- die Standard-Prompt-Datei automatisch erzeugt werden kann, +- die Erzeugung sauber in den Korrekturplan integriert ist, +- weitere sichere technische Ressourcenkorrekturen funktionieren, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-008 Tests für Gesamttest, Korrekturdialog, Prompt-Erzeugung und Netzlaufwerksfähigkeit ergänzen + +### Voraussetzung +AP-001 bis AP-007 sind abgeschlossen. + +### Ziel +Der vollständige M12-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen. + +### Muss umgesetzt werden +- Tests für **„Validieren“** mit aktuellem, ungespeichertem Editorzustand ergänzen. +- Tests für **„Technische Tests ausführen“** ohne Frühabbruch ergänzen. +- Tests für providerbezogene technische Prüfpunkte ergänzen, soweit innerhalb von M12 sinnvoll und stabil automatisierbar. +- Tests für den gesammelten Bestätigungsdialog ergänzen. +- Tests für sichere technische Korrekturen ergänzen. +- Tests für automatische Prompt-Erzeugung ergänzen. +- Tests für Windows-/Netzlaufwerksannahmen ergänzen, insbesondere dafür, dass gemappte Laufwerksbuchstaben korrekt akzeptiert werden. +- Sicherstellen, dass der definierte M12-Zielzustand vollständig buildbar und übergabefähig ist. + +### Explizit nicht Teil +- Abschlussdokumentation des Gesamtprojekts +- GUI-Erweiterungen aus M13+ +- DB-/Historienanzeige +- manueller Verarbeitungslauf + +### Fertig wenn +- die M12-spezifische Test-Suite grün ist, +- Gesamttest, Korrekturhilfen und Netzlaufwerksfähigkeit automatisiert abgesichert sind, +- ein fehlerfreier, übergabefähiger Stand vorliegt. + +--- + +## Abschlussbewertung + +Die Arbeitspakete sind inhaltlich konsistent, widerspruchsfrei und sauber auf den Meilenstein **M12 – Technische Tests, Korrekturhilfen und Windows-/Netzlaufwerksfähigkeit** zugeschnitten. Sie decken den vollständigen Zielumfang dieses Meilensteins ab, ohne spätere Ausbaustufen vorwegzunehmen. \ No newline at end of file diff --git a/docs/workpackages/M13 - Arbeitspakete.md b/docs/workpackages/M13 - Arbeitspakete.md new file mode 100644 index 0000000..d7aee58 --- /dev/null +++ b/docs/workpackages/M13 - Arbeitspakete.md @@ -0,0 +1,384 @@ +# M13 - Arbeitspakete + +## Geltungsbereich + +Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M13 – V2.0-Abschluss, Dokumentation und Qualitätsnachweis**. + +Die Meilensteine **M1** bis **M12** 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 Dokumentation, Build, Bootstrap, GUI, CLI, Konfigurationsbeispiele und Tests ändern. +- Keine Annahmen treffen, die nicht durch die bestehenden Spezifikationen, den dokumentierten V1.1-Ist-Stand, `meilensteine-v2_0.md` oder dieses Dokument gedeckt sind. +- Kein Vorgriff auf spätere Ausbaustufen **jenseits von V2.0**. +- Kein Umbau bestehender M1–M12-Strukturen ohne direkten M13-Bezug. +- M13 ergänzt **keine neue Produktfunktionalität**, sondern dokumentiert, stabilisiert und belegt den bereits definierten V2.0-Gesamtstand. +- GUI und headless bleiben **ein gemeinsames ausführbares JAR**; M13 erfindet keine neue Distributionsform. +- Der bestehende **headless Server-/Scheduler-Betrieb** darf weder technisch noch dokumentarisch still gebrochen werden. +- Änderungen klein, fokussiert und architekturtreu halten. +- Ein Arbeitspaket darf nur dann einen Release-Blocker beheben, wenn dieser im unmittelbar vorhergehenden Prüf-Arbeitspaket **konkret nachgewiesen und eingegrenzt** wurde. + +## Explizit nicht Bestandteil von M13 + +- DB-/Historienanzeige +- manueller Verarbeitungslauf aus der GUI +- EXE +- Installer +- neues Konfigurationsformat +- neue Provider über Claude und OpenAI-kompatibel hinaus +- Cost-Tracking oder Token-/Preisberechnung +- neue Tabs oder größere GUI-Ausbaustufen jenseits des vorhandenen V2.0-Umfangs +- neue fachliche Regeln für Dateinamensbildung, Retry, Persistenz oder Laufverhalten +- plattformübergreifender offizieller GUI-Support außerhalb des definierten Windows-Ziels + +## Verbindliche M13-Regeln für **alle** Arbeitspakete + +### 1. M13 ist ein Abschluss- und Nachweismeilenstein + +Ab M13 gilt verbindlich: + +- Der funktionale V2.0-Umfang wird **nicht erweitert**, sondern für Betrieb, Übergabe und Freigabe abgesichert. +- Änderungen in Produktionscode sind nur zulässig, wenn sie für: + - dokumentierte Start-/Betriebssemantik, + - belastbare Tests, + - Packaging-Stabilität, + - oder konkret nachgewiesene Release-Blocker + zwingend erforderlich sind. + +### 2. GUI und headless müssen gemeinsam und widerspruchsfrei beschrieben sein + +Ab M13 gilt verbindlich: + +- Die Dokumentation beschreibt den gemeinsamen Betrieb eines **einzigen ausführbaren JARs**. +- **GUI ist Standardstart**. +- **`--headless`** aktiviert den bisherigen Batch-/Scheduler-Betrieb. +- **`--config `** gilt für GUI und headless. +- Verhalten bei ungültigem oder nicht vorhandenem `--config` muss für beide Startarten klar dokumentiert und testbar belegt sein. + +### 3. `.properties` bleibt die einzige Konfigurationswahrheit + +Ab M13 gilt verbindlich: + +- Dokumentation, Konfigurationsbeispiele, GUI-Verhalten und headless Betrieb verwenden weiterhin dieselbe `.properties`-Struktur. +- M13 führt keine zweite Konfigurationswelt für GUI oder headless ein. +- Prompt-Datei und Properties-Datei bleiben getrennte Artefakte; die Prompt-Datei bleibt externe Datei. + +### 4. Headless-Abwärtskompatibilität ist release-kritisch + +Ab M13 gilt verbindlich: + +- Bestehender headless Betrieb ohne GUI-Einsatz bleibt lauffähig. +- Headless darf keine separate JavaFX-Installation voraussetzen. +- Bestehendes Default-Verhalten für headless Starts **ohne `--config`** bleibt erhalten. +- Regressionen im bisherigen Server-/Scheduler-Betrieb gelten in M13 als **Release-Blocker**. + +### 5. Windows-zentrierte GUI-Dokumentation + +Ab M13 gilt verbindlich: + +- Die GUI wird für **Windows** dokumentiert. +- Windows-spezifische Pfade und gemappte Laufwerke bleiben Teil des Zielbilds. +- Dokumentation und Beispiele dürfen diese Pfadrealität nicht still relativieren oder auf UNC-only reduzieren. + +### 6. Qualitätsnachweis basiert auf real ausgeführten Prüfungen + +Ab M13 gilt verbindlich: + +- Ein V2.0-Freigabestand wird nur auf Basis **real ausgeführter Builds und Tests** beschrieben. +- Prüf- und Freigabedokumente müssen den tatsächlich ausgeführten Stand wiedergeben. +- Reine Absichtserklärungen ohne realen Nachweis sind für M13 unzureichend. + +### 7. Release-Blocker und finale Freigabe sind getrennte Schritte + +Ab M13 gilt verbindlich: + +- Zuerst wird eine **Befundliste** mit konkret eingegrenzten Restthemen erstellt. +- Danach dürfen nur die dokumentierten Release-Blocker gezielt behoben werden. +- Erst danach erfolgt eine finale Gesamtprüfung und Freigabedokumentation. + +--- + +## AP-001 V2.0-Betriebs- und Startdokumentation für GUI und headless konsolidieren + +### Voraussetzung +Keine. Dieses Arbeitspaket ist der M13-Startpunkt. + +### Ziel +Der V2.0-Betrieb wird für Benutzer und Betreiber klar, widerspruchsfrei und vollständig beschrieben. + +### Muss umgesetzt werden +- README bzw. vorhandene Start-/Betriebsdokumentation gezielt auf den V2.0-Stand erweitern. +- Mindestens folgende Punkte klar und konsistent dokumentieren: + - gemeinsames ausführbares JAR, + - GUI als Standardstart, + - `--headless`, + - `--config `, + - Exit-Code-Modell von V2.0 mit `0` für normale erfolgreiche GUI-/headless-Beendigung und `1` für harte Start-, Bootstrap-, Konfigurations- oder Initialisierungsfehler, + - Verhalten bei fehlender oder ungültiger Konfiguration, + - Verhalten bei GUI-Startfehlern, + - Windows-Bezug und gemappte Laufwerke. +- Dokumentieren, dass V2.0 **keinen** manuellen Verarbeitungslauf aus der GUI enthält. +- Dokumentieren, dass die GUI in V2.0 der Konfiguration, Validierung und technischen Prüfung dient. +- Terminologie zwischen README, JavaDoc, GUI-Texten und Startsemantik vereinheitlichen. + +### Explizit nicht Teil +- neue Produktfunktionalität +- vollständige Testergänzung +- Release-Blocker-Befundliste +- Freigabedokument + +### Fertig wenn +- der V2.0-Betrieb für GUI und headless klar dokumentiert ist, +- die Startoptionen widerspruchsfrei beschrieben sind, +- die Dokumentation zum realen Verhalten des aktuellen Codes passt, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-002 Konfigurationsbeispiele, Standardvorlage und Prompt-Bezug für den V2.0-Endstand konsolidieren + +### Voraussetzung +AP-001 ist abgeschlossen. + +### Ziel +Die im Repository enthaltenen Konfigurations- und Prompt-Beispiele passen konsistent zum realen V2.0-Verhalten der GUI und des headless Betriebs. + +### Muss umgesetzt werden +- Vorhandene Konfigurationsbeispiele prüfen und auf den V2.0-Stand bringen. +- Sicherstellen, dass mindestens nachvollziehbar und konsistent abgebildet sind: + - mehrere Provider-Konfigurationen in einer Datei, + - genau ein aktiver Provider, + - GUI-relevante und headless-relevante Konfigurationswerte, + - `prompt.template.file`, + - konservative Default-Werte, + - V2.0-relevante Grenz- und Warnparameter. +- Die Standardvorlage für **„Neue Konfiguration“** und die dokumentierten Konfigurationsbeispiele semantisch aufeinander abstimmen. +- Sicherstellen, dass die Dokumentation den gemeinsamen Standardpfad `config/application.properties` relativ zum Arbeitsverzeichnis konsistent beschreibt, wo dies für GUI-Speichervorschläge und headless Standardverhalten relevant ist. +- Den Umgang mit `.bak`-Sicherungen beim Überschreiben bestehender `.properties`-Dateien konsistent dokumentieren. +- Den Umgang mit automatisch erzeugbarer deutscher Standard-Prompt-Datei dokumentieren. +- Sicherstellen, dass Dateinamen, Pfadbeispiele und Properties-Namen zum tatsächlichen Code passen. + +### Explizit nicht Teil +- neue GUI-Funktionalität +- größere Prompt-Überarbeitung jenseits des dokumentierten Standardfalls +- Release-Befundliste +- Freigabedokument + +### Fertig wenn +- Konfigurationsbeispiele und Standardvorlage konsistent zum V2.0-Stand sind, +- Prompt-Bezug und automatische Prompt-Erzeugung nachvollziehbar beschrieben sind, +- Properties-Namen und Beispielwerte zum realen Code passen, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-003 Regressionstests für headless Abwärtskompatibilität, Startoptionen und Konfigurationspfade ergänzen + +### Voraussetzung +AP-001 und AP-002 sind abgeschlossen. + +### Ziel +Die kritischen V2.0-Risiken im bisherigen Server-/Scheduler-Betrieb werden automatisiert abgesichert. + +### Muss umgesetzt werden +- Regressionstests für den headless Betrieb ergänzen oder vervollständigen, insbesondere für: + - headless Start ohne `--config` mit bestehendem Default-Verhalten, + - headless Start mit gültigem `--config`, + - headless Start mit ungültigem bzw. nicht vorhandenem `--config` als harter Startfehler, + - keine unzulässige Abhängigkeit von separater JavaFX-Installation im headless Pfad. +- Tests für Parsing und Semantik von `--headless` und `--config` ergänzen. +- Tests für das verbindliche Exit-Code-Modell im headless Pfad ergänzen, soweit dies stabil automatisierbar ist. +- Sicherstellen, dass bestehender Batch-/Scheduler-Betrieb durch V2.0 nicht still verändert wird. +- Relevante Start- und Fehlermeldungssemantik mit absichern, soweit dies stabil automatisierbar ist. + +### Explizit nicht Teil +- GUI-interaktive Bedienpfade +- Release-Befundliste +- Freigabedokument +- neue Produktfunktionalität + +### Fertig wenn +- die headless Abwärtskompatibilität belastbar automatisiert abgesichert ist, +- Startoptionen und Konfigurationspfade regressionssicher geprüft werden, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-004 GUI-Smoke- und Interaktionstests für den V2.0-Kernumfang vervollständigen + +### Voraussetzung +AP-001 bis AP-003 sind abgeschlossen. + +### Ziel +Die zentralen V2.0-GUI-Pfade sind automatisiert so abgesichert, dass Bedienung, Startzustände und wichtige Fehlersituationen regressionssicher werden. + +### Muss umgesetzt werden +- GUI-nahe Tests für die zentralen V2.0-Bedienpfade ergänzen oder vervollständigen, insbesondere für: + - leerer GUI-Start ohne geladene Konfiguration, + - Willkommenstext und sichtbare Grundaktionen, + - `--config` im GUI-Start mit gültiger Datei, + - `--config` im GUI-Start mit nicht vorhandener Datei inklusive Fehlermeldung und Fallback auf leeren GUI-Zustand, + - Dirty-State-Kennzeichnung, + - Schutzdialoge bei ungespeicherten Änderungen, + - Arbeiten von **„Validieren“** und **„Technische Tests ausführen“** auf dem aktuellen Editorzustand. +- Soweit stabil automatisierbar, auch zentrale Meldungs- und Validierungsflüsse mit absichern. +- Sicherstellen, dass die Tests den echten V2.0-Kernumfang prüfen und keine späteren GUI-Ausbaustufen vorwegnehmen. + +### Explizit nicht Teil +- DB-/Historienansicht +- manueller Verarbeitungslauf +- Release-Befundliste +- Freigabedokument + +### Fertig wenn +- die zentralen V2.0-GUI-Pfade automatisiert abgesichert sind, +- GUI-Start, Fallback-Verhalten und Schutzdialoge regressionssicher geprüft werden, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-005 Build-, Packaging- und Artefaktdokumentation für das gemeinsame V2.0-JAR vervollständigen + +### Voraussetzung +AP-001 bis AP-004 sind abgeschlossen. + +### Ziel +Das gemeinsame ausführbare JAR für GUI und headless ist nachvollziehbar beschrieben und sein Build-/Packaging-Verhalten ist für die Übergabe ausreichend dokumentiert. + +### Muss umgesetzt werden +- Dokumentation für Build und Packaging des gemeinsamen V2.0-JAR ergänzen oder schärfen. +- Mindestens folgende Punkte nachvollziehbar beschreiben: + - gemeinsames ausführbares JAR, + - integrierte JavaFX-Laufzeit im GUI-Fall, + - keine EXE und kein Installer in V2.0, + - headless Start ohne separate JavaFX-Installation, + - relevante Build-Kommandos, + - Artefakterzeugung und Startbeispiele. +- Prüfen, ob bestehende Packaging-/Build-Hinweise oder Konfigurationsbeispiele widersprüchlich oder veraltet sind, und diese gezielt bereinigen. +- Nur dann produktiven Build-Code anfassen, wenn für eine korrekte V2.0-Dokumentation ein nachweisbarer Widerspruch zum realen Packaging-Verhalten besteht. + +### Explizit nicht Teil +- neue Distributionsformate +- EXE oder Installer +- Release-Befundliste +- Freigabedokument + +### Fertig wenn +- Build- und Packaging-Verhalten des gemeinsamen JAR nachvollziehbar dokumentiert ist, +- veraltete oder widersprüchliche Angaben bereinigt sind, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-006 Integrierte Gesamtprüfung des V2.0-Stands und belastbare Befundliste erstellen + +### Voraussetzung +AP-001 bis AP-005 sind abgeschlossen. + +### Ziel +Der V2.0-Gesamtstand wird ganzheitlich geprüft, und es entsteht eine belastbare Befundliste, aus der ausschließlich reale Release-Blocker ableitbar sind. + +### Muss umgesetzt werden +- Den vollständigen V2.0-Projektstand ganzheitlich gegen die bestehenden Spezifikationen, den V1.1-Ist-Stand und `meilensteine-v2_0.md` prüfen. +- Tatsächlich ausführen und auswerten: + - vollständigen Maven-Reactor-Build, + - relevante Test-Suiten, + - headless Smoke-/Regressionstests, + - GUI-nahe Smoke-/Interaktionstests, soweit im Projekt vorhanden, + - Prüfung der Konfigurations- und Dokumentationsbeispiele. +- Die Ergebnisse in einer im Repository verbleibenden **Befundliste** dokumentieren. +- Befunde klar klassifizieren, insbesondere in: + - Release-Blocker, + - nicht blockierende Restpunkte, + - bewusst außerhalb von V2.0 liegende Themen. +- Sicherstellen, dass nur **konkret nachgewiesene** Release-Blocker für das Folge-Arbeitspaket in Betracht kommen. + +### Explizit nicht Teil +- Behebung der gefundenen Blocker +- neue Produktfunktionalität +- finale Freigabedokumentation + +### Fertig wenn +- die integrierte Gesamtprüfung real durchgeführt und dokumentiert wurde, +- eine belastbare Befundliste im Repository vorliegt, +- Release-Blocker klar und eng eingegrenzt sind, +- der Stand weiterhin fehlerfrei buildbar bleibt. + +--- + +## AP-007 Nachgewiesene V2.0-Release-Blocker gezielt beheben + +### Voraussetzung +AP-006 ist abgeschlossen. + +### Ziel +Die im vorherigen Arbeitspaket konkret dokumentierten Release-Blocker werden gezielt und ohne Scope-Ausweitung beseitigt. + +### Muss umgesetzt werden +- Ausschließlich die in der Befundliste aus AP-006 dokumentierten **Release-Blocker** beheben. +- Änderungen strikt auf die tatsächlich nachgewiesenen Blocker begrenzen. +- Betroffene Tests, Dokumentation und Konfigurationsbeispiele mitziehen, soweit dies zur sauberen Behebung erforderlich ist. +- Sicherstellen, dass durch die Behebung keine Themen späterer Ausbaustufen still vorweggenommen werden. +- Den relevanten Build-/Testumfang erneut ausführen und grün bekommen. + +### Explizit nicht Teil +- Behebung nicht blockierender Restpunkte +- neue Features +- finaler Freigabenachweis + +### Fertig wenn +- die dokumentierten Release-Blocker gezielt behoben sind, +- die relevanten Builds und Tests erneut erfolgreich laufen, +- keine Scope-Ausweitung auf spätere Ausbaustufen stattgefunden hat, +- ein fehlerfreier, übergabefähiger Stand vorliegt. + +--- + +## AP-008 Finale V2.0-Gesamtprüfung und Freigabedokumentation erstellen + +### Voraussetzung +AP-007 ist abgeschlossen. + +### Ziel +Der V2.0-Gesamtstand wird abschließend geprüft und als freigabefähiger Stand nachvollziehbar dokumentiert. + +### Muss umgesetzt werden +- Die integrierte Gesamtprüfung nach den Blockerbehebungen erneut durchführen. +- Tatsächlich ausführen und bewerten: + - vollständigen Maven-Reactor-Build, + - maßgebliche Test-Suiten, + - headless Smoke-/Regressionstests, + - GUI-nahe Smoke-/Interaktionstests, + - Konfigurations- und Dokumentationsbeispielprüfung. +- Eine im Repository verbleibende **Freigabedokumentation** erstellen, die mindestens festhält: + - geprüften Stand, + - ausgeführte Prüfungen, + - Build-/Test-Ergebnisse, + - offene nicht blockierende Restpunkte, + - klare Freigabeaussage für V2.0. +- Sicherstellen, dass die Freigabedokumentation keine Aussagen trifft, die nicht durch reale Prüfungen gedeckt sind. + +### Explizit nicht Teil +- neue Produktfunktionalität +- weitere Qualitätskampagnen jenseits des V2.0-Abschlusses +- spätere Ausbaustufen V2.1+ + +### Fertig wenn +- der V2.0-Gesamtstand erneut vollständig geprüft wurde, +- eine belastbare Freigabedokumentation im Repository vorliegt, +- der V2.0-Stand als freigabefähig nachvollziehbar beschrieben ist, +- ein fehlerfreier, übergabefähiger Abschlussstand vorliegt. + +--- + +## Abschlussbewertung + +Die Arbeitspakete sind inhaltlich konsistent, widerspruchsfrei und sauber auf den Meilenstein **M13 – V2.0-Abschluss, Dokumentation und Qualitätsnachweis** zugeschnitten. Sie decken den vollständigen Zielumfang dieses Abschlussmeilensteins ab, ohne spätere Ausbaustufen vorwegzunehmen. \ No newline at end of file diff --git a/docs/workpackages/M9 - Arbeitspakete.md b/docs/workpackages/M9 - Arbeitspakete.md new file mode 100644 index 0000000..b20160f --- /dev/null +++ b/docs/workpackages/M9 - Arbeitspakete.md @@ -0,0 +1,381 @@ +# 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 ` + +Ab M9 gilt verbindlich: + +- **`--config `** 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 ` 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 ` 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 `** 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 ` 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 `** 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 ` 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. \ No newline at end of file