Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/designer-briefs/P13-ki-layer.md
T

58 lines
5.7 KiB
Markdown

# Designer-Brief · P13 — KI-Layer
> ⛔ **ABGELÖST (KI→MCP-Pivot, [[AD-26]], 2026-06-22):** Phase 13 (KI-Layer) entfällt — kein KI-Settings-/AI-Credits-Screen. HiveGrid wird MCP-Server; die einzige zugehörige UI ist die Verbindungs-/Settings-Ansicht in **[[VD-MCP]]**. Brief unten = historisch.
**Phase:** 13/21 · **Modul:** M18 · **Owner-Dev:** Raffael (R-P13) · **Designer:** David (D-KI, Paket Mo 06.07. Compose)
**Quellen:** `ROADMAP.md` §Phase 13 · `ENTITY-MODEL.md` Domäne 7 (Automation & KI) · `SCREEN-MAP.md` §6 (KI-Settings / AI-Credits) · `_bmad-output/specs/M18-ki-layer.md` (HiveMind/RAG/Whisper-Teile → v2)
**Subframe:** Pflicht je Route. Archetypen aus D0 (A6 Settings/Connection, KPI+Charts). Compose-Paket — wenig Bespoke.
> 🟡 **v1-Grenze (Scope-Schnitt 11.06.):** HiveMind, RAG/Embeddings, Whisper-Transkription und AlephAlpha sind **v2** (→ P25). v1 baut nur den produktiven **EU-LLM-Gateway** (Mistral La Plateforme primär, Provider-Abstraktion), Token-/AiCredits-Tracking mit harten + Drossel-Limits und die **Andock-Adapter** als Muster. Kein RAG-Chat-UI, kein Whisper-Aufnahme-UI, kein HiveMind-Assistent in v1.
> 🔴 **Sprach-zu-Automation gehört sichtbar in den Flow-Editor (P12)** — P13 liefert nur das Gateway dahinter. EU-Datenresidenz wird überall im Klartext kommuniziert; keine US-Kern-Abhängigkeit.
## Was dieses Modul tut (Kurzfassung)
Der EU-only KI-Unterbau: ein Multi-Provider-LLM-Gateway, das Tokens trackt, gegen das lokale **AiCredits**-Konto bucht und Soft-/Hard-Limits durchsetzt. Sichtbare v1-Oberflächen sind die **KI-Settings** (Use-Case-Toggles, Modell-Wahl, EU-Klartext) und das **AI-Credits/Usage-Dashboard**. Die KI selbst wird über v1-Use-Cases konsumiert (primär Sprach-zu-Automation in P12, plus Lead-Zusammenfassung/Programm-Hilfe/Stuck-Vorschläge als KI-Widgets in bestehenden Detail-/Dashboard-Views). Promptfoo testet die ausgelieferten Funktionen.
## Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
|---|---|---|
| **KI-Settings** [`/admin/ai`] | Use-Case-Toggles (je v1-Use-Case ein/aus) · Modell-Wahl (Mistral Large/Small je Use-Case) · Token-Limit pro Monat · **EU-Datenresidenz-Klartext-Block** · Hinweis Plan-Erweiterung extern | A6 |
| **AI-Credits / Usage** [`/admin/usage/ai`] | Saldo (current_balance_tokens) · Verbrauch je Use-Case (Donut) · Verlauf über Zeit (Linie) · Top-User · **80%-Soft-Limit-Warnbanner** · Hochrechnung Monatsende · Plan-Limit-Anzeige | KPI + Charts |
| **Soft-/Hard-Limit-Banner** [global] | 80%-Banner („KI-Budget zu 80% verbraucht …") · 100%-Klartext bei Aufruf-Versuch („KI-Budget erschöpft, Erweiterung auf hivegrid.de/pricing") · kritische Funktionen (Klartext-Diagnostik) bleiben aktiv | Banner (A7/Topbar) |
| KI-Widget: Lead-Zusammenfassung [im Kontakt-/Lead-Detail] | On-demand-Generierung des Pre-Termin-Briefs · Quelle Activity-Stream/Custom-Felder/Form-Submissions · Cache-Hinweis · Klartext bei Provider-Down | Compose (in A3-Detail) |
| KI-Widget: Stage-Stuck-Vorschläge [im Dashboard] | Wöchentlich generierte Vorschläge für Stuck-Deals/-Projekte · Quick-Action-Buttons (Anrufen/Email) · **KI-Vorschlag-Kennzeichnung** | Compose (in Dashboard) |
| Programm-Hilfe-Einstieg [In-App, klein] | Frage-Eingabe → KI-Antwort (Klartext + Deep-Link) · Conversation-Historie pro User · **„KI-Vorschlag"-Markierung** bei Fallback-Diagnostik | A5-klein / Drawer |
*(RAG-Chat, Whisper-Aufnahme-UI, HiveMind-Assistent, Bring-Your-Own-Key → v2.)*
## Geplante Features (muss abgedeckt sein)
- [ ] EU-LLM-Gateway (Mistral La Plateforme primär, Provider-Abstraktion für zweiten EU-Provider → v2) mit Token-Tracking je Aufruf
- [ ] AiCredits-Buchung: AiTokenUsage je Aufruf, Aggregat-Abzug, Soft-Limit (80% Banner + Admin-Mail), Hard-Limit (100% Pause außer kritische Funktionen, Monats-Reset)
- [ ] KI-Settings pro Tenant: aktivierte Use-Cases, Default-Modelle, Monats-Token-Limit, EU-Residenz-Klartext
- [ ] Usage-Dashboard: Verbrauch je Use-Case (Donut), Zeitverlauf, Top-User, Forecast, Plan-Limit
- [ ] v1-Use-Cases sichtbar: Sprach-zu-Automation (Gateway für P12), Lead-Zusammenfassung, Programm-Hilfe/FAQ, Klartext-Diagnostik-Fallback, Stage-Stuck-Vorschläge
- [ ] Sicherheits-Layer-Wirkung im UI: schreibende KI-Aktionen erfordern Bestätigungs-Workflow (Action-Boundary); KI-Fallback-Outputs als „KI-Vorschlag" markiert
- [ ] Klartext bei Provider-Down / Limit-erreicht statt technischer Fehler
- [ ] Promptfoo-Eval-Suite deckt ausgelieferte KI-Funktionen ab (CI-Pflicht, kein UI)
- [ ] v2-Andock-Adapter als Muster vorhanden: `RetrievalProvider`-Interface, Outbox-Index-Events (via P11), Bestätigungs-Grenze (kein v1-UI nötig)
- [ ] Datenmodell persistiert: LlmGatewayProvider/Model, AiSettings, AiCredits, AiTokenUsage, Conversation/Message, GeneratedObject (Domäne 7)
## Benötigte UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
Settings-Sektionen mit Toggle-Zeilen (Klartext-Beschreibung), Modell-Auswahl-Dropdowns je Use-Case, Token-Limit-Eingabe, EU-Datenresidenz-Klartext-Block, KPI-Kacheln (Saldo/Verbrauch/Forecast), Donut-Chart (Verbrauch je Use-Case), Linien-Chart (Verlauf), Top-User-Liste, Soft-/Hard-Limit-Warnbanner (stapelbar mit Topbar-System), KI-Vorschlag-Badge/Kennzeichnung, On-demand-Generieren-Button mit Lade-Zustand, Conversation-Historie-Liste, Bestätigungs-Dialog für schreibende KI-Aktionen, Klartext-Provider-Down-Hinweis, Empty-/Loading-/Permission-Denied-States.
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
- [ ] Neue UI/UX-Entscheidungen:
- [ ] Subframe-Screen-Link(s):
- [ ] Offene Fragen an Dev:
## Dev-Nachzug (wir nach Davids Delta)
- [ ] Spec/ENTITY-MODEL an Davids Entscheidungen angepasst:
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen:
- [ ] Plane-Ticket (R-P13) aktualisiert: