Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,132 @@
# Phase 07 — Chatbot
**Dauer:** 4-6 Wochen
**Tasks:** 3 (MVP → V1 → V2)
**Ziel:** Den heute hart deaktivierten Chatbot (`apps/web/app/modules/chatbot/lib/chatbot-stream.server.ts:41` returnt unconditionally `503 "AI provider runtime is not configured yet."`) in einen modularen, SaaS-bewussten, capability-gestaffelten Chatbot verwandeln. Drei Ausbaustufen, jede für sich produktionsreif. Nicht alles auf einmal — saubere Trennung damit Tenants schon nach MVP echten Wert haben, V1 die Risk-Surface durch Allow-List + Audit klein hält und V2 erst dann RAG + Cost-Tracking zünden lässt, wenn die dafür nötige Infrastruktur (Phase 04 und Phase 05) wirklich steht.
## Warum 3-stufig
- **Wert früh liefern.** MVP (Master-Switch + 3 read-only Capabilities) ist in 3-4 Tagen baubar und gibt Tenants sofort einen Self-Service-Helfer für Produktfragen, KB-Suche und Account-Basics — ohne dass wir RAG-Infrastruktur, Cost-Quotas oder Per-User-Permissions brauchen.
- **Risk inkrementell aufdrehen.** Schreibende und admin-nahe Tools (data_write, workflow_trigger, admin_actions, external_tools) kommen erst in V1, dann hinter Per-User-Allow-List + Per-Capability Rate-Limits + Audit-Log. Wir öffnen die Angriffsfläche nicht in einem Rutsch.
- **Schwere Abhängigkeiten kapseln.** V2 (RAG + Cost-Tracking) braucht Phase 04 (`meilisearch.md`, `vector-store.md`, `embedding-pipeline.md`) und Phase 05 (`ai-cost-phase-1/2/3.md`) komplett. Würden wir das in MVP packen, müsste der ganze Chatbot warten bis Search/RAG steht — Wert-Lieferung würde 8+ Wochen verschoben.
- **Klare Rollback-Punkte.** Jede Stufe hat einen eigenen Feature-Flag-Subschalter (`chatbot`, `chatbot.user_allowlist`, `chatbot.rag`). Wenn V1 oder V2 Probleme machen, lässt sich die jeweilige Stufe deaktivieren ohne MVP zu reißen.
## Modulares Design (gilt über alle 3 Stufen)
```
┌─────────────────────────────────────────────────────────────────┐
│ Tenant-Settings UI (/app/$tenant/settings/ai-chatbot) │
│ - Master-Switch (Feature-Flag chatbot) │
│ - Capability-Matrix (8 Toggles, V1+) │
│ - User-Allow-List (V1+) + Per-User-Overrides (V2) │
└──────────────┬──────────────────────────────────────────────────┘
│ liest/schreibt
▼
┌─────────────────────────────────────────────────────────────────┐
│ TenantChatbotAccess (Prisma, ab V1) + │
│ Feature-Flags-Engine (Task #53, ab MVP) │
└──────────────┬──────────────────────────────────────────────────┘
│ enforced durch
▼
┌─────────────────────────────────────────────────────────────────┐
│ Capability-Resolver (lib/chatbot-capabilities.server.ts) │
│ - resolveCapabilitiesForUser({tenantId, userId}) │
│ - returnt erlaubte Capability-Liste │
└──────────────┬──────────────────────────────────────────────────┘
│ konfiguriert
▼
┌─────────────────────────────────────────────────────────────────┐
│ chatbot-stream.server.ts (refactored) │
│ - System-Prompt-Builder (Tenant + User + RAG-Context ab V2) │
│ - Capability-gated Tool-Registry (3 in MVP, 8 in V1+) │
│ - High-Risk-Tool-Audit (V1+) │
│ - Cost-Tracking pro Tool-Call (V2) │
└─────────────────────────────────────────────────────────────────┘
```
**Die 8 Capabilities (final in V1, vorbereitet ab MVP):**
| ID | Name | Risk | MVP | V1 | V2 |
|---|---|---|---|---|---|
| `qa_help` | Produktfragen via Static-Docs | low | ✅ | ✅ | ✅ |
| `kb_search` | Tenant-KB-Search (Postgres-FTS/Meilisearch) | low | ✅ | ✅ | ✅ |
| `account_info` | Plan, Credits, simple Account-Queries | low | ✅ | ✅ | ✅ |
| `data_read` | Tenant-Daten lesen (CRM, Rows, Notes) | medium | — | ✅ | ✅ |
| `data_write` | Tenant-Daten schreiben | high | — | ✅ | ✅ |
| `workflow_trigger` | Workflows starten | high | — | ✅ | ✅ |
| `admin_actions` | Tenant-Admin-Operationen | high | — | ✅ | ✅ |
| `external_tools` | MCP-Tools, externe Integrationen | high | — | ✅ | ✅ |
## Task-Reihenfolge
| # | Task-ID | Datei | Estimated | Parallelisierbar |
|---|---|---|---|---|
| 1 | #13 | `chatbot-mvp.md` | 3-4 Tage | — (Foundation) |
| 2 | #14 | `chatbot-v1.md` | 1 Woche | — (braucht MVP) |
| 3 | #15 | `chatbot-v2.md` | 2 Wochen | — (braucht V1 + Phase 04 + Phase 05 Cost) |
**Sequenziell.** Keine Parallelisierung innerhalb der Phase, weil jede Stufe auf der Capability-Architektur der vorigen aufbaut. Externe Parallelität (Phase 04, Phase 05) erfolgt vor V2-Start.
## Dependency-Graph (extern + intern)
```
Phase 05 feature-flags.md (#53) ───┐
│
▼
#13 chatbot-mvp.md
(Master-Switch + 3 Capabilities)
│
▼
Phase 10 audit-compliance-export.md ─┐
│
▼
#14 chatbot-v1.md
(Allow-List + 8 Capabilities + Audit)
│
Phase 04 meilisearch.md (#48) ──┐ │
Phase 04 vector-store.md (#49) ─┤ │
Phase 04 embedding-pipeline.md (#50)─┤
Phase 05 ai-cost-phase-1.md (#54) ──┤
Phase 05 ai-cost-phase-2.md (#55) ──┤
Phase 05 ai-cost-phase-3.md (#56) ──┤
▼
#15 chatbot-v2.md
(RAG + Cost-Tracking + Per-User-Overrides)
```
## Phase Done-Definition
Diese Phase ist `completed` wenn:
- [ ] Alle 3 Tasks `completed` in `PROGRESS.md`
- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün
- [ ] `chatbot-stream.server.ts` enthält keinen unconditionalen 503-Return mehr; Routing geht über Feature-Flag + Capability-Resolver
- [ ] `apps/web/app/routes/app.$tenant/settings/ai-chatbot.tsx` (oder gleichwertig) bietet Master-Switch, Capability-Matrix und User-Allow-List
- [ ] `TenantChatbotAccess` Prisma-Model ab V1 vorhanden inkl. Migration
- [ ] Alle 8 Capabilities sind als LLM-Tools registriert und werden capability-gated exposed
- [ ] AuditEvent wird für jeden High-Risk-Tool-Call geschrieben (V1+)
- [ ] AICostEvent wird pro Chatbot-Generation mit `capability`-Feld geschrieben (V2)
- [ ] RAG-Retrieval (Top-K=5 default) ist im System-Prompt-Builder integriert und nutzt `chatbot_rag`-Collection (V2)
- [ ] Doku-Files: `docs/features/chatbot.md`, `docs/features/chatbot-capabilities.md`, `docs/operations/chatbot-rollout.md`
- [ ] Staging-Deployment auf `agent/phase-07-final`: Tenant-A hat MVP-Setup, Tenant-B hat V1 mit Allow-List, Tenant-C hat V2 mit RAG — jeweils smoke-getestet
- [ ] Tenant-Isolation-Test: Chatbot von Tenant A kann via keiner Capability auf Daten von Tenant B zugreifen (positiv- und negativ-Test pro Capability)
- [ ] Indirect-Prompt-Injection-Test: KB-Article mit eingebettetem Tool-Aufruf wird nicht ausgeführt (siehe Security-Notes der Detail-MDs)
- [ ] `gsd-code-reviewer`-Subagent hat alle Phase-07-Commits reviewed; Findings adressiert
- [ ] Phase-Summary in dieser README.md ergänzt
## Phase Summary
_(Wird nach Abschluss der Phase vom ausführenden Agent ergänzt.)_
### Lessons Learned
_(Wird nach Abschluss ergänzt — insbesondere: Tool-Call-Token-Budget-Findings, RAG-Top-K-Tuning, Capability-UI-UX-Erkenntnisse, Audit-Log-Volumen pro High-Risk-Tool, Prompt-Injection-Mitigationen die tatsächlich gegriffen haben.)_
## Verweise
- Detail-MD-Template: `../DETAIL-MD-TEMPLATE.md`
- Agent-Workflow: `../AGENT-INSTRUCTIONS.md`
- Execution-Order: `../00-execution-order.md`
- Live-Status: `../PROGRESS.md`
- Vorgänger-Phasen: `../04-search-rag/README.md`, `../05-business-features/README.md`
- Nachfolger-Phase: `../08-mobile-cli-storybook-sdk/README.md`