# Phase 07 — Chatbot — VERIFICATION **Verifier:** general-purpose (read-only) **Date:** 2026-05-16 **Files reviewed:** `README.md`, `chatbot-mvp.md`, `chatbot-v1.md`, `chatbot-v2.md` **Overall verdict:** **PASS mit Auflagen** — Plan ist im Kern stimmig, vollständig, sequenziell sauber begründet. Einige nicht-blockierende Lücken bei Chat-History, Reset-Funktion, Multilingual sowie eine kleinere Inkonsistenz zwischen Approach-Text und Implementation-Step bei der V1-Resolver-Override-Semantik. --- ## 1) Template-Konformität (DETAIL-MD-TEMPLATE.md, 15 Sections) | Section | mvp.md | v1.md | v2.md | |---|---|---|---| | Frontmatter (Status/Task-ID/Phase/Effort/Owner) | OK | OK | OK | | Problem | OK | OK | OK | | Depends on | OK | OK | OK | | Blocks | OK | OK | OK | | Approach | OK | OK | OK | | Implementation Steps | OK (11) | OK (12) | OK (13) | | Test Requirements | OK | OK | OK | | Acceptance Criteria | OK | OK | OK | | Rollback Strategy | OK | OK | OK | | Security Notes | OK | OK | OK | | Subagent Recommendations | OK | OK | OK | | Staging-Deployment-Steps | OK | OK | OK | | Deviations from Plan | OK | OK | OK | | Progress Log | OK | OK | OK | | Lessons Learned | OK | OK | OK | **Reihenfolge:** Stimmt in allen 3 Files exakt mit Template überein. **Frontmatter-Detail v1.md:** Leerzeile zwischen `Estimated Effort` und `Owner` (kosmetisch, nicht template-konform aber irrelevant). README.md folgt — wie für Phase-README üblich — nicht dem Detail-Template (richtig so). --- ## 2) Dependencies konsistent **MVP:** - Depends on `05-business-features/feature-flags.md` (#53) — **OK.** Begründung im Text sauber (Multi-Tenant-Persistence, SharedStore-Cache). - Blocks: V1 + V2 — **OK.** **V1:** - Depends on: MVP + `ai-cost-phase-2.md` (#55) + `10-compliance-polish/audit-compliance-export.md` (#67) — **OK, vollständig.** - README-Dep-Graph zeigt #55 nicht als V1-Input — **Inkonsistenz:** Der README-Graph führt nur „Phase 10 audit-compliance-export.md" als externe V1-Dep, vergisst `ai-cost-phase-2.md` (#55, Rate-Limits). Empfehlung: im README-Graph eine Linie `Phase 05 ai-cost-phase-2.md (#55) → #14` ergänzen, damit Graph zur Detail-MD passt. **Minor.** - Blocks: V2 — **OK.** **V2:** - Depends on: V1 + `meilisearch.md` (#48) + `vector-store.md` (#49) + `embedding-pipeline.md` (#50) + `ai-cost-phase-1/2/3.md` (#54/55/56) — **OK, alle 4 Phase-04-Files** (technisch: 3 Phase-04-Files; Meilisearch ist Hybrid-Pre-Filter, vector-store + embedding-pipeline sind Pflicht) **plus alle 3 AI-Cost-Phasen.** Begründung pro Dep sauber. - Blocks: „nichts kritisches" — **OK.** Auflage (Minor): README-Graph für V1 um #55 ergänzen. --- ## 3) Implementation-Steps-Qualität ### MVP - **Feature-Flag-Check ersetzt hardcoded 503 (`chatbot-stream.server.ts:41`)** — Step 3 macht das explizit: „Zeile 41 entfernen; vor Step 3 `resolveCapabilitiesForUser({tenantId, userId})` aufrufen". **Korrekt.** Zusätzlich saubere Trennung von „flag off → 403" vs. „flag on + no key → 503 mit code:NO_AI_PROVIDER_KEY". Lobenswert: unterschiedliche Status-Codes für unterschiedliche User-Wahrnehmungen. - **3 Basis-Capabilities als Tools exposed** — Steps 5/6/7 definieren `qa_help` (statische Markdown-Index + Keyword-Matching, kein Embedding), `kb_search` (Postgres-FTS, tenant-scoped Pflicht), `account_info` (Plan/Credits/Limits/MembersCount, Sensitive-Data-Whitelist). Tool-Factory-Pattern mit injizierter tenantId via Closure (kein `tenantId` im LLM-sichtbaren Schema) — **Best Practice, sauber begründet im Approach.** - **Capability-gated Tool-Registry (Step 8):** Tools werden NICHT registriert wenn Capability off — der Approach erklärt explizit warum „im Tool selbst prüfen" verworfen wurde (Token-Burn, User-Verwirrung). **Saubere Architektur-Entscheidung.** - **Settings-UI + Onboarding-Warning (Steps 9/10):** Vollständig. ### V1 - **TenantChatbotAccess Prisma-Model + Per-User-Toggles (Step 1):** Prisma-Schema komplett gezeigt, `@@unique([tenantId, userId])` und `@@index([tenantId])` korrekt, Cascade-Deletes auf Tenant+User. **Sauber.** - **Capability-gated Tool-Registrierung (Step 6 + Step 9):** Erweiterung des Switch-Statements aus MVP auf 8 Cases. High-Risk-Wrapping via `wrapHighRiskTool(...)` mit Pre-Flight-Rate-Limit + Audit. **Technisch sauber: Wrapper-Pattern verhindert Code-Duplikation, jeder High-Risk-Tool-Pfad geht garantiert durch Rate-Limit + Audit.** - **Audit-Event pro High-Risk-Tool-Call (Step 7):** `chatbot-audit.server.ts` schreibt AuditEvent mit `category='chatbot.tool_call'`, `action=capability+'.'+toolName`, sanitize via Allow-List. Integration mit Task #67 explizit benannt (Hash-Chain wird genutzt, direkter DB-Write verboten). **Korrekt verdrahtet.** - **Per-Capability Rate-Limits via Quota-Engine (Step 8):** `enforceQuota` aus Task #55 wird explizit referenziert, Scope `chatbot.${capability}`, konkrete Default-Limits angegeben. **Sauber verdrahtet.** **Inkonsistenz im V1-Resolver (Approach vs. Step 4):** - Approach Z.39 sagt: „Default-Modus ist konfigurierbar: entweder `all_members` oder `allow_list`". - Step 4 (Resolver-Logic) sagt korrekterweise: bei `all_members` und Row mit `capabilityScopes` → diese Liste; sonst Tenant-Default. **OK.** - Step 4 sagt aber NICHT, wie `capabilityScopes` per Row im UI gesetzt werden, wenn der Tenant im `all_members`-Modus ist — Step 10 (UI) zeigt nur „pro User Toggle enabled + Override-Capabilities" was OK ist. **Konsistent, aber V2 ändert die Semantik dieses Feldes dann radikal — siehe V2.** V2 (Step 9/10) konvertiert dann `capabilityScopes: String[]` zu `Json` (Map mit `inherit|grant|deny`). Das ist eine **breaking schema change** mit Data-Migration. Plan ist explizit, Migration-Step ist drin (Step 10), Backfill-Skript referenziert. **OK, aber komplex — siehe V2.** ### V2 - **RAG-Retrieval-Layer im System-Prompt-Builder (Steps 4-6):** `retrieveRelevantContext({tenantId, query, topK=5})` ruft `vectorStore.semanticSearch` aus Phase 04-Adapter mit `filter: { tenantId }`. System-Prompt-Builder bekommt `ragSnippets?` Parameter und rendert `## Relevant context`-Section mit `[ref:N]`-Markern. Stream-Endpoint ruft Retrieval vor jedem Stream-Call auf. **Korrekt, alles aus Phase 04 wiederverwendet, keine Duplikation.** - **Per-User-Capability-Overrides mit 3-State (Step 9):** `capabilityScopes` neue Repräsentation als JSON-Map `{[capability]: 'inherit'|'grant'|'deny'}`. Resolver: start mit Tenant-Default, dann pro Capability User-Override anwenden. Migration-Strategie ausdrücklich (Step 10 mit `data.ts`-Backfill). **Sauber, Migration explizit.** - **MCP-Tools über `external_tools`-Capability gegated (Step 11):** Stub aus V1 wird ersetzt durch echte MCP-Registry-Integration; jedes MCP-Tool als Sub-Tool exposed unter `external_tools`-Gate. AuditEvent + Rate-Limit aus V1 wiederverwendet. **Korrekt verdrahtet.** - **AICostEvent.capability-Feld (Step 7):** `trackChatbotCost(...)` schreibt via `ai-cost-phase-1` Producer-Helper Event mit Pflicht-Capability-Feld. Pseudo-Capability `chat_general` für Tool-freie Generations definiert. **Sauber.** --- ## 4) Test-Requirements - **Pro Capability ein E2E-Test (Tool-not-exposed wenn Capability off):** - MVP: 3 Cases in `capability-exposure.integration.test.ts` — **OK.** - V1: explizit „nicht nur 3 wie in MVP, sondern alle 8 Capabilities × 2 Runs (enabled/disabled)" — **OK, Pattern wird sauber erweitert.** - V2: erweitert auf 8 × 3 (inherit/grant/deny vs. Tenant-Default) — **OK, sehr gründlich.** - **RAG-Retrieval-Tests mit Mock-Embedding:** V2 hat `retrieve-relevant-context.server.test.ts` (Integration mit Test-pgvector via testcontainers) + `v2-rag-flow.integration.test.ts` (full-flow mit Embedding-Pipeline) + Cross-Tenant-Negativ-Test als CI-Pflicht-Blocker. **OK, aber kein expliziter „Mock-Embedding"-Vermerk — der Integration-Test nutzt testcontainers mit echtem pgvector. Für Unit-Tests fehlt eine `mockEmbeddingProvider`-Notiz.** Empfehlung: Unit-Test-Variante mit deterministic Mock-Embedding ergänzen, damit Tests ohne testcontainers in CI laufen können. **Minor.** - **Cross-Tenant-Negativ-Tests:** explizit als Pflicht in allen 3 Stufen (MVP: `kb_search`; V1: alle 8; V2: RAG-Embeddings). **Lobenswert.** --- ## 5) Security-Notes — Indirect Prompt Injection Der vom Security-Track identifizierte Indirect-Prompt-Injection-Finding ist **adressiert**, mit eskalierender Mitigation pro Stufe: - **MVP (Read-only):** Daten-Instruktions-Trennung via `---KB ARTICLE START/END---`-Marker, System-Prompt-Regel, Blast-Radius minimal (alle Capabilities read-only). - **V1 (Schreibend):** zusätzlich (1) `---TOOL_RESULT START (untrusted content)---`-Marker, (2) **Confirm-Step für High-Risk-Tools** im Chat-Widget (Tool returnt `{status: 'awaiting_confirmation', confirmationId}`, UI rendert Confirm-Step, separater POST endgültig), (3) Audit-Log immer aktiv, (4) Rolle-Check für `admin_actions` zusätzlich zur Capability. - **V2 (RAG):** zusätzlich (1) Strikte Marker in RAG-Section, (2) **Sub-Prompt-Sandbox-Pattern** (Snippets gehen in `user`-Channel statt `system`-Channel), (3) **Heuristic-Filter** `detectInjectionMarkers` pre-injection, (4) Citation-Spoofing-Validation im UI-Renderer (unbekannte refs → `[broken reference]`). Alle 4 vom User explizit verlangten Mitigations (Daten-Instruktions-Trennung mit Markern, Sub-Prompt-Sandbox, Heuristic-Filter, Confirm-Step für High-Risk-Actions) **sind vorhanden, korrekt verteilt über MVP/V1/V2.** **PASS.** Zusätzliche Security-Sorgen: - Embedding-Leak zwischen Tenants explizit als CI-Pflicht. - MCP-Tool-Trust-Boundary erwähnt Phase-06-WASM-Sandbox als künftige Mitigation. - Quota-Bypass via Stream-Abbruch → `onAbort`-Hook ergänzt. - Cost-Event-PII (keine Prompts/Completions) → DSGVO-konform. --- ## 6) Konsistenz mit User-Wünschen - **„Modularer SaaS-bewusster Chatbot mit gestaffelten Toggles, alle 4 Layer (Bewusstsein/Master/User/Capability) durchgehend":** - Bewusstsein = System-Prompt-Builder mit Tenant/User-Context — MVP Step 4. **OK.** - Master-Switch = Feature-Flag `chatbot` — MVP Step 3. **OK.** - User-Layer = `TenantChatbotAccess` pro `(tenantId, userId)` — V1 Step 1, V2 Step 9 (3-State). **OK.** - Capability-Layer = 8 Capabilities + Tool-Registry-Gating — MVP Steps 5-8, V1 Steps 5-6, V2 Step 11. **OK.** - Durchgängig in allen 3 Stufen. **PASS.** - **„Per-Tenant + Per-User-Toggles":** V1 deckt Per-User ab, V2 erweitert auf 3-State-Capability-Overrides. **PASS.** - **„RAG mit pgvector/Qdrant":** V2 nutzt explizit `vector-store`-Adapter aus Phase 04 (`vector-store.md` #49), pgvector als Default genannt, Adapter erlaubt Provider-Wechsel zu Qdrant. **PASS.** - **„AI-Cost-Tracking pro Capability":** V2 schreibt `AICostEvent` mit Pflicht-`capability`-Feld, nutzt Producer aus `ai-cost-phase-1.md` (#54), Per-Capability-Quotas via `ai-cost-phase-2.md` (#55), Aggregation/Reporting via `ai-cost-phase-3.md` (#56). **PASS.** --- ## 7) Staging-Deployment-Steps - MVP: Smoke-Test mit 3 konkreten Fragen für 3 Capabilities + Cross-Tenant-Negativ-Test + Onboarding-Test. **OK.** - V1: Smoke-Test mit OWNER + Power-User + Audit-Check + Rate-Limit-Check (51 Calls Test-Script) + Prompt-Injection-Test mit präparierten KB-Article. **OK, sehr konkret.** - V2: Setup-Steps (Embedding-Provider-Key, Bulk-Embed-Backfill via `rag-backfill.ts`-Skript), RAG-Smoke-Test, Cost-Smoke-Test, Quota-Smoke-Test, Override-Smoke-Test, Prompt-Injection-Test. **OK, alle Sub-Tracks abgedeckt.** **Mocked LLM-Provider für E2E:** Pattern existiert in Tests (Mock-LLM-Inspector für `streamText`-Tools-Map). Für Playwright-E2E wird auf Staging mit echtem Provider gefahren — das ist konsistent mit der Cost-Smoke-Test-Annahme. **Nicht explizit dokumentiert wie E2E in CI-Pipeline ohne Provider-Key läuft.** Empfehlung: Notiz in Test-Section ob Playwright-E2E in CI gegen Mock-Provider läuft oder nur gegen Staging — fehlt aktuell. **Minor.** --- ## 8) Fehlende Aspekte (vom Verifier identifiziert) Die Aufgabe nennt explizit drei mögliche Lücken — Status: ### a) Chatbot-History-Persistence - **NICHT explizit adressiert.** Weder MVP noch V1 noch V2 erwähnen Persistenz der Chat-Messages (User+Assistant). Im Modul-Pfad gibt es `apps/web/app/modules/chatbot/db/` (in der Code-Karte erwähnt), aber Detail-MDs sagen nicht ob `Chat`/`ChatMessage`-Modelle bereits existieren oder ob neu zu bauen. - **Lücke:** Falls History bereits existiert → kurze Erwähnung in MVP-Approach „nutzt bestehendes Chat/ChatMessage-Schema" wäre sauber. Falls nicht → MVP Step 0 fehlt komplett (History-Tabelle + Tenant-Scope + Retention). - **Empfehlung:** Vor MVP-Implementation Explore-Subagent prüfen lassen, Detail-MD ergänzen. Sonst riskiert MVP einen In-Memory-Chat ohne Persistenz, was gegen „produktionsreif" verstößt. ### b) Chatbot-Reset-Function (User-can-clear-history) - **NICHT erwähnt.** Weder in Settings-UI noch im Chat-Widget-Verhalten beschrieben. DSGVO-relevant (User soll seine eigenen Daten löschen können). - **Empfehlung:** V1 oder spätestens V2 Settings-UI um „Clear my chat history" + Endpoint ergänzen. Compliance-Export (Task #67) sollte ohnehin Per-User-Daten-Löschung können — Chatbot-History als ein Datentyp dort eintragen. ### c) Multilingual-Chatbot-Support - **NICHT erwähnt.** System-Prompt ist Englisch-only (siehe Section-Namen wie `## You are`, `## Tenant context`, etc.). Keine Sprach-Detektion oder lokalisierte Antworten. - **Empfehlung:** Wenn Boilerplate Multi-Locale unterstützt (zu prüfen), sollte V1 oder V2 Locale aus User-Settings in System-Prompt aufnehmen („Respond in {locale}" oder explizite Übersetzung der RAG-Snippets). Sonst fragt deutscher User auf Deutsch und Bot antwortet auf Englisch. **Diese 3 Lücken sind nicht blocker für PASS-Verdict**, weil sie eher Produkt-Features als Architektur-Lücken sind. **Sie sollten aber explizit als Out-of-Scope-Notiz aufgenommen werden** (z.B. in Phase-07-README oder als Backlog-Items für Phase 11 / Polish). --- ## 9) Weitere Befunde ### Stärken - **Sequenzielle Begründung sehr stark:** README erklärt klar warum nicht „alles auf einmal" und welche Phase-Abhängigkeiten warum existieren. - **Atomic-Commit-Disziplin:** Jeder Step endet mit eindeutigem Commit-Message — gut für Rollback und Code-Review. - **Wrapper-Pattern für High-Risk-Tools** (V1 Step 9) ist die richtige Architektur — verhindert dass irgendein neuer High-Risk-Tool den Rate-Limit/Audit-Pfad versehentlich überspringt. - **Capability-Exposure-Tests als Pattern** wird konsequent durch alle 3 Stufen durchgezogen und sogar erweitert (3 → 8 → 24 Cases). - **3-State-Override-Semantik (V2)** ist eleganter als zusätzliches Model und Migration ist explizit. - **Pseudo-Capability `chat_general`** für Tool-freie Cost-Tracking ist saubere Modellierung. ### Schwächen / Empfehlungen 1. **README-Dep-Graph fehlt #55 als V1-Input** (siehe Section 2). **Minor.** 2. **Chat-History/Reset/Multilingual nicht adressiert** (siehe Section 8). **Medium.** Sollte mindestens als Out-of-Scope-Notiz dokumentiert werden. 3. **Unit-Test für `retrieveRelevantContext` ohne testcontainers fehlt** — alle Tests dort sind Integration. **Minor.** 4. **CI-Strategie für E2E-Playwright-Tests gegen LLM-Provider nicht dokumentiert.** **Minor.** 5. **V1 Step 8 erwähnt Defaults für Limits** (`data_read=200/h`, etc.) **aber V2 Step 12** spricht von „Per-Capability-Token-Quota-Inputs" im Settings-UI. Inkonsistenz: V1 = Call-Frequency-Limit, V2 = Token-Quota. Beide existieren parallel — explizit machen dass das ZWEI verschiedene Limits sind (Call-Rate-Limit vs. Token-Quota). **Minor — Doku-Klärung empfohlen.** 6. **`isProviderConfigured`-Helper** wird in MVP Step 3 erwähnt, aber nicht als eigener Implementation-Step. **Minor:** Falls Helper noch nicht existiert, sollte er als Sub-Step in Step 3 oder als Step 0 stehen. ### Trennung von „chatbot.rag" vs. „chatbot"-Master-Flag - README erwähnt Subschalter `chatbot`, `chatbot.user_allowlist`, `chatbot.rag` — V2 Step 6 nutzt `chatbot.rag`. **Konsistent.** - `chatbot.user_allowlist` als separater Flag nicht in V1-Detail erwähnt — V1 nutzt stattdessen `Tenant.chatbotAccessMode='allow_list'`. **Inkonsistenz README vs. V1-Detail:** entweder Flag streichen oder als zusätzlicher Override-Layer dokumentieren. **Minor.** --- ## 10) Verdict **PASS mit folgenden Auflagen vor Implementation-Start:** 1. **MEDIUM:** Klären ob Chat-History/Reset/Multilingual in Phase 07 Scope sind oder explizit Out-of-Scope (Backlog-Verweis). README oder Phase-Done-Definition entsprechend ergänzen. 2. **MINOR:** README-Dep-Graph um `ai-cost-phase-2.md` (#55) → V1 ergänzen. 3. **MINOR:** README-Subschalter-Liste vs. V1-Detail abgleichen (`chatbot.user_allowlist` vs. `chatbotAccessMode`-Spalte). 4. **MINOR:** V1/V2 explizit machen dass es ZWEI verschiedene Limit-Achsen gibt: Call-Rate-Limit (V1) und Token-Quota (V2). 5. **MINOR:** `isProviderConfigured`-Helper als Sub-Step in MVP Step 3 oder Step 0 dokumentieren. 6. **MINOR:** Test-Strategie für E2E gegen LLM-Provider (Staging vs. CI) kurz erwähnen. Keine dieser Auflagen ist ein Blocker — der Plan kann implementiert werden, sobald Punkt 1 entschieden ist (Out-of-Scope-Notiz reicht). **Architektur-Korrektheit:** Sehr hoch. Capability-Gating-Pattern, Wrapper-Pattern, Tenant-Scoping-Disziplin, Migration-Pfade, Security-Mitigations gegen Prompt-Injection sind alle vorbildlich. **Vollständigkeit:** 95% — die fehlenden 5% sind die in Section 8 genannten Produkt-Features (History/Reset/Multilingual), nicht Architektur-Lücken. **Konsistenz:** Hoch — wenige Minor-Inkonsistenzen zwischen README und Detail-MDs, alle leicht zu beheben.