Meilensteine für V2.0 in der Pre-Version angelegt

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.