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