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