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“
• M12-spezifische Gesamtprüfungs- und Korrekturpfade rund um die Aktion „Modelle neu laden“ (die Aktion selbst gehört zu M11 als manueller Wieder-Auslöser des bereits vorhandenen Modellabrufs)
• 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. API-Key-Herkunft und Env-Var-Schutz

Ab M11 gilt verbindlich:

• Die GUI macht die Herkunft des effektiven API-Keys für den Benutzer sichtbar, insbesondere wenn eine providerspezifische Umgebungsvariable aktuell Vorrang vor dem Property-Wert hat.
• Das API-Key-Eingabefeld ist ein normales, unmaskiertes Textfeld (pragmatische V2.0-Entscheidung, keine Sicherheitsbehauptung).
• Ein leeres API-Key-Feld darf einen bereits vorhandenen Property-Wert nicht stillschweigend löschen, wenn keine Umgebungsvariable greift. Stattdessen bleibt der Property-Wert erhalten und eine deutliche Warnung wird angezeigt.

8. 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.
• 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.
• 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.
• 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.
• API-Key-Herkunftsanzeige (Umgebungsvariable vs. Property-Wert) in den zentralen Meldungsbereich und, soweit feldnah sinnvoll, unter das API-Key-Feld anbinden.
• 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 automatische 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.