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

5.7 KiB

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: