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

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.