leocrm/PLATFORM_ROADMAP.md

# LeoCRM → LeoPlatform: Entwicklungs-Roadmap

> **Erstellt:** 2026-08-11
> **Überarbeitet:** 2026-08-13 — Endstand-Audit + Privacy/DSGVO/EU-AI-Act-by-Design integriert
> **Status:** Finale Endstand-Roadmap
> **Leitlinie:** «LeoCRM soll einfacher, konsistenter und erweiterbarer werden – nicht abstrakter, generischer oder frameworklastiger.»

---

## Entscheidungsregel für alle Änderungen

Bevor eine neue zentrale Abstraktion gebaut wird, müssen drei Fragen beantwortet werden:

1. Gibt es mindestens zwei oder drei wirklich semantisch gleiche Implementierungen?
2. Verursacht die Duplizierung aktuell konkrete Fehler oder Wartungsprobleme?
3. Wird das Gesamtsystem durch die gemeinsame Lösung tatsächlich einfacher?

Wenn eine Antwort nein ist: **Nicht generalisieren.**

Bestehender funktionierender Code wird nicht nur deshalb umgebaut, weil eine theoretisch schönere Architektur möglich wäre.

---

## Querschnitt-Regeln (für alle Phasen verbindlich)

### Ein Problem = ein Standardweg

| Querschnittsfunktion | Standardweg |
|---|---|
| DB-Schema (Core) | Alembic |
| DB-Schema (Plugin) | Plugin-Migrationsweg |
| DB-Schema (Runtime Auto-Sync) | Nicht authoritative, kein Ersatz für Migrationen |
| Redis | Zentraler Pool `get_redis()` |
| LLM | Zentraler Client `llm_complete()` |
| Files | Gemeinsamer Storage-Layer |
| Auth | Bestehender Auth-Kontext |
| Permissions | Bestehendes RBAC/ABAC-System |
| Search | Unified Search |
| Langlebige Events | Outbox |
| Externe Events | WebhookDispatcher |
| Background Jobs | ARQ |
| Plugin Integration | Vorhandenes Manifest/Registry-System |
| Workstream / interne Zusammenarbeit | Zentrales Communication-System (`CommConversation` / `CommMessage`) |
| Rich Content / MiniApps | `CommMessageBlock` + gemeinsamer `MiniAppRegistry` + Plugin-Manifest |
| Agent Skills | Kleiner Skill-Registry-/Definition-Weg; Skills orchestrieren nur vorhandene Tools/Services und verleihen keine Rechte |
| Plugin-Frontend | Volle React-Seiten gebündelt/deployment-time über vorhandenes Plugin-Frontend; runtime-fähige MiniApps schema-/registry-basiert |

Keine zweite parallele Lösung hinzufügen, wenn bereits ein funktionierender Standardweg existiert.

### Workstream-/MiniApp-Invarianten

Der Workstream ist **Darstellung, Zusammenarbeit und Koordination**, nicht die fachliche Datenquelle. Kontakte, Projekte, Termine, Dateien usw. bleiben in ihren Domain-Services/Tabellen authoritative. Eine MiniApp zeigt oder bearbeitet diese Objekte über die regulären APIs/Services mit normalen Permission-Prüfungen; sie hält keine zweite fachliche Kopie.

Der zentrale Workstream basiert auf dem bestehenden Communication-System und kann Menschen, System, Agenten und Workflows als Akteure zusammenführen. Text/Chat ist nur ein Blocktyp neben Action Cards, Entity Cards, Knowledge-Quellen, Approvals und MiniApps.

**Plugin-Frontend-Vertrag:**
- Vollständige kundenspezifische React-Seiten/Komponenten dürfen über das bestehende `PluginRegistry`/`PluginLoader`-System geliefert werden, benötigen im ersten Schritt aber einen Frontend-Build/Deploy, wenn ihr Code nicht bereits im Bundle vorhanden ist.
- Runtime-installierbare/interaktive Workstream-MiniApps verwenden primär einen sicheren schema-/registry-basierten Renderer (`render_schema`) und Standardaktionen/-komponenten.
- Kein beliebiges Remote-JavaScript/Module-Federation-System im Core. Signierte Remote-Bundles erst später, falls ein echter Marketplace-Hot-Install-Use-Case das verlangt.

### Sensitive Data Boundary (verbindlich)

Secrets und sensible technische Daten dürfen niemals automatisch in folgende Systeme gelangen:
- EntityHistory Snapshots
- Search Index / Embeddings
- RAG Chunks
- LLM Context
- Agent Memory
- Export
- Logs

Betroffen: Password Hashes, SMTP/IMAP Credentials, API Keys, OAuth Tokens, Session Tokens, Encryption Keys.

Lösung: Zentrale Exclude-/Sensitive-Field-Konvention. Verbindlich, getestet, keine riesige Security-Engine.

### Error-Handling-Konvention (verbindlich)

Error Handling ist **keine nachträgliche Schicht**, sondern wird direkt an den jeweiligen Systemgrenzen konsistent umgesetzt: LLM-Client, Agent-Loop, Workflow-Engine, WebSocket, Search/Indexing, Plugin-Routes, Batch-Operationen und Frontend.

**Grundregeln:**
- **Einheitliches Error-Response-Format** für die gesamte API: `{code, detail, field, trace_id, retryable}`. Keine Ad-hoc-`HTTPException` ohne strukturierten Code.
- **Error-Kategorisierung**: `TRANSIENT` (retryable: Timeout, Rate-Limit, Connection), `PERMANENT` (non-retryable: Validation, Permission, NotFound), `PARTIAL` (teilweise erfolgreich: Batch, Bulk, Multi-Step). Jeder Fehler trägt seine Kategorie, damit Workflow-Retry, Agent-Recovery und Frontend-UX entscheiden können.
- **Error-Propagation-Kette**: Plugin/Service → Core → API → Frontend → User. Technische Details (Tracebacks, interne Pfade) werden nur geloggt/monitoriert; dem User wird eine verständliche Nachricht mit `trace_id` zur Nachverfolgung gezeigt.
- **Frontend Error Boundaries**: Jede Plugin-Seite, MiniApp und kritische Komponente wird von einer ErrorBoundary umschlossen. Ein fehlerhaftes Plugin darf nicht die ganze App crashen.
- **Partial-Failure-Semantik**: Batch-Operationen (Import, Bulk-Restore, Re-Index, Agent Multi-Step) melden `partial_success` mit klarem Fehler-Report, was committed ist und was fehlgeschlagen ist. Kein stummes Versagen, kein inkonsistenter Zustand.
- **Bestehende Resilience-Patterns nutzen**: CircuitBreaker, `retry_db`, Outbox DLQ/Replay und Plugin-Error-Isolation sind vorhanden und werden konsequent angewendet — keine zweite Error-Engine.

### Privacy / DSGVO / EU AI Act by Design (verbindlich)

Compliance wird **nicht** als nachträgliche Parallelarchitektur gebaut. Datenschutz-, Transparenz-, Human-Oversight- und Nachweisfunktionen werden direkt an den bereits vorhandenen technischen Grenzen umgesetzt: Entity/Field-Metadaten, `AIProvider`, LLM-Client, Outbox, SearchProvider, AgentRun, WorkflowRun, ApprovalRequest, Audit und Communication.

**Grundregeln:**
- Leo stellt technische Compliance-Funktionen bereit; die rechtliche Zulässigkeit eines konkreten Einsatzes hängt weiterhin von Zweck, Daten, Betreiberrolle, Rechtsgrundlage und Branchenkontext ab.
- Jeder relevante AI-Use-Case erhält mindestens: `intended_purpose`, Owner, verwendete Agenten/Modelle/Provider, Datenkategorien, zulässige Aktionen, Human-Oversight-Policy und eine konfigurierbare Risikoklasse.
- **Keine Universal-Compliance-Engine:** kleine deklarative Policies an bestehenden Grenzen statt eines zweiten Policy-/Rechtesystems.
- `SENSITIVE_FIELDS` bleibt die harte Secret-Grenze. Zusätzlich gibt es eine kleine **AI/Data Exposure Policy** für personenbezogene bzw. besonders schützenswerte Fachfelder: ob sie in LLM Context, Search, Embeddings, RAG, Agent Memory und Export gelangen dürfen.
- Löschung/Korrektur einer authoritative Quelle muss abgeleitete Daten konsistent nachziehen können: Search/FTS, Vector/Embeddings, RAG-Chunks, Graph-Referenzen und Agent Memory. Kein blindes pauschales Hard-Delete, wenn gesetzliche Aufbewahrung oder fachliche Sperrgründe gelten; dafür muss der Betreiber die passende Retention-/Erasure-Policy konfigurieren.
- AI-Akteure werden im Workstream eindeutig als AI gekennzeichnet. Extern ausgegebene AI-generierte Inhalte können je Use-Case zusätzliche Transparenz-/Kennzeichnungsmetadaten erhalten.
- Personenbezogene oder sonst hochwirksame Entscheidungen können per Use-Case-Policy zwingend Human Review/Approval verlangen; Empfehlung, Evidenz, menschliche Entscheidung und Zeitpunkt bleiben nachvollziehbar.
- AI-Provider erhalten Compliance-Metadaten (Region, DPA/Vertragsstatus, Retention, Training-on-Customer-Data, Transfer-/Hosting-Hinweise, erlaubte Datenklassen). Der zentrale LLM-Client erzwingt die konfigurierte Provider-/Datenpolicy.
- High-Risk-/regulierte Branchenplugins nutzen dieselben Plattformmechanismen, bringen aber ihre **fachspezifische** Dokumentation, Risikobewertung und zusätzliche Kontrollen selbst mit. Der Core wird nicht auf Verdacht zu einer High-Risk-Suite aufgeblasen.

### Execution Principles (verbindlich für alle Phasen)

Diese 10 Prinzipien sind keine Tasks sondern **Arbeitsweise-Regeln** die für alle 12 Phasen gelten. Sie kosten keine zusätzliche Zeit sondern verändern wie gearbeitet wird.

1. **Spike First** — Riskante Phasen werden vorher mit einem 2-Tage-Spike validiert (siehe Spike-Tasks unten). Keine 6-Wochen-Phase ohne Proof-of-Concept.
2. **Test-First** — Jeder Task beginnt mit failing Tests, dann Code bis grün, dann Refactor. „Es compiliert" ist nicht „fertig".
3. **Phase-Gate-Disziplin** — Nach jeder Phase: AI-Review gegen 7 Kriterien. Bei ❌ → Bugfix-Sprint, keine neue Phase. Zeitbewusst: 2-3 Stunden Review, nicht 2 Tage.
4. **AI-Code-Review vor Merge** — Jeder Commit wird von AI reviewed bevor er gemerged wird: Forbidden Patterns, Permission-Bypass, Tenant-Isolation, Error-Handling, Test-Abdeckung.
5. **Task-Block-Deploy** — Pro Task-Block deployen (z.B. alle B-LLM Tasks zusammen = 1 Deploy), nicht pro Einzel-Task und nicht pro ganzer Phase. Mittelweg zwischen Micro-Deploy und 6-Wochen-Sammler.
6. **Architektur-Reviews** — Nach Phase B, F und I: AI-Architektur-Review. Dependency-Graph, Pattern-Check, Cross-Plugin-Imports, zirkuläre Abhängigkeiten. 2-3 Stunden pro Review.
7. **AI nach Stärken** — AI für repetitive Tasks (CRUD, Tests, Migrationen, Doku, Refactoring, Code-Review). Mensch für kritische Logik (ReAct-Loop, Workflow-Engine, Permission-Checks, Race-Conditions, Performance-Tuning, Security-Review).
8. **Fortlaufende Integration-Tests** — Nach jeder Phase: neue Features mit vorherigen Phasen zusammen testen. Nicht erst in Phase I alles kombinieren.
9. **Rollback-Lite** — Jeder Task hat Rollback-Plan (`git revert` + redeploy). Riskante Änderungen hinter Feature-Flag. Migrationen immer downgrade-fähig.
10. **Ehrliche Status-Reports** — „done" = bewiesen mit Test-Output, Build-Result, Health-Check. „Glaube ich" = `in_progress`, nicht `done`. PROGRESS.md bei jedem Status-Wechsel aktualisieren.

### Spike-Tasks (vor riskanten Phasen)

Vor den 4 Hochrisiko-Phasen (E, F, G, I) wird je ein 2-Tage-Spike durchgeführt. Spikes sind keine Tasks die in die Phase fallen — sie laufen **vor** der Phase und validieren das Kernrisiko.

| Spike | Vor Phase | Was wird validiert | Aufwand |
|-------|----------|-------------------|--------|
| SPIKE-E | Phase E | Minimaler FTS+Vector+Permission-Proof auf 10k Datensätzen. Funktioniert Permission-Filterung? Ist pgvector schnell genug? | 2 Tage |
| SPIKE-F | Phase F | Minimaler ReAct-Loop mit 3 Tools, 5 Steps, Permission-Check. Funktioniert Tool-Calling? Sind Responses brauchbar? | 2 Tage |
| SPIKE-G | Phase G | Minimaler durable WorkflowRun mit Wait+Resume+Idempotency. Überlebt er einen Worker-Restart? | 2 Tage |
| SPIKE-I | Phase I | Agent → Search → Knowledge → Workstream → Task → Approval in einem minimalen Flow. Funktionieren die Übergänge? | 2 Tage |

**Regel:** Spike scheitert → Risiko wird in der Phase adressiert oder Phase wird angepasst. Spike erfolgreich → Phase kann fokussiert umgesetzt werden.

### Phase-Gate-Reviews (zeitbewusst)

Nach jeder Phase führt AI ein Phase-Gate-Review durch. Dauer: 2-3 Stunden. Format: 7-Kriterien-Checkliste.

| Kriterium | Was wird geprüft |
|----------|----------------|
| 1. Tests grün | `pytest` + `vitest` + `tsc --noEmit` alle grün |
| 2. Build erfolgreich | `npm run build` erfolgreich |
| 3. Health 200 | Deployed → `curl /api/v1/health` → 200 |
| 4. Cross-Tenant safe | `test_cross_tenant_security.py` grün |
| 5. E2E pass | Kritische Playwright-Flows grün |
| 6. Docs aktualisiert | Betroffene `docs/` Dateien aktualisiert |
| 7. PROGRESS.md aktuell | Alle Task-Status eingetragen und verifiziert |

**Regel:** Bei ❌ bei einem Kriterium → Bugfix-Sprint bis ✅, keine neue Phase starten.

### Architektur-Reviews (nach B, F, I)

Nach den 3 wichtigsten Fundament-Phasen führt AI ein Architektur-Review durch. Dauer: 2-3 Stunden.

| Review | Nach Phase | Was wird geprüft |
|--------|-----------|----------------|
| ARCH-B | Phase B | LLM/Redis/Storage/WS/Error/Observability/Shutdown — funktioniert das Zusammenspiel? Gibt es zirkuläre Abhängigkeiten? |
| ARCH-F | Phase F | Agent+Tasks+Permissions+Approval+Workstream — gibt es Permission-Lücken? Ist das Task-Modell konsistent? |
| ARCH-I | Phase I | Alle Systeme verbunden — Search↔Agent↔Workflow↔Knowledge↔Workstream↔Tasks↔Approval — gibt es zirkuläre Abhängigkeiten oder inkonsistente Patterns? |

### Integration-Tests (fortlaufend)

Nach jeder Phase werden die neuen Features mit den vorherigen Phasen zusammen getestet. Nicht erst in Phase I alles kombinieren.

| Nach Phase | Was wird zusammen getestet |
|-----------|--------------------------|
| B | LLM-Client + Error-Handling + Observability + Shutdown |
| C | Frontend Error Boundaries + B-Systeme |
| D | Undo/Restore + Hooks + Outbox + B-Systeme |
| E | Search + Permission + Outbox + LLM + B-Systeme |
| F | Agent + Tasks + Permissions + Approval + Workstream + B+E-Systeme |
| G | Workflow + Agent + Approval + Workstream + B+E+F-Systeme |
| H | Knowledge + Search + RAG + Graph + B+E+F+G-Systeme |
| I | Alle Systeme — vollständiger Integration-Test |

### Migration-Staffelung

Nicht: neu → migrieren → alt sofort löschen.
Sondern: 1. neue Struktur → 2. Daten migrieren → 3. Reads/Writes umstellen → 4. Tests → 5. stabiler Release → 6. alte Struktur entfernen.

### Teststrategie (gestaffelt verbindlich)

Die Tests bleiben streng, werden aber sinnvoll gestaffelt. Nach größeren Entwicklungsblöcken laufen die technischen Checks; das vollständige Deployment-Gate wird am Phasenende ausgeführt.

1. **Backend Tests:** `python -m pytest -v --tb=short`
2. **Frontend Tests:** `cd frontend && npx vitest run --reporter=verbose`
3. **TypeScript Check:** `cd frontend && npx tsc --noEmit`
4. **E2E Tests:** `cd frontend && npx playwright test` (kritische Flows)
5. **Frontend Build:** `cd frontend && npm run build`
6. **Health Check:** auf deploytem Phase-Candidate → `curl /api/v1/health` → 200
7. **Login Check:** auf deploytem Phase-Candidate → Login → 200
8. **Cross-Tenant Test:** `python -m pytest tests/test_cross_tenant_security.py`

**Staffelung:**
- Einzel-Task: relevante Unit-/Integration-/Frontend-Tests + Typecheck/Build soweit betroffen
- Größerer Block: Checks 1–5 + 8
- Phase-Gate: alle 8 Checks inklusive Deploy/Health/Login

Damit bleibt das Gate streng, ohne nach jedem kleinen Backend-Task Production-Deployments zu erzwingen.

### Test-Strategie-Erweiterung (in Phase A aufzusetzen, fortlaufend pro Phase)

Die aktuelle Test-Strategie hat Lücken. Diese werden in Phase A aufgesetzt und pro Phase erweitert:

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| T-FE | **Frontend-Tests systematisch** — Vitest-Tests für neue/geänderte Fachlogik, Interaktionen, Hooks, Stores, API-Clients und kritische UI-Komponenten. Reine Präsentationskomponenten benötigen keinen Pflicht-Test ohne eigenes Verhalten | fortlaufend |
| T-SEC | **Security-Tests** — bandit (Python SAST), pip-audit (Dependencies), npm-audit (Frontend Dependencies). In CI-Pipeline integrieren | 1 Tag |
| T-LLM-MOCK | **LLM-Mocking-Strategy** — zentraler Mock für `llm_complete()` und `llm_embed()` in Tests. Keine Tests die externe APIs blockieren | 1 Tag |
| T-RLS | **RLS-Tests** — Test-DB mit echten Alembic-Migrationen (statt `create_all`) damit RLS-Policies getestet werden können | 1.5 Tage |
| T-PARALLEL | **Test-Parallelisierung** — pytest-xdist mit pro-Worker Datenbank. Reduziert Test-Laufzeit | 1 Tag |
| T-LOAD | **Load/Performance-Tests** — Basis-Load-Test mit locust/k6: Login, Contact-List, Search unter Last. In Phase A Baseline, in Phase I Vergleich | 1 Tag |
| T-CONTRACT | **Contract-Tests** — Plugin-Contracts (Mail, DMS, GraphRAG, AI UI Control) haben Tests die die Contract-Schnittstelle verifizieren | 1 Tag |
| T-A11Y | **Accessibility-Tests** — axe-core in E2E-Tests integrieren. WCAG-Checks auf kritischen Seiten | 1 Tag |
| T-E2E-EXT | **E2E-Tests erweitern** — bestehend: auth, contact-crud, calendar, dms, mail, search, plugin-toggle. Ergänzen: settings, notifications, tags, custom-fields, agent-chat, workflow-editor, knowledge, undo/restore | fortlaufend |
| T-COV | **Coverage-Tracking** — pytest-cov für Backend, vitest coverage für Frontend. CI prüft dass Coverage nicht sinkt | 0.5 Tage |
| T-DOC | **`docs/test-strategy.md` aktualisieren** — mit allen neuen Test-Typen, Mocking-Strategy, Parallelisierung, Coverage-Ziele | 1 Tag |

### Dokumentations-Pflicht (pro Phase)

Nach jeder Phase werden die betroffenen Docs aktualisiert:
- `docs/api-documentation.md` bei API-Änderungen
- `docs/plugin-development-guide.md` bei Plugin-Vorgaben
- `docs/ui-design-guidelines.md` bei UI-Änderungen
- `docs/test-strategy.md` bei Test-Änderungen
- `docs/security_kernel.md` bei Security-Änderungen
- `AGENTS.md` bei Engineering-Regeln

### Frontend-Tests (verbindlich pro Phase)

Pro Phase werden fehlende Frontend-Tests ergänzt:
- Vitest-Tests für neue/geänderte Fachlogik, Interaktionen und kritische Komponenten
- API-Client-Tests für neue/geänderte Endpoints
- Hook-Tests für neue Custom Hooks
- Store-Tests bei eigener Zustands-/Businesslogik
- E2E-Tests für neue kritische User-Flows
- Reine Präsentationskomponenten ohne eigenes Verhalten benötigen keinen Pflicht-Test

### Definition of Done (DoD) — verbindlich für jeden Task

Ein Task gilt erst als **DONE** wenn **alle** folgenden Kriterien erfüllt sind:

1. **Code implementiert** — Funktionalität ist vollständig gebaut, keine TODOs, keine Stubs
2. **Tests geschrieben** — relevante Fachlogik und Verhalten sind mit passenden Unit-/Integration-/Frontend-Tests abgedeckt; keine Pflicht zu wertlosen Tests für reine Präsentationskomponenten
3. **Tests grün** — alle Tests für diesen Task bestehen
4. **TypeScript clean** — `npx tsc --noEmit` zeigt keine neuen Fehler (nur bei Frontend-Tasks)
5. **Dokumentation aktualisiert** — betroffene Docs sind aktualisiert (API-Doku, Plugin-Guide, etc.)
6. **Keine neuen `any` Types** — neue/geänderte Dateien haben keine `any` Types (nur bei Frontend-Tasks)
7. **Sensitive Data ausgeschlossen** — falls Task mit Daten zu tun hat: SENSITIVE_FIELDS respektiert
8. **Integration verifiziert** — Task lokal/CI-grün; Production-Deploy ist kein Pflichtschritt pro Einzel-Task, sondern erfolgt am Phase-Gate

Ein Task mit testbarer Fachlogik oder relevantem Verhalten ist ohne passenden Test **NICHT done** — auch wenn der Code funktioniert. Reine Präsentationsänderungen ohne eigenes Verhalten benötigen keinen künstlichen Pflicht-Test.

### Phase-Gate-Review — verbindlich nach jeder Phase

Eine Phase gilt erst als **ABGESCHLOSSEN** wenn:

1. **Alle Tasks DONE** — jeder Task in der Phase hat DoD erfüllt
2. **8-Check-Pipeline grün** — alle 8 Checks (Backend, Frontend, TypeScript, E2E, Build, Health, Login, Cross-Tenant) bestehen
3. **Deploy verifiziert** — in Produktion deployed, Health 200, Login 200, Smoke-Test bestanden
4. **Dokumentation aktualisiert** — alle betroffenen Docs sind aktualisiert
5. **Performance verglichen** — gegen Phase A Baseline, keine signifikanten Regressionen
6. **Frontend-Tests ergänzt** — neue Features haben Vitest-Tests + E2E-Tests
7. **Keine offenen TODOs** — keine TODOs/Stubs aus dieser Phase im Code

Erst wenn alle 7 Kriterien erfüllt sind, wird die nächste Phase begonnen.

### Task-Tracking — Status pro Task

Jeder Task hat einen Status der verfolgt wird:
- `not_started` — Task noch nicht begonnen
- `in_progress` — Task wird bearbeitet
- `blocked` — Task blockiert (Abhängigkeit fehlt, Entscheidung ausstehend)
- `review` — Task implementiert, wartet auf Review/Tests
- `done` — Task hat DoD erfüllt

Tasks die `done` sind ohne DoD zu erfüllen werden auf `in_progress` zurückgesetzt.

---

## Code-Baseline 2026-08-13 — Ausgangspunkt dieser Roadmap

Die Roadmap ist **kein Greenfield-Plan**. Der aktuelle Code wurde gegen das Zielbild geprüft. Stand des geprüften Archivs:

- ca. **68.771 Backend-Python-Zeilen** in `app/`
- ca. **65.467 Frontend-TS/TSX-Zeilen** in `frontend/src/`
- ca. **32.328 Python-Testzeilen** in `tests/`
- **118 Alembic-Migrationen**, letzter Stand im Archiv `0117`
- `python -m compileall -q app` im Audit erfolgreich
- vollständiger frischer pytest-Lauf im Audit-Container nicht möglich, weil dort das Python-Paket `redis` fehlt; daraus wird **kein** Codefehler abgeleitet. Phase A verifiziert die echte Projekt-/Deploy-Umgebung.

### Bereits vorhandene Fundamente — erweitern, nicht neu bauen

| Bereich | Aktueller Code-Stand | Konsequenz für die Roadmap |
|---|---|---|
| Communication / Workstream | `CommConversation`, Teilnehmer, Messages, Rich Blocks, WebSocket, rechte `MessageSidebar`, mobile Overlay-Darstellung vorhanden | zum zentralen Workstream fertigstellen, kein neues Message-Modell |
| MiniApps | `MiniAppRegistry`, `MiniAppContribution`, `miniapp`-Message-Block, sechs registrierte Typen vorhanden; `MiniAppBlock.tsx` noch Placeholder | Runtime/Renderer und Plugin-Wiring fertigstellen |
| Proactive AI / UI Context | `useAIContext`, `ContextLog`, `ProactiveSuggestion`, Context-Events und Actions vorhanden | in gemeinsamen Trigger-/Agent-Kern konsolidieren |
| AI UI Control | REST/WebSocket, Navigation/Filter/Contact/Modal/Tab/Settings + Frontend-Feedback vorhanden | als Agent-Tool integrieren/erweitern |
| Agents | `AgentDefinition`, `AgentVersion`, `AgentRun`, `AgentSubtask`, früher `AgentCoordinator`, Agent-UI vorhanden | echten ReAct-/Permission-/Skill-Kern fertigstellen; nicht neu anfangen |
| Skills | **kein** explizites Skill-Modell/Registry im geprüften Code gefunden | kleinen Skill-Baustein in Phase F explizit ergänzen |
| Automation / Workflow | Workflow-Engine, persistente Instanz/Step-History, Conditions/Approval sowie AutomationDefinition/Run/Version/Cron vorhanden | durable Runtime erweitern; Automation und Workflow nicht zu zwei Engines auswachsen lassen |
| Search | SearchProvider, FTS, Vector/pgvector, RRF und GraphRAG-Grundlage vorhanden | auf Unified FTS+Vector+RAG+Graph konsolidieren/komplettieren |
| Knowledge | Graph-Grundlage vorhanden, aber Wiki/Document-RAG/Extraktion fehlen | Firmenwissensschicht auf bestehendem Search-Kern ergänzen |
| Import/Export | Service, Routes und Frontend für Import/Export bereits vorhanden | modularisieren/erweitern statt neu bauen |
| History/Restore | generisches Recording/History-UI teilweise vorhanden, Restore noch fachlich begrenzt | gezielt fertigstellen |
| Plugin UI | Manifest + Registry + dynamische Pfade vorhanden; externe Python-Plugins können entdeckt werden | klare Trennung: gebündelte React-Plugins vs. runtime schema-basierte MiniApps |

**Wichtiger Code-Fit:** Das Manifest kennt `miniapps`, aber die zentrale Plugin-Contribution-Registrierung und `/plugins/active-manifests` reichen MiniApps derzeit nicht vollständig bis zum Frontend durch. Genau diese konkrete Lücke wird in Phase B/I geschlossen; dafür wird keine neue Plugin-Architektur eingeführt.

## Roadmap-Übersicht

```
Phase A — Stabilität verifizieren                    [Woche 1]          ✅ DONE
Phase B — Kleine System-Konsolidierung               [Woche 2-7]        ⚠️ PARTIAL (B-VEC-IVF partial, B-STOR-EXT/WEBDAV fehlen, B-NOTIF-DEPREC nicht done)
Phase C — Core UI abschließen                        [Woche 8-11]       ✅ DONE
Phase C.5 — Modularer Import/Export                  [Woche 12-13]      ✅ DONE
Phase D — Minimal Undo/Restore                       [Woche 14-17]      ✅ DONE
Phase E — Unified Search vollständig                 [Woche 18-23]      ✅ DONE
Phase F — Agent MVP                                  [Woche 24-29]      ⚠️ PARTIAL (10 Module verbunden, aber Pre-built Agents nicht registriert, Agent→Communication nur teilweise, F-WORK gelöscht)
Phase G — Workflow MVP                               [Woche 30-35]      ✅ DONE (Engine + Step-Handlers + Decision Guard verbunden)
Phase H — Knowledge                                  [Woche 36-41]      ⚠️ PARTIAL (Wiki Plugin done, Knowledge Extraction/Lifecycle gelöscht — muss neu gebaut werden)
Phase I — Integration, Workstream & Polish           [Woche 42-47]      ✅ DONE (Integration, Block-Typen, Dashboard, Redis-Cache, 25/25 Tasks)
Phase J — Controlled Self-Improvement                [Woche 48-52]      ✅ DONE (self_improvement Plugin, 24/24 Tests, deployed)
Phase K — EU Compliance Finalization                 [Woche 52]         ✅ DONE (AI Registry, DPIA, Incident Register, 12/12 Tests, deployed)
Später — Advanced Autonomy/Automation nur bei echtem Bedarf
```

---

## Phase A — Stabilität verifizieren

**Dauer:** 1 Woche
**Ziel:** Verifizieren dass die 9 Minimal-Fix-Pakete stabil sind. Keine neue Architekturarbeit.

| Task | Beschreibung |
|------|-------------|
| A-VERIFY | Installation, CI, E2E, Auth, Cross-Tenant, Worker verifizieren |
| A-TEST | Test-Pipeline (8 Checks) ausführen — alle müssen grün sein |
| A-PERF | Performance-Baseline messen (Response-Times, DB-Query-Counts) für spätere Vergleiche |
| A-RESTORE | **Automatisierter Backup-Restore-Test** — bestehendes `backup_service.py` + `restore_test.sh` verifizieren und als ARQ-Cron-Job einrichten: Backup erstellen → in Test-DB restore → Schema/Row-Count validieren → Ergebnis loggen. Ein Backup das nie getestet wurde ist kein Backup |
| A-DOC | `docs/test-strategy.md` aktualisieren mit verbindlicher Test-Pipeline |

---

## Phase B — Kleine System-Konsolidierung

**Dauer:** 6 Wochen (bei 2 Entwicklern; bei 1 Entwickler ~10-12 Wochen)
**Ziel:** Nur wirklich gemeinsame technische Infrastruktur konsolidieren. Keine Universalmodelle.

### B.1 Zentraler LLM Client

Im Code-Audit verbleiben **9 direkte `litellm.acompletion()` Aufrufe außerhalb des zentralen Clients** (automation/agent_runner, ai_assistant 2x, ai_proactive 3x, unified_search 2x). Diese auf den vorhandenen zentralen Client umstellen.

**Embedding-API:** Der zentrale Client stellt nicht nur `llm_complete()` sondern auch `llm_embed(texts, model)` bereit. LiteLLM unterstützt Embeddings über `litellm.aembedding()` — derselbe Provider-/API-Key-Mechanismus wie Completion. Aktuell nutzt `unified_search/embedding.py` direkte OpenRouter-API-Calls. Diese werden auf `llm_embed()` über den zentralen Client umgestellt. Provider-Auswahl, API-Key-Auflösung, Error-Handling und Cost-Tracking laufen über denselben zentralen Weg wie Completion-Calls.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-LLM | `llm_client.py` erweitern: `llm_complete(model, messages, tools, ...)`, `llm_embed(texts, model)`. Provider-Auswahl aus DB, API-Key-Auflösung, Error-Handling, Cost-Tracking, Streaming-Helfer, Timeouts, optionale Retries | 2 Tage |
| B-LLM-MIG | Alle 9 verbleibenden direkten `litellm.acompletion()` Aufrufe außerhalb `llm_client.py` umstellen + `unified_search/embedding.py` auf `llm_embed()` umstellen | 2 Tage |
| B-LLM-TEST | Tests für zentralen Client (mock mode, real mode, error scenarios) | 1 Tag |
| B-LLM-DOC | Plugin-Dev-Guide: `from app.ai.llm_client import llm_complete`. Keine direkten LiteLLM-Aufrufe | 0.5 Tage |

### B.2 Zentraler Redis Pool

Ein zentraler `get_redis()`-Weg existiert bereits. Direkte Redis-Client-Erzeugung verbleibt im Audit u. a. in `cache.py`, `monitoring.py` und `worker.py`; Auth/Dependencies nutzen bereits den zentralen Weg. Diese technischen Sonderpfade konsolidieren, ohne neue Redis-Abstraktion.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-RED | `get_redis()` als Standard-Anlaufstelle. `cache.py`, `monitoring.py`, `worker.py` und weitere echte Direktkonstruktoren prüfen/umstellen; bestehende Dependency-/Middleware-Nutzung nicht unnötig umbauen | 1 Tag |
| B-RED-TEST | Connection-Leak-Test unter Last | 0.5 Tage |

### B.2b pgvector HNSW Optimierung

pgvector mit HNSW-Index direkt optimieren — nicht auf Phase I verschieben. Bei 100k+ Embeddings ohne Tuning wird Search langsam.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-VEC | **HNSW-Parameter optimieren** — `ef_construction=128`, `m=16` als Defaults. Konfigurierbar pro Entity. `ef_search` pro Query anpassbar (Tradeoff Speed/Recall) | 1 Tag |
| B-VEC-IVF | **IVFFlat als Alternative** — für sehr große Datasets (>1M) kann IVFFlat besser sein. Konfigurierbare Index-Strategie | 0.5 Tage |
| B-VEC-BATCH | **Batch-Embedding** — mehrere Entities in einem LLM-Call embedden (reduziert API-Calls und Kosten) | 0.5 Tage |
| B-VEC-TEST | Performance-Tests: 10k, 100k, 1M Embeddings — Query-Latenz messen | 1 Tag |

### B.3 Gemeinsamer File Storage

Gemeinsame technische Storage-Schicht für alle File-Typen. Domainmodelle (DMS File, MailAttachment, CommMessageAttachment, AIChatAttachment) bleiben separat.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-STOR | Bestehendes `core/storage.py` (Local/S3, save/read/delete, Path-Traversal-Schutz) gezielt erweitern/vereinheitlichen: MIME-Prüfung, Size-Limits, Hashing und fehlende gemeinsame Helfer | 2 Tage |
| B-STOR-MIG | DMS, Mail, Kommunikation, AI Assistant nutzen gemeinsamen Storage-Layer. Eigene Upload-Endpoints bleiben bestehen (`/dms/files/upload`, `/mail/.../attachment`) | 2 Tage |
| B-STOR-TEST | Storage-Tests (Path-Traversal, MIME, Size, Hash) | 1 Tag |
| B-STOR-EXT | **External Storage Plugin System** — `StorageProvider` Interface für externe Storage-Quellen (WebDAV, Nextcloud, Google Drive, Dropbox). Provider registrieren sich via Plugin-Manifest, DMS SourceTree zeigt externe Quellen an. Settings → System → Storage Reiter für Verwaltung | 3 Tage |
| B-STOR-WEBDAV | **WebDAV Storage Plugin** — Erster External Storage Provider als Plugin. Verbindet WebDAV-Server (Nextcloud, ownCloud, radicale). Browse, Upload, Download, Delete. Credentials in Settings → System → Storage konfigurierbar | 2 Tage |

### B.4 WebSocket Helpers

Gemeinsame Helpers statt großer BaseWebSocketManager. Spezialisierte Manager bleiben.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-WS | Gemeinsame Helpers: Session-Auth, Origin-Check, Tenant-Check, Connection-Cleanup, Heartbeat. `WebSocketManager` (Kommunikation) und `AIUIControlWSManager` (AI UI) nutzen Helpers. **Redis Pub/Sub für WS-Fanout** — bei mehreren Uvicorn-Workern funktioniert In-Memory-Fanout nicht. Redis Pub/Sub als Backbone: Worker publish auf Redis-Channel, alle WS-Clients subscriben. Kein Funktionsverlust, horizontale Skalierung möglich | 3 Tage |
| B-WS-TEST | WebSocket-Auth-Tests | 1 Tag |

### B.5 Event-System Rollen dokumentieren

4 Systeme bleiben, Rollen klar definieren. Keine neue Abstraktion.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-EVT | Rollen dokumentieren: HookRegistry = Lifecycle/Daten-Anpassungen, EventBus = flüchtige interne Events, Outbox = dauerhafte Domain Events, WebhookDispatcher = externe HTTP-Zustellung. Regel: nicht dieselbe Funktion über Hook UND EventBus triggern. Inkonsistenzen bereinigen | 1 Tag |
| B-EVT-DOC | Decision Guide für Plugin-Entwickler: wann welches System | 0.5 Tage |

### B.6 Schema Authority definieren

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-SCHEMA | Dokumentieren: Core → Alembic, Plugin → Plugin-Migrationsweg, Runtime Auto-Sync → nicht authoritative. Kein neuer Schema-Mechanismus | 0.5 Tage |

### B.7 Plugin-Guide (klein)

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-PLUGIN | Plugin-Pflicht auf das Wesentliche: Manifest, Dependencies, Routes, Permissions, Tenant-Isolation, Migrationen, Activation/Deactivation. Alles andere optional (Search, History, LLM, MCP, Attachments, etc. — nur wenn benötigt). Nicht jedes ORM-Modell braucht `deleted_at` | 1 Tag |
| B-PLUGIN-MANIFEST | Bestehende Manifest-Felder und Contributions wiederverwenden. Nicht aufblasen | 0.5 Tage |
| B-PLUGIN-FE | Bestehendes Plugin-Frontend-System (`PluginLoader.tsx`, `PluginRegistry.tsx`, `PluginRouteRenderer.tsx`, `pluginStore.ts`) analysieren, testen, bei Bedarf korrigieren. NICHT neu bauen | 1 Tag |
| B-PLUGIN-MINIAPP-WIRE | **MiniApp-Contributions end-to-end verdrahten** — `manifest.miniapps` beim Aktivieren in den **gemeinsamen** `comm_miniapps`-Registry eintragen und beim Deaktivieren entfernen. Keine privaten Registry-Instanzen pro Plugin | 1 Tag |
| B-PLUGIN-UI-CONTRACT | **Frontend-Delivery-Vertrag festlegen** — gebündelte React-Pluginseiten benötigen Build/Deploy; runtime-fähige MiniApps laufen schema-/registry-basiert. Kein beliebiges Remote-JS als Core-Anforderung | 0.5 Tage |
| B-PLUGIN-GUIDE | **Vollständiger Plugin-Dev-Guide** — `docs/plugin-development-guide.md` komplett überarbeiten mit ALLEN Integration-Punkten die eine KI die Plugins baut kennen muss: | 2 Tage |

**Plugin-Dev-Guide muss folgende Kapitel enthalten:**

1. **Grundlagen** — Manifest, Dependencies, Routes, Permissions, Tenant-Isolation, Migrationen, Activation/Deactivation
2. **Hooks** — wie Plugin Hooks registriert (`register_action`, `register_filter`), welche Hooks existieren (B.10 Übersicht), wie eigene Hooks definiert werden
3. **Outbox Events** — wie Plugin Events published (`enqueue_outbox_event`), welche Events existieren (B.10 Übersicht), wie Plugin Events subscribiert
4. **Trigger** — wie Plugins Domain-Event-, UI-, Cron- und Manual-Trigger nutzen; Webhook-Trigger folgt in Phase G. Durable Domain Events und ephemere UI-Events klar trennen
5. **Message-System** — wie Plugin System-Nachrichten postet (`post_system_message()`), wie Plugin Chat-Räume erstellt, wie Plugin Mini-Apps registriert, Rich Content Blocks (action_card, contact_card, miniapp)
6. **Search** — wie Plugin SearchProvider registriert, welche Modi unterstützt werden (FTS, Vector, RAG, Graph), wie Auto-Indexierung funktioniert
7. **LLM** — wie Plugin LLM-Calls macht (`from app.ai.llm_client import llm_complete`), keine direkten LiteLLM-Aufrufe, Provider-Auswahl, Cost-Tracking
8. **File Storage** — wie Plugin Files speichert (`core/storage.py`), keine eigenen Storage-Backends, MIME-Prüfung, Path-Traversal-Schutz
9. **WebSocket** — gemeinsame Helpers für Auth, Origin, Tenant, Cleanup und Heartbeat sind Pflicht. Eigene spezialisierte WebSocket-Manager sind erlaubt, wenn ein Plugin eigene Connection-/Message-Semantik benötigt; keine parallele eigene Sicherheits-/Lifecycle-Basislogik
10. **Redis** — wie Plugin Redis nutzt (`get_redis()`), keine eigenen Connections
11. **Permissions** — wie Plugin Permissions deklariert und bestehendes RBAC/ABAC nutzt. Tools, Skills und MCP dürfen keine Rechte verleihen oder bestehende Permission-Prüfungen umgehen
12. **AI Tools** — wie Plugin Tools in ToolRegistry registriert, wie Agenten diese nutzen, `required_permission` pro Tool
13. **MCP** — MCP nur als dünne Exposure-Schicht auf bestehende Tools/Services; vorhandener Auth-/Run-as-Kontext und normale Permission-Prüfungen bleiben maßgeblich
14. **UI-Events** — wie Plugin auf UI-Events reagiert (`ui.contact_selected`, etc.), wie Plugin UI-Events published
15. **AI UI Control** — wie Plugin AI UI Control nutzt (navigate, filter, open_contact, modal, tab, settings)
16. **Sensitive Data** — welche Felder SENSITIVE sind, wie Plugin SENSITIVE_FIELDS deklariert, was NICHT in Snapshots/Index/Embeddings/Export darf
17. **Schema Authority** — Core → Alembic, Plugin → Plugin-Migrationsweg, Runtime Auto-Sync → nicht authoritative
18. **Migration-Staffelung** — wie Plugin Migrationen sicher durchführt (neu → migrieren → umstellen → testen → release → alt entfernen)
19. **Frontend** — wie Plugin Frontend-Komponenten erstellt (Standard-Komponenten nutzen, Manifest deklarieren, Theme respektieren, i18n nutzen, ErrorBoundary), inklusive Delivery-Vertrag: volle React-Komponenten deployment-time/bundled; runtime MiniApps schema-/registry-basiert
20. **Privacy/AI Compliance** — wie Plugin Datenklassen/AI-Exposure deklariert, AI-Use-Cases beschreibt, Human-Oversight/Transparency nutzt und abgeleitete Daten bei Correction/Erasure nachzieht; High-Risk-Spezialpflichten bleiben beim konkreten Vertical/Use-Case
21. **Test-Strategie** — wie Plugin Tests schreibt (Backend: pytest, Frontend: Vitest, E2E: Playwright), was getestet werden muss
22. **Error-Handling** — wie Plugin Errors werfen (`ApiError` mit `code`, `category`, `retryable`), Error-Propagation-Kette (Plugin → Core → API → Frontend → User), `trace_id`-Korrelation, Frontend-ErrorBoundary-Pflicht für Plugin-Seiten/MiniApps, Partial-Failure-Semantik bei Batch-Operationen, keine Tracebacks an User

### B.8 Rate-Limiting Konsistenz

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-RL | Zentrale Redis-basierte Rate-Limit-Implementierung verwenden und bestehende In-Memory-Limiter darauf umstellen. Policies gezielt für missbrauchs-/kostenrelevante Endpoints definieren (Auth/Login, öffentliche APIs, Webhooks, AI/LLM, Uploads, Passwort-Reset etc.). Keine pauschale Rate-Limit-Pflicht für jeden internen CRUD-Endpoint | 1 Tag |

### B.9 Sensitive Data Boundary

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-SENS | Zentrale Exclude-/Sensitive-Field-Konvention: `SENSITIVE_FIELDS` Set pro Entity. EntityHistory, Search, Embeddings, Export filtern automatisch. Tests die verifizieren dass keine Secrets in Snapshots/Index landen | 2 Tage |
| B-DATA-POL | **AI/Data Exposure Policy** — kleine deklarative Entity-/Field-Policy ergänzen: zulässig für LLM Context, Search, Embeddings/RAG, Agent Memory und Export. `SENSITIVE_FIELDS` bleibt harte Secret-Sperre; keine zweite Permission-Engine | 2 Tage |
| B-AIPROV-COMP | **AIProvider Compliance Metadata** — Region/Hosting, DPA-/Vertragsstatus, Retention, Training-on-Customer-Data, Transfer-Hinweise und erlaubte Datenklassen am bestehenden `AIProvider`; zentraler LLM-Client prüft die konfigurierte Policy vor Übermittlung | 1.5 Tage |
| B-PRIV-TEST | Tests: Secrets immer blockiert, Exposure-Policy greift, nicht freigegebener Provider erhält keine entsprechenden Daten | 1 Tag |

### B.10 Lifecycle Hooks & relevante Outbox Events

Für KI-, Plugin- und Automatisierungs-Erweiterbarkeit werden Lifecycle-Hooks dort breit und konsistent angeboten, wo Erweiterbarkeit fachlich sinnvoll ist. **Durable Outbox Events werden dagegen nur für fachlich relevante Zustandsänderungen definiert, die asynchron verarbeitet, automatisiert oder extern konsumiert werden können. Keine Events auf Vorrat.**

**Prinzip:** Hooks sind lokale Erweiterungspunkte. Outbox Events sind dauerhafte Domain Events mit Delivery-/Retry-Semantik. Technische Tabellen, reine Read-Aktionen und UI-Kontext brauchen nicht automatisch Hooks oder Outbox Events.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-HOOK-CORE | **Core Hooks vervollständigen** — Contact, Company und weitere relevante Core-Businessobjekte konsistent abdecken; nur Lifecycle-Punkte mit echtem Erweiterungsnutzen | 1 Tag |
| B-HOOK-MAIL | **Mail Hooks** — relevante receive/send/delete/move Lifecycle-Punkte ergänzen | 1 Tag |
| B-HOOK-DMS | **DMS Hooks** — relevante upload/create/update/delete/restore Lifecycle-Punkte + Folder-CRUD | 1 Tag |
| B-HOOK-CAL | **Calendar Hooks** — relevante create/update/delete Lifecycle-Punkte | 0.5 Tage |
| B-HOOK-TASK | **Task Hooks** — relevante create/update/delete Lifecycle-Punkte | 0.5 Tage |
| B-HOOK-COMM | **Communication Hooks** — relevante message/edit/delete + conversation Lifecycle-Punkte | 1 Tag |
| B-HOOK-AI | **AI/Agent Hooks** — nur sinnvolle Run-/Tool-/Message-Lifecycle-Punkte | 0.5 Tage |
| B-HOOK-WF | **Workflow Hooks** — relevante start/step/complete/cancel Lifecycle-Punkte | 0.5 Tage |
| B-HOOK-TAG | **Tag/Link Hooks** — assign/unassign bzw. create/delete soweit Plugins darauf reagieren müssen | 0.5 Tage |
| B-HOOK-SEARCH | **Search Hooks** — optional `before_search`/`after_search` für echte Query-/Result-Erweiterungspunkte. **Keine** parallelen `before/after index/reindex`-Hooks; Indexierung läuft ausschließlich über SearchProvider + Outbox→Worker | 0.25 Tage |
| B-EVT-OUTBOX | **Relevante Domain Events ergänzen** — z. B. task.completed, file.created/deleted/restored, mail.received/sent, workflow.started/completed, agent.run_started/completed. Event nur wenn ein konkreter Consumer/Automatisierungs-/Integrationsbedarf existiert | 1.5 Tage |
| B-HOOK-TEST | Tests: relevante Hooks feuern korrekt; definierte Domain Events werden zuverlässig gepublished; keine UI-/Read-Events versehentlich durable; Sensitive Fields ausgeschlossen | 1.5 Tage |
| B-HOOK-DOC | Plugin-Dev-Guide: Hook- und Domain-Event-Konventionen sowie Entscheidungsregel dokumentieren | 0.5 Tage |

### B.11 Trigger-Kern konsolidieren

Der vorhandene Trigger-Kern wird vereinheitlicht; **keine zweite Trigger-Engine**. Domain Events, UI Events, Cron und Manual nutzen denselben registrierungs-/dispatch-orientierten Kern, aber mit unterschiedlicher Delivery-Semantik.

- **Durable Domain Events** → Outbox → Worker/Trigger Dispatcher
- **UI Events** (`ui.contact_selected`, `ui.page_navigated`, `ui.mail_opened`, ...) → ephemer über EventBus/Redis/Trigger Dispatcher, **nicht** über die Transactional Outbox
- **Cron/Heartbeat** → vorhandener Automation-Scheduler/ARQ
- **Manual** → vorhandener Execution-Pfad
- **Incoming Webhook** → wird erst in Phase G als Workflow-Feature gebaut
- **Agent → Workflow** → wird später in F/G über reguläre Tools/Services integriert, nicht in B künstlich vorbereitet

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-TRIG-GEN | **Generische Domain-Event-Trigger** — hardcodierte Event-Liste entfernen; registrierte relevante Outbox Events können über den gemeinsamen Dispatcher Automations/Workflows finden | 1.5 Tage |
| B-TRIG-UI | **UI-Event Trigger-Typ definieren** — ephemerer Pfad über EventBus/Redis/Dispatcher; noch keine Agent-spezifische Parallelengine | 0.5 Tage |
| B-TRIG-CRON | **Cron/Heartbeat verifizieren** — bestehenden Scheduler/ARQ-Pfad für relevante Job-Typen konsistent nutzen; keine neue Scheduler-Architektur | 0.5 Tage |
| B-TRIG-MAN | **Manual-Trigger verifizieren** — bestehender Manual-Pfad nutzt denselben Execution-Kern | 0.5 Tage |
| B-TRIG-TEST | Tests: Domain Event, UI Event, Cron und Manual werden korrekt dispatcht; UI Events werden nicht in die Outbox geschrieben | 1 Tag |
| B-TRIG-DOC | Plugin-Dev-Guide: Trigger-Typen und durable-vs-ephemeral Semantik dokumentieren | 0.5 Tage |

### B.12 Notification → zentrales Message-System konsolidieren

Das bisher separate Notification-System und das Communication-/Message-System werden **zu einem zentralen internen Message-System zusammengeführt**. Communication wird damit der Standardweg für User-, System-, Agent- und Notification-Nachrichten. Das alte Notification-System wird nach Migration und Verifikation vollständig entfernt; `NotificationPreference` bleibt ausschließlich als Delivery-/Preference-Konfiguration. System-/Notification-Messages bleiben semantisch typisiert und sind nicht einfach normale Chattexte.

**Aktueller Stand:**
- Notification: eigenes Model (`Notification`, `NotificationType`, `NotificationPreference`), eigene Routes (`/api/v1/notifications`), eigene Frontend-Komponenten (`NotificationDropdown.tsx`, `NotificationItem.tsx`)
- Communication: eigenes Plugin (`CommConversation`, `CommMessage`, `CommMessageBlock`, etc.), eigene Routes (`/api/v1/comm`), eigene Frontend-Komponenten (`comm/blocks`)
- Keine Verbindung zwischen beiden Systemen

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-NOTIF-SYS | **System-Channel** — automatischer System-Channel (CommConversation) pro Tenant. Wird bei Tenant-Erstellung angelegt. `is_system=True` Flag. `CommParticipant` mit `participant_type='system'`. User sind automatisch Teilnehmer | 1 Tag |
| B-NOTIF-EVT | **Event → typisierte System-Message** — relevante Domain Events erzeugen bei konfigurierter Delivery typisierte `CommMessage`/Rich-Content-Blöcke mit Severity, Entity-Referenz/Action und System-Participant. Keine normale Chattext-Semantik erzwingen | 1.5 Tage |
| B-NOTIF-UI | **Notification-Dropdown → System-Channel** — Notification-Dropdown in TopBar zeigt den System-Channel an (letzte Nachrichten). Klick öffnet den System-Channel im Chat. Ungelesene System-Nachrichten = Badge in TopBar. `NotificationDropdown.tsx` und `NotificationItem.tsx` werden durch Chat-Komponenten ersetzt | 1.5 Tage |
| B-NOTIF-PREF | **Delivery-/Notification-Preferences** — `NotificationPreference` bleibt als Routing-Konfiguration, z. B. In-App/System-Channel, E-Mail oder stumm; kein zweites Nachrichtensystem | 0.5 Tage |
| B-NOTIF-MIG | **Migration** — bestehende Notifications in System-Channel als CommMessages migrieren. Alte Notification-Tabelle als View behalten für Übergang. **Field-Mapping:** `Notification.read_at` → `CommMessageRead`, `Notification.type` → Block-Metadata `notification_type`, `Notification.entity_type/entity_id` → Block-Metadata `entity_ref`, `Notification.title/body` → Text-Block + `action_card` Block mit Deep-Link | 1.5 Tage |
| B-NOTIF-DEPREC | **Notification-System vollständig zurückbauen** — nach Migration und Verifikation: `Notification` Model, `NotificationType` Model, `/api/v1/notifications` Routes, `NotificationDropdown.tsx`, `NotificationItem.tsx` vollständig entfernen. Kein doppeltes System. `NotificationPreference` bleibt (für E-Mail/Stumm-Einstellungen). `create_notification()` wird zu `post_system_message()` im Comm-System | 1 Tag |
| B-NOTIF-TEST | Tests: System-Events → Chat-Nachrichten, Preferences respektiert, Unread-Badge korrekt, Migration korrekt | 1 Tag |

### B.13 Error-Handling-Infrastruktur

Bestehende Resilience-Patterns (CircuitBreaker, `retry_db`, Outbox DLQ/Replay, Plugin-Error-Isolation) werden konsolidiert und um die fehlenden systematischen Bausteine ergänzt. Keine zweite Error-Engine, sondern ein einheitlicher Rahmen auf bestehenden Mustern.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-ERR-FMT | **Einheitliches Error-Response-Format** — `{code, detail, field, trace_id, retryable}` für die gesamte API. Bestehende `error_codes.py` (6 Codes) erweitern, `ApiError` als Standard-Exception, FastAPI Exception-Handler der alle Errors im einheitlichen Format zurückgibt. `trace_id` korreliert mit Request-Logging | 1 Tag |
| B-ERR-CAT | **Error-Kategorisierung** — `ErrorCategory.TRANSIENT` (retryable: Timeout, Rate-Limit, Connection), `PERMANENT` (non-retryable: Validation, Permission, NotFound), `PARTIAL` (teilweise erfolgreich: Batch, Bulk, Multi-Step). Jeder `ApiError` trägt seine Kategorie; Workflow-Retry, Agent-Recovery und Frontend-UX nutzen diese | 0.5 Tage |
| B-ERR-WS | **WebSocket Error-Handling** — strukturierte Error-Messages an WS-Clients, Reconnect-Hints, Dead-Message-Queue für nicht-verarbeitbare Messages. In B-WS Helpers integriert | 0.5 Tage |
| B-ERR-PROP | **Error-Propagation-Konvention** — Plugin/Service → Core → API → Frontend → User. Technische Details (Tracebacks, interne Pfade) nur geloggt/monitoriert; dem User verständliche Nachricht mit `trace_id`. Im Plugin-Dev-Guide (B-PLUGIN-GUIDE) als Kapitel 22 dokumentieren | 0.5 Tage |
| B-ERR-TEST | Tests: Error-Response-Format, Kategorisierung, WS-Error-Handling, Error-Propagation | 1 Tag |

### B.14 Observability & trace_id-Korrelation

Bestehendes `structlog` (JSON-Logging) und `monitoring.py` (Prometheus-Metriken) werden um systematische Request-/Trace-Korrelation ergänzt. Kein zweites Monitoring-System, sondern `trace_id`-Propagation durch alle Ebenen.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-OBS-TRACE | **trace_id-Propagation** — Request-ID wird pro API-Request erzeugt, im `structlog` contextvars gesetzt, in jeden Log-Eintrag eingebettet, an ARQ-Worker weitergereicht (ARQ `job_metadata`), in LLM-Client-Calls injiziert, in Error-Responses zurückgegeben. Frontend kann `trace_id` aus Response anzeigen/melden | 1 Tag |
| B-OBS-LOG | **Strukturiertes Logging konsolidieren** — alle Module nutzen `structlog.get_logger()`, keine `logging.getLogger()` mehr. Log-Level konfigurierbar pro Modul. Sensitive Fields aus Logs filtern (wie Sensitive Data Boundary) | 0.5 Tage |
| B-OBS-TEST | Tests: trace_id durch alle Ebenen korreliert, Sensitive Fields nicht in Logs | 0.5 Tage |

### B.15 Graceful Shutdown & Connection Draining

Bei Coolify-Deploy oder Worker-Restart dürfen laufende Requests, WebSocket-Connections und ARQ-Jobs nicht abrupt abgebrochen werden. Bestehende `lifespan` und `on_shutdown` werden um sauberes Draining ergänzt.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-SHUT-API | **API Graceful Shutdown** — SIGTERM-Handler: keine neuen Requests akzeptieren, in-flight Requests abschließen (Timeout 30s), dann sauber beenden. `lifespan` shutdown-Phase erweitern | 0.5 Tage |
| B-SHUT-WS | **WebSocket Connection Draining** — bei Shutdown: WS-Clients über Reconnect-Hint informieren, Connections nach Grace-Period schließen. In B-WS Helpers integriert | 0.5 Tage |
| B-SHUT-WORKER | **ARQ Worker Graceful Stop** — laufende Jobs abschließen oder Checkpoint setzen (WorkflowRun `status='paused'`), keine Jobs abrupt abbrechen. `on_shutdown` erweitern | 0.5 Tage |
| B-SHUT-TEST | Tests: SIGTERM → in-flight Requests abschließen, WS drain, Worker checkpoint | 0.5 Tage |

### B.16 API Versioning Strategie

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-API-VER | **API Versioning Strategie** — `/api/v1` bleibt. Konvention dokumentieren: Breaking Changes → neue `/api/v2`-Router parallel, alte Routes deprecated für 1 Release, dann entfernt. Non-breaking Changes (neue Felder, neue Endpoints) innerhalb v1. Im Plugin-Dev-Guide ergänzen | 0.5 Tage |

### B.17 Cost Overrun Protection (Tenant-weit)

Bestehendes `budget_limit_usd` pro Agent-Definition schützt pro Agent-Run. Es fehlt ein Tenant-weites Cost-Cap das alle LLM-Calls (Agenten, Workflows, Search-Embeddings, Proactive) aggregiert.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| B-COST-CAP | **Tenant Cost-Cap** — `TenantSettings` um `llm_monthly_budget_usd` und `llm_hard_cutoff` ergänzen. Zentraler LLM-Client prüft vor jedem Call: Tenant-Monatskosten + Cost-Cap. Bei Überschreitung → Hard-Stop (nur noch kostenlose Calls) oder Alert. Cost-Tracking in Redis (inkrementell) | 1 Tag |
| B-COST-ALERT | **Cost Alerts** — bei 50%/80%/100% des Tenant-Budgets → System-Message im Workstream + E-Mail an Admin. Konfigurierbar | 0.5 Tage |
| B-COST-TEST | Tests: Cost-Cap greift, Alerts feuern, Hard-Stop blockiert LLM-Calls | 0.5 Tage |

**Deliverables Phase B:** Zentraler LLM Client, zentraler Redis Pool, gemeinsamer File Storage, WebSocket Helpers, Event-System dokumentiert, Schema Authority definiert, schlanker Plugin-Guide, MiniApp-Contribution-Wiring, klarer Plugin-Frontend-Vertrag, gezieltes Rate-Limiting, Sensitive Data Boundary + AI/Data Exposure Policy, AIProvider-Compliance-Metadaten, konsistente Lifecycle-Hooks + relevante Domain-Outbox-Events, gemeinsamer Trigger-Kern, vollständige Notification→Message-Konsolidierung, systematische Error-Handling-Infrastruktur (einheitliches Response-Format, Error-Kategorisierung, WS-Error-Handling, Error-Propagation-Konvention), Observability/trace_id-Korrelation, Graceful Shutdown/Connection Draining, API-Versioning-Strategie und Tenant-weites Cost-Cap/Alerts.

---

## Phase C — Core UI abschließen

**Dauer:** 4 Wochen
**Ziel:** Bereits weitgehend vorhandene Frontend-Funktionen verifizieren, fertigstellen und konsistent machen; kein paralleler UI-Neubau.

**Code-Stand:** Workspace-/Settings-/Agent-/Tag-/Custom-Field-/Saved-Filter-/Dedup-/Print-/Onboarding-/Theme-Bausteine sind im geprüften Frontend bereits vorhanden. Die Tasks dieser Phase bedeuten deshalb überwiegend **prüfen, vervollständigen, integrieren und testen**, nicht Greenfield-Bau.

**Noch nicht bauen:** History UI (Phase D), Workflow/Webhook UI (Phase G), Backup UI nur bei konkretem Bedarf. Import/Export folgt separat in Phase C.5 auf einer kleinen modularen Backend-Basis.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| C-NAV-WS-UI | Workspace-Editor UI — Module auswählen, Unterpunkte/Reihenfolge, Drag-and-Drop | 2-3 Tage |
| C-NAV-WS-DEFAULT | Standard-Workspace konfigurierbar — zeigt alles was für User freigeschaltet ist | 1-2 Tage |
| C-NAV-WS-BACK | Workspace Zurück-Button zum Startbildschirm | 0.5 Tage |
| C-NAV-AGENT | Agentenverwaltung als eigene Seite (Standalone-Layout, nur Topbar + Zurück) | 1-2 Tage |
| C-NAV-SETTINGS | Einstellungen als eigene Seite (vertikale Reiter, nur Topbar + Zurück) | 1-2 Tage |
| C-NAV-LAYOUT | Seiten-Layout-Typen: Workspace-Layout vs Standalone-Layout | 1 Tag |
| C-NOTIF | **TopBar Message/Notification UI fertigstellen** — Unread Badge und Dropdown für typisierte System-/Notification-Messages aus dem zentralen Communication-System; Klick öffnet System-Channel oder verlinkte Entity | 1-2 Tage |
| C-TAGS | Tags UI — Tag-Manager, Tag-Filter | 2 Tage |
| C-CF | Custom Fields UI — Editor, Anzeige in Detail | 2-3 Tage |
| C-FILTER | Saved Filters — speichern, laden, teilen | 2 Tage |
| C-DEDUP | Dedup/Merge UI für Kontakte | 2-3 Tage |
| C-PRINT | Print/PDF für Contact/Company | 1 Tag |
| C-DOCS | API Docs UI (Swagger-UI Embed) | 0.5 Tage |
| C-ONBOARD | Onboarding-Wizard für neue Nutzer | 1-2 Tage |
| C-THEME | CSS Custom Properties + Dark Mode + Design Tokens. Theme-Editor/Presets später | 2 Tage |
| C-A11Y | Accessibility ergänzen — sr-only Texte, ARIA-Live-Regions | 1 Tag |
| C-PWA | **PWA behalten und Service Worker sauber reaktivieren** — kontrollierte Cache-Strategie für App-Shell und statische Assets, sauberes Update-/Cache-Invalidierungsverhalten. API-, Auth-, Tenant- und Permission-sensitive Daten nicht pauschal cachen. Keine Offline-Sync-/Offline-ERP-Architektur | 0.5 Tage |
| C-FE-CLEAN | Frontend bereinigen: neue/geänderte Dateien sauber (keine any, keine inline styles wo vermeidbar). Bestehende nur bei Fehler/Security/Inkonsistenz | fortlaufend |
| C-ERR-BOUNDARY | **Frontend Error Boundaries** — ErrorBoundary-Komponente + Plugin-ErrorBoundary-Wrapper. Jede Plugin-Seite, MiniApp und kritische Komponente wird von einer ErrorBoundary umschlossen. Ein fehlerhaftes Plugin darf nicht die ganze App crashen. Fallback-UI mit `trace_id` und „Neu laden"-Button | 1 Tag |
| C-FE-TEST | Fehlende Frontend-Tests ergänzen: Vitest für neue Komponenten, API-Client-Tests, Hook-Tests | 3 Tage |
| C-DOC | `docs/ui-design-guidelines.md` aktualisieren | 1 Tag |

**Deliverables Phase C:** Stabile Navigation, Workspace-UI, Settings-Seite, Agentenverwaltung-Seite, TopBar Message/Notification UI auf dem zentralen Message-System, Tags, Custom Fields, Saved Filters, Dedup, Print, Onboarding, Theme-Basis, Accessibility, PWA mit reaktiviertem Service Worker und Frontend Error Boundaries.

---

## Phase C.5 — Modularer Import/Export

**Dauer:** 2 Wochen
**Ziel:** Die bereits vorhandene Import/Export-Implementierung in wiederverwendbare technische Bausteine konsolidieren, ohne eine universelle Ein-Endpunkt-/Ein-Modell-Engine zu bauen. Fachmodule behalten eigene Handler/Endpoints und nutzen dieselben Parser-, Mapping-, Validation- und Job-Bausteine.

**Code-Stand:** `import_export_service.py`, Routes sowie Import/Export-Frontend existieren bereits; Contact/Company sind kein Greenfield. Phase C.5 macht daraus die kleine modulare Referenzbasis und ergänzt Mapping/Preview/Background-Verarbeitung, wo noch nötig.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| C5-BASE | **Shared Import/Export Helpers** — CSV, JSON, XLSX Parser/Writer, Encoding, Schema-/Field-Mapping, Validation und strukturierte Fehlerberichte | 2 Tage |
| C5-PREVIEW | **Import Preview & Mapping** — Preview vor Commit, Spalten-Mapping, Validierungsfehler sichtbar machen | 2 Tage |
| C5-JOB | **Background Processing** — große Imports/Exports über vorhandenes ARQ, Fortschritt/Status; keine neue Job-Infrastruktur. **Partial-Failure-Semantik**: bei Teilausfällen `partial_success` Status mit klarem Fehler-Report (welche Zeilen/Records committed, welche fehlgeschlagen), kein stummes Versagen, kein inkonsistenter Zustand | 1.5 Tage |
| C5-CONTACT | **Contact Import/Export** — erster vollständiger fachlicher Handler auf gemeinsamer Basis | 1 Tag |
| C5-COMPANY | **Company Import/Export** — zweiter fachlicher Handler, beweist Wiederverwendbarkeit ohne Universalmodell | 1 Tag |
| C5-UI | **Modulare Import/Export UI** — fachmodulspezifisch nutzbare Mapping-/Preview-Komponenten | 2 Tage |
| C5-TEST | Tests: Mapping, Validation, große Jobs, Tenant-/Permission-Kontext, Sensitive Fields | 1.5 Tage |
| C5-DOC | Plugin-Dev-Guide: wie Module eigene Import/Export-Handler auf Shared Helpers aufsetzen | 0.5 Tage |

**Spezialformate:** ICS, EML, DMS-ZIP, PST etc. nur dort implementieren, wo der fachliche Use Case besteht. Keine Universalengine, die jedes Format erzwingt.

**Deliverables Phase C.5:** Gemeinsame CSV/JSON/XLSX-Basis, Preview/Mapping/Validation, ARQ-Verarbeitung für große Jobs, Contact/Company als Referenzimplementierungen und modulare UI-Bausteine.

---

## Phase D — Minimal Undo/Restore

**Dauer:** 4 Wochen
**Ziel:** Bestehende EntityHistory/History-UI gezielt zu echtem Undo/Restore für ausgewählte Businessobjekte vervollständigen. Keine universelle Migration aller History-/Versionssysteme.

**Code-Stand:** generisches History-Recording/Lesen und UI-Bausteine existieren bereits; Restore ist derzeit noch fachlich begrenzt. Deshalb vorhandenen Service erweitern, nicht ersetzen.

### Was in EntityHistory aufgenommen wird

Contact, Company, Task, Calendar Event, DMS-Metadaten. Weitere nur bei echtem Bedarf.

### Was separat bleibt

- AgentVersion (Konfigurations-Versionierung)
- AutomationVersion (Automations-Definition-Versionierung)
- CommMessageEdit (Chat-Edit-History)
- ContactMergeHistory (Merge-Protokoll)
- AuditLog (Compliance)
- WorkflowStepHistory (Runtime-Protokoll)
- Backup (Disaster Recovery)

### History-Aufzeichnung: ein Mechanismus

Hook-basiert: `do_action('entity.after_create/after_update/after_delete')` → `record_history()`. Explizit, nachvollziehbar, testbar. Keine SQLAlchemy Event Listener (ORM-Magie).

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| D-GEN | `restore_from_history()` generisch machen, aber **nur für explizit registrierte Entity-Typen**. Registry definiert Model, Restore-Erlaubnis, erlaubte Restore-Felder, Permission-Check und optionalen Sonderhandler. Kein dynamisches beliebiges ORM-Laden, kein blindes Snapshot-Zurückschreiben | 1 Tag |
| D-HOOK | Hook-basierte History: Standard-Hooks die `record_history()` aufrufen für registrierte Entities | 1 Tag |
| D-CORE | Contact, Company: `record_history()` in allen CRUD-Operationen (bereits teilweise vorhanden) | 1 Tag |
| D-PLUG | Task, Calendar, DMS-Metadaten: `record_history()` in Services | 2 Tage |
| D-SOFT | Soft-Delete + Restore für alle EntityHistory-Entitäten | 1 Tag |
| D-MAIL | **Mail Sonderbehandlung** — eigener Restore-Handler mit echter IMAP-/DB-Semantik: Delete nach Möglichkeit als Move in serverseitigen Trash, Restore zurück in ursprünglichen Ordner (falls vorhanden), notwendige Folder-/IMAP-Referenzen speichern. Serverfehler dürfen keinen falschen lokalen Status erzeugen. Kein „Undo Send“-Versprechen für bereits zugestellte externe Mails | 2 Tage |
| D-TRASH | Trash-View UI — alle gelöschten Entitäten nach Typ filterbar, Multi-Select-Restore | 1 Tag |
| D-TOAST | Undo-Toast — nach Aktion Toast "Gelöscht — Undo?" für 5 Sekunden | 1 Tag |
| D-HIST-UI | History-Panel pro Entität — Timeline, Diff-View, Restore-Button | 2 Tage |
| D-BULK | **Bulk-Restore** — Multi-Select im Trash ruft für jedes ausgewählte Objekt denselben vorhandenen Restore-Service mit Tenant-/Permission-Checks auf. Keine Batch-History-, Transaktionsgruppen- oder eigene Bulk-Undo-Architektur. **Partial-Failure-Semantik**: bei Teilausfällen `partial_success` mit Fehler-Report (welche Objekte restored, welche fehlgeschlagen), kein stummes Versagen | 1.5 Tage |
| D-RET | Retention-Policy — EntityHistory älter als 90 Tage archivieren. GDPR-Hard-Delete | 0.5 Tage |
| D-TEST | Tests: Restore funktioniert, Snapshots korrekt, Sensitive Fields ausgeschlossen, Mail-IMAP-Trash | 2 Tage |
| D-DOC | `docs/test-strategy.md`, `docs/security_kernel.md` aktualisieren | 1 Tag |

**Deliverables Phase D:** EntityHistory für Businessobjekte (Contact, Company, Task, Calendar, DMS), generisches Restore, Hook-basierte History, Mail-Sonderbehandlung, Trash-View, Undo-Toast, History-Panel, Bulk-Undo, Retention.

---

## Phase E — Unified Search vollständig

**Dauer:** 6 Wochen
**Ziel:** Die bestehende SearchProvider-/Hybrid-Search-/pgvector-/GraphRAG-Basis zu einer gemeinsamen Search-Architektur mit FTS + Vector + RAG + Graph konsolidieren und vervollständigen. Nicht jede Entity muss jeden Modus unterstützen.

**Code-Stand:** FTS, Vector Search, pgvector/HNSW, RRF-Fusion, mehrere SearchProvider und GraphRAG-Grundlagen existieren bereits. Der Schwerpunkt liegt auf Vereinheitlichung, Document-RAG, Permission-Konsistenz und einem einzigen Indexierungsweg — nicht auf Neubau.

### Such-Modi

| Modus | Was |
|---|---|
| FTS | PostgreSQL tsvector/tsquery |
| Vector | pgvector cosine similarity |
| RAG | Document-Chunking + Chunk-Embeddings + Retrieval |
| Graph | GraphRAG BFS-Traversal |

### Provider deklarieren Modi

Provider deklariert `supports_fts`, `supports_vector`, `supports_rag`, `supports_graph`. Nicht alles in alles zwingen.

### Sinnvolle globale Suche

Contacts, Companies, Mail, DMS, Tasks, Calendar, Communication, AI Chats, Wiki/Knowledge.

Nicht: AuditLog, EntityHistory, SystemSettings, technische Logs.

### Globale + modulspezifische Suche auf demselben Kern

Es gibt ausdrücklich **beides**:
- eine globale Unified Search über die Plattform
- modulspezifische Suchoberflächen/-Endpoints in Mail, DMS, Tasks usw.

Die spezifischen Suchen bleiben für gute Fach-UX erhalten, laufen technisch aber über dieselben SearchProvider, Permission-/Tenant-Regeln und dieselbe FTS/Vector/RAG/Graph-Infrastruktur. **Keine parallele eigene Suchlogik pro Modul.** Agent Memory und weitere Module werden ebenfalls über SearchProvider angebunden.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| E-PROV | SearchProvider-Schnittstelle mit `supports_fts/vector/rag/graph` Flags. **Provider-Registration erfolgt zur Plugin-Aktivierungszeit** (`auto_register_providers`), nicht dynamisch zur Laufzeit. Neue Provider benötigen Plugin-Reaktivierung | 1 Tag |
| E-FTS | FTS für alle Provider die es unterstützen | 1 Tag |
| E-VEC | Vector Search für alle Provider die es unterstützen | 1 Tag |
| E-CHUNK | Document-Chunking für DMS (semantische Chunks) | 2 Tage |
| E-EMB | Chunk-Embeddings (pgvector, ARQ Background Job) | 2 Tage |
| E-RAG | RAG Retrieval (Query → Semantic Search über Chunks → Top-K) | 2 Tage |
| E-GRAPH | Graph Traversal (GraphRAG BFS) | 1 Tag |
| E-FUSE | RRF Result-Fusion über alle Modi | 1 Tag |
| E-LLM | LLM Query Understanding (Intent, Entities, Semantic Terms) — über zentralen LLM Client | 1 Tag |
| E-PERM | Permission-aware Search (Tenant, RBAC, Visibility-Filter) | 1 Tag |
| E-IX-EVT | Auto-Indexierung: Mutation → Outbox → Worker → Index aktualisieren. Ein Weg, nicht Hook + EventBus parallel. **Index-Fehler-Handling**: bei Embedding-LLM-Fehlern, pgvector-Errors oder Timeouts → Retry über Outbox-DLQ, Dead-Letter bei permanentem Fehler, Index-Konsistenz-Check. Kein stummes Fehlschlagen von Suchergebnissen. **Concurrency**: zwei Events die dasselbe Dokument indexieren → dedup über `entity_type+entity_id+version` Lock, kein verlorenes Update | 2.5 Tage |
| E-IX-RE | Re-Indexierung: Batch-Reindex Kommando, Delete-Handling, Retry | 1 Tag |
| E-DATA-LIFE | **Derived-Data Lifecycle für Search/Vector** — Correction/Delete/Erasure-Signal aktualisiert oder entfernt FTS-/Search-Dokumente und Embeddings reproduzierbar; Rebuild aus authoritative Quelle möglich. Retention-/Legal-Hold-Entscheidung bleibt fachlich konfiguriert | 1.5 Tage |
| E-K-MAIL | Mail-spezifische Suche behalten, interne ILIKE-Logik aber auf `MailSearchProvider`/Unified Search Core umstellen | 1 Tag |
| E-K-DMS | DMS-spezifische Suche behalten, interne Suchlogik aber auf `FileSearchProvider`/Unified Search Core umstellen | 1 Tag |
| E-K-TASKS | Task-spezifische Suche behalten, interne Suchlogik aber auf `TaskSearchProvider`/Unified Search Core umstellen | 0.5 Tage |
| E-K-MEM | Agent Memory eigene Suche → SearchProvider | 1 Tag |
| E-P-AI | AI Chat Search Provider (AIChatSession, AIChatMessage) | 1 Tag |
| E-P-COMM | Communication Search Provider (CommMessage, CommConversation) | 1 Tag |
| E-P-WF | Workflow Search Provider | 0.5 Tage |
| E-API | REST API `/api/v1/search` mit Filter-Parametern | 0.5 Tage |
| E-TOOL | Tool Registry: `unified_search` als AI Tool | 1 Tag |
| E-MCP | MCP-Exposure für Search als **dünne Schicht auf dem bestehenden Search-Tool/Service**. Auth-/Run-as-Kontext und normale RBAC/ABAC-/Tenant-Prüfungen bleiben maßgeblich; MCP erhält keine eigenen Rechte | 1 Tag |
| E-UI-CMD | Command Palette (Cmd+K) — globale Suche | 2 Tage |
| E-UI-FAC | Facetten-Filter, Preview-Cards, Click-through, Saved Searches | 2 Tage |
| E-TEST | Tests: FTS, Vector, RAG, Graph, Permission-Filter, Auto-Index, Sensitive Fields ausgeschlossen | 3 Tage |
| E-DOC | `docs/api-documentation.md`, `docs/plugin-development-guide.md` (Search-Kapitel) | 1 Tag |

**Deliverables Phase E:** Unified Search mit FTS+Vector+RAG+Graph, Provider deklarieren Modi, Auto-Indexierung (Outbox→Worker), konsistenter Correction/Delete-Lifecycle für Search/Vector, KI-nutzbar (Tool, MCP, API), Command Palette sowie globale und modulspezifische Suchen auf demselben Search-Kern.

---

## Phase F — Agent MVP

**Dauer:** 6 Wochen
**Ziel:** Die vorhandene Agentenbasis zu autonomen KI-Agenten mit echtem ReAct-Loop, Skills, sicherem Permission-/Run-as-Kontext und Workstream-Integration vervollständigen. Keine Agent-Rollenarchitektur.

**Code-Stand:** `AgentDefinition`, `AgentVersion`, `AgentRun`, `AgentSubtask`, früher Coordinator/Runner und Agent-UI existieren bereits. Der aktuelle Runner ist jedoch noch kein vollständiger mehrstufiger ReAct-Loop. Ein explizites Skill-Modell/Registry wurde im Audit nicht gefunden und wird deshalb klein ergänzt.

### Permission-Modell

Effektive Fähigkeiten = User-/Run-as-Permissions ∩ Agent-Freigaben ∩ Skill-Freigaben ∩ Tool-Freigaben.
- Interaktive Runs: `run_as = aktueller Benutzer`
- Geplante/autonome Runs: expliziter Service-/Run-as-User
- Sichtbarkeit, Ausführbarkeit und effektive Tool-/Skill-Berechtigung sind getrennte Prüfungen
- Jeder Tool-/Service-Aufruf prüft den **aktuellen** User-/Run-as-Kontext erneut; Rechte werden nicht für einen Run eingefroren
- Skills orchestrieren Fähigkeiten, verleihen aber niemals zusätzliche Rechte
- Keine parallele Agent-/Skill-Rollenarchitektur

### Agent UI & Trace

Zwei Darstellungsmodi:
- **Standard:** Status, Tool Calls, Tool Results, Fortschritt, Kosten, Fehler, finale Antwort
- **Extended Trace:** zusätzlich kurze, strukturierte Entscheidungsbegründungen/Zwischenzusammenfassungen für den Nutzer

Kein vollständiger interner Chain-of-Thought; der Extended Trace ist ein explizit erzeugter, sicherer Entscheidungs-/Aktions-Trace.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| F-LOOP | `agent_loop.py` — ReAct-Loop mit LiteLLM `acompletion()` + `tools=` über zentralen LLM Client. Multi-Step-Reasoning, Tool-Call-Parsing, Error-Recovery, Graceful-Stop, Streaming — komplexer als ein einzelner LLM-Call. **LLM-Fehlerstrategie**: Provider-Rate-Limit → Backoff+Retry; Provider-Timeout → Graceful-Stop mit Fehlermeldung; Provider-Ausfall → Failover auf konfigurierten Backup-Provider; Max-Retries → Run beenden mit Fehler-Trace | 5.5 Tage |
| F-CALL | Tool-Call-Parser — extrahiert function_calls, ruft ToolRegistry auf | 1 Tag |
| F-CTX | Context-Builder — System-Prompt, Agent-Definition, relevanter User-/Tenant-Kontext, relevantes Memory, freigegebene Skills und Tool-Schemas. Zusätzliche API-/Domain-Dokumentation nur gezielt/on-demand; keine pauschale Vollinjektion der CRM-API-Spec | 2 Tage |
| F-MAX | Max-Steps-Limit + Graceful-Stop | 0.5 Tage |
| F-ERR | Error-Handling: Tool-Fehler → LLM bekommt strukturierte Error-Message mit `ErrorCategory` (TRANSIENT/PERMANENT/PARTIAL). Transient → LLM kann entscheiden zu retry-en; Permanent → LLM muss Strategie ändern; Partial → LLM bekommt Teilerfolg-Report. Keine rohen Tracebacks an LLM | 1.5 Tage |
| F-STR | SSE-Streaming mit **Standard- und Extended-Trace-Modus**: Status, Tool-Calls/-Results, Fortschritt, Kosten, Fehler, finale Antwort; optional zusätzlich strukturierte kurze Entscheidungsbegründungen/Zwischenzusammenfassungen | 1 Tag |
| F-DEF | Bestehende AgentDefinition CRUD/API/Versionierung verifizieren und nur fehlende Felder/Contracts für Runtime, Skills, Trigger und Limits ergänzen | 1 Tag |
| F-AIUSE | **AI Use-Case Metadata** — für relevante Agent-/AI-Funktionen `intended_purpose`, Owner, Datenklassen, zugelassene Provider/Modelle, zulässige Aktionen, Oversight-Policy und konfigurierbare Risikoklasse erfassen. Kein juristischer Auto-Klassifizierer | 1 Tag |
| F-TRANS | **AI Transparency** — Agent-/AI-Teilnehmer im Workstream und relevanten UIs eindeutig als AI kennzeichnen; generierte Inhalte können typisierte Herkunfts-/Kennzeichnungsmetadaten tragen | 0.5 Tage |
| F-SKILL | **Kleiner Skill-Baustein** — `SkillDefinition`/Registry + `skill_definitions`-Plugin-Contribution (oder gleichwertig) mit Name/Beschreibung/Instructions, erlaubten Tool-IDs und optionaler Context-Policy. Skills sind Orchestrierungsmetadaten, **keine Rechtequelle**, kein `SkillRole`, kein zweites RBAC | 1.5 Tage |
| F-TOOL | Tool-/Skill-Binding — Agent definiert, welche Tools und Skills er nutzen darf. Skills dürfen nur freigegebene Tools/Services orchestrieren und keine Permissions umgehen | 1 Tag |
| F-PERM | Permission-Context: Agent agiert im Kontext eines Users/Run-as. RBAC/ABAC pro Tool-/Service-Aufruf, Visibility-Filter und EntityPermission. Effektiv: User/Run-as ∩ Agent ∩ Skill ∩ Tool. Aktuelle Rechte bei jedem Call neu prüfen. **Concurrency**: zwei Agenten die dieselbe Entity mutieren → optimistisches Locking über `version`-Feld oder Row-Level Lock, kein verlorenes Update | 2.5 Tage |
| F-PERM-VIS | User-Agent Visibility: User sehen nur Agenten die für sie freigeschaltet sind (`agents:read` + EntityPermission). Über bestehendes RBAC/ABAC | 1 Tag |
| F-PERM-USE | User-Agent Usage: `agents:execute` Permission pro Agent | 0.5 Tage |
| F-MEM | Memory-Integration — agent_memory Plugin | 1 Tag |
| F-PROACTIVE | **Bestehende Proactive AI konsolidieren** — vorhandene `ContextLog`/`ProactiveSuggestion`-/Context-Event-Basis in den gemeinsamen Trigger-/Agent-Kern integrieren. Primär Domain-/UI-/andere Trigger; zeitabhängige Prüfungen nur über vorhandenen Cron/Heartbeat/ARQ. Kein neuer Polling-Mechanismus | 1 Tag |
| F-APPR | **Agent Action Approval + zentraler ApprovalRequest-Kern** — Tool-/Skill-Aktionen können per Policy/Metadaten approval-pflichtig sein (nicht nur destruktiv; auch extern, irreversibel oder sensibel). Da Agents vor Phase G kommen, wird hier der minimale **zentrale** `ApprovalRequest`-Kern angelegt/vereinheitlicht; Phase G baut nur den Workflow-Step/Queue darauf. Keine separate Agent-Approval-Engine | 2 Tage |
| F-DRY | Dry-Run-Mode | 0.5 Tage |
| F-AUDIT | Audit-Log für jeden Tool-Call | 1 Tag |
| F-OVERSIGHT | **Human-Oversight / Decision Record** — Use-Cases können bestimmte personen-/risikorelevante Aktionen zwingend vor Außenwirkung an `ApprovalRequest` binden; Recommendation/Evidence, Reviewer, Entscheidung, Zeitpunkt und Abweichung nachvollziehbar speichern | 1 Tag |
| F-DATA-POL | **Runtime Provider/Data Policy Enforcement** — Agent/Context Builder/LLM Client respektieren B-DATA-POL und B-AIPROV-COMP; nicht erlaubte Felder/Provider werden vor dem LLM-Call geblockt bzw. minimiert | 1 Tag |
| F-UI-CTRL | **Bestehendes AI UI Control als Agent-Tool integrieren/erweitern** — Navigation, Filter, Tabs, Modals, Ansichten, Form-Prefill und UI-Kontext steuern. **Persistente fachliche Mutationen ausschließlich über reguläre Tools/Services mit bestehenden Permission-Prüfungen**; `ai_ui_control:write` darf keine Fachrechte umgehen. Feedback-Loop: Agent → REST/WebSocket → Frontend → Feedback → Agent | 1.5 Tage |
| F-UI-TRIG | **Bestehende UI-Context-Events zum allgemeinen UI-Trigger ausbauen** — Frontend-Events (`ui.contact_selected`, `ui.page_navigated`, `ui.mail_opened`, `ui.task_status_changed` etc.) triggern Agenten/Proactive Suggestions **ephemer über EventBus/Redis + gemeinsamen Trigger-Dispatcher, nicht über Outbox**. Trigger im Agent-Editor konfigurierbar; Bedingungen nutzen vorhandene Condition-Logik. Sobald ein Agent startet, wird `AgentRun` persistent gespeichert | 2 Tage |
| F-WORK | **Agent → zentraler Workstream** — Agenten posten Text, Status, `action_card`, Entity-/Contact-Cards, Knowledge-Quellen, Approval- und `miniapp`-Blocks über das bestehende Communication-System. Kein zweites Agent-Message-/Chat-Modell | 1.5 Tage |
| F-UI-LIST | Agent-Liste — Kartenansicht und Listenansicht (Toggle) | 1.5 Tage |
| F-UI-EDIT | Agent-Editor — System-Prompt, Modell, Tools, Limits, Trigger | 2 Tage |
| F-UI-CHAT | Agent-Chat-UI — interaktive Konversation | 2 Tage |
| F-UI-LOG | Agent-Run-Log — Aktionen, Tool Calls, Resultate, Status, Kosten, Fehler | 1 Tag |
| F-UI-MON | Agent-Monitoring — Live-Status, aktive Runs, Budget | 1 Tag |
| F-EMAIL | Pre-Built: E-Mail-Triage-Agent | 2 Tage |
| F-CONTACT | Pre-Built: Contact-Enrichment-Agent | 1 Tag |
| F-FOLLOW | Pre-Built: Follow-up-Agent | 1 Tag |
| F-REPORT | Pre-Built: Report-Agent | 1 Tag |
| F-TEST | Tests: ReAct-Loop, Tool-Calling, Permissions, Approval, Budget-Limits | 3 Tage |
| F-DOC | `docs/api-documentation.md`, `docs/plugin-development-guide.md` (Agent-Kapitel) | 1 Tag |

### F.14 Unified Task System

Das bestehende Tasks-Plugin (713 Zeilen, nur `contact_id`, nur User-Assignment) wird zu einem **systemweiten Assignment-System** upgegradet. Kein zweites System, sondern das bestehende Tasks-Plugin das erwachsen wird. AI, Menschen, Gruppen und Workflows können Aufgaben erstellen, zugewiesen bekommen und mit jedem Objekt verknüpfen.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| F-TASK-MODEL | **Task-Modell erweitern** — `assignee_type` (user/agent/group) + `assignee_id` (polymorph), `entity_type` + `entity_id` (polymorph, wie EntityLink), `creator_type` (user/agent/workflow/system) + `creator_id`, `parent_task_id` (Self-Reference für Subtasks), `depends_on` (Task-Dependencies), `task_type` (todo/approval/follow_up/review/**goal**/**milestone**), `success_criteria` (JSON — wann ist Ziel erreicht?), `target_date` (Deadline für Goal/Milestone), `progress` (aggregiert aus Child-Tasks, 0-100%), Lifecycle: open/in_progress/review/blocked/done/cancelled | 2.5 Tage |
| F-TASK-API | **Task API erweitern** — bestehende Tasks-Routes um polymorphe Entity-Links, polymorphe Assignees, Subtasks, Dependencies und neue Lifecycle-Status ergänzen. Bestehende Contact-Tasks bleiben kompatibel | 1.5 Tage |
| F-TASK-AGENT | **Agent ↔ Task Integration** — Agenten können Tasks erstellen (`create_task` Tool), Tasks zugewiesen bekommen (`assignee_type='agent'`), Task-Status aktualisieren und Tasks als Subtasks zerlegen. `AgentSubtask` wird zu `Task` mit `task_type='agent_subtask'` migriert. **Goal Decomposition**: Agent kann ein Goal erhalten und es in Milestones/Tasks/Subtasks zerlegen (`decompose_goal` Tool) | 2 Tage |
| F-TASK-WORK | **Task → Workstream** — Tasks erscheinen als `task_card` Block-Typ im Communication-System: Titel, Assignee, Due-Date, Status, Entity-Deep-Link, Action-Buttons (Done/Reassign/Comment). Status-Änderungen posten Updates in den Workstream. Goals/Milestones erscheinen als `goal_card` Block mit Progress-Bar, Success-Criteria, Target-Date und Child-Task-Übersicht | 1.5 Tage |
| F-TASK-UI | **Task UI erweitern** — Task-Liste mit Filter (nach Assignee, Entity, Status, Due-Date, Task-Type), Task-Detail mit Subtasks/Dependencies, Task-Board (Kanban-View optional), Task-Assignment-Dropdown (User/Agent/Group). **Goal-Views**: Goal-Übersicht mit Progress-Bar, Goal-Detail mit Milestone/Task-Hierarchie-Baum, Success-Criteria-Checkliste | 2.5 Tage |
| F-TASK-MIG | **Migration** — bestehende `Task.contact_id` → `entity_type='contact' + entity_id`, `Task.assigned_to` → `assignee_type='user' + assignee_id`. `AgentSubtask` → `Task` mit `task_type='agent_subtask'`. Daten-Migration + View für Übergang | 1 Tag |
| F-TASK-GOAL | **Goal/Milestone Logik** — `progress`-Aggregation: Parent-Task/Goal/Milestone Progress wird aus Child-Task-Status berechnet (0-100%). `success_criteria`-Evaluation: strukturierte Kriterien die manuell oder per Agent/Workflow gecheckt werden können. Goal ist `done` wenn alle Success-Criteria erfüllt ODER alle Child-Tasks `done` sind (konfigurierbar). Milestone ist `done` wenn alle Child-Tasks `done`. Parent-Status-Propagation: wenn alle Child-Tasks `done` → Parent wird automatisch `review` (konfigurierbar) | 1.5 Tage |
| F-TASK-TEST | Tests: Polymorphe Assignment, Entity-Links, Subtasks, Agent-Task-Creation, Goal-Decomposition, Progress-Aggregation, Success-Criteria-Evaluation, Workstream-Integration, Migration | 2 Tage |

**Deliverables Phase F:** ReAct-Agenten auf vorhandener Agentenbasis, kleiner Skill-Baustein, Tool-/Skill-Calling, Permission-Modell (User/Run-as ∩ Agent ∩ Skill ∩ Tool) mit Concurrency-Schutz, AI-Use-Case-/Transparency-Metadaten, Provider/Data-Policy-Enforcement, Standard+Extended Trace, LLM-Fehlerstrategie (Rate-Limit-Backoff, Provider-Failover, Timeout-Graceful-Stop), strukturiertes Tool-Error-Handling mit ErrorCategory, trigger-basierte Proaktivität, UI Control ohne Permission-Bypass, zentraler ApprovalRequest-Kern + Human-Oversight-Record, Workstream-Ausgabe, Agent UI, 4 Pre-Built Agenten und Unified Task System mit Goals (polymorphe Assignment, Entity-Links, Subtasks, Goal/Milestone-Hierarchie, Progress-Aggregation, Success-Criteria, Agent Goal-Decomposition, Workstream-Integration).

---

## Phase G — Workflow MVP

**Dauer:** 6 Wochen
**Ziel:** Die vorhandene Workflow-/Automation-Basis zu einer robusten CRM-/Business-Automation ausbauen. Form+JSON Editor. Kein visueller Canvas. Kein Raw SQL. Kein Code-Node.

**Runtime-Invariante:** `Workflow`/`WorkflowRun` ist die authoritative langlebige Multi-Step-Engine. `AutomationDefinition` bleibt die leichte Trigger/Condition/Action-/Scheduler-Schicht und darf Workflows starten, wird aber **keine zweite durable Workflow-Engine**.

**Abgrenzung:**
- **AutomationDefinition** = einfache Event-Reaktion: 'Wenn Event X → führe Action Y aus'. Single-Step, nicht-durable, keine Resume-Semantik. Beispiele: 'Mail empfangen → Notification senden', 'Contact erstellt → Proactive Suggestion'.
- **Workflow** = komplexe Multi-Step-Prozesse: 'Warte auf Approval → führe 5 Steps aus → Warte 3 Tage → finalisiere'. Durable, resumable, mit ExecutionContext und Idempotency.
- **Automation kann Workflows starten** (Trigger → `start_workflow`), aber nicht umgekehrt.
- **Beide nutzen denselben Trigger-Kern** (B.11) und denselben ApprovalRequest-Mechanismus (F-APPR/G-APPROVAL).

**Code-Stand:** persistente Workflow-Instanz/Step-History, Conditions und Approval-Pause sowie AutomationDefinition/Run/Version/Cron existieren bereits. Phase G erweitert diese Basis um allgemeines Resume/Wait, Idempotency, neue Business-Steps und Agent-/Workstream-Integration.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| G-COND | Condition-Step (bestehend, erweitern) | 0.5 Tage |
| G-WAIT | **Wait/Delay-Step — persistent/resumable**: WorkflowRun speichert `status`, `current_step`, `execution_context` sowie `resume_at` bzw. Wait-Kriterium. Worker beendet sich während Wartezeiten und setzt den Run später über vorhandenen ARQ/Cron/Event-Pfad fort; kein langes `sleep()`/blockierender Worker | 1 Tag |
| G-HTTP | **HTTP-Request-Node** — Method/URL/Headers/Body/Response-Mapping plus Timeout, maximale Response-Größe, SSRF-Schutz für private/interne Ziele, kontrollierte Protokolle/Redirects und Credentials ausschließlich über sicheren Credential-/Secret-Mechanismus statt Workflow-JSON | 1-1.5 Tage |
| G-MAIL | Mail-Send-Node | 0.5 Tage |
| G-CAL | Calendar-Node | 0.5 Tage |
| G-DMS | DMS-Node | 0.5 Tage |
| G-SEARCH | Search-Node (Unified Search) | 0.5 Tage |
| G-AGENT | Agent-Step (ruft autonomen Agenten auf) | 1 Tag |
| G-CRM | CRM-Action-Node (create/update Contact, etc.) | 1 Tag |
| G-EVT | Event-Trigger (CRM-Event startet Workflow) | 1 Tag |
| G-CRON | Cron-Trigger (bestehender Scheduler erweitern) | 0.5 Tage |
| G-WEB | **Incoming Webhook-Trigger** — externer HTTP-Call startet Workflow über sicheren token-/permission-basierten Endpoint, Rate-Limit und Payload-Validation; nutzt gemeinsamen Trigger-/Execution-Kern aus B.11 | 1 Tag |
| G-MAN | Manual-Trigger (Button in UI) | 0.5 Tage |
| G-RETRY | **Retry-Logic für fehlgeschlagene Steps** — Retry/Backoff über vorhandenen Execution-/ARQ-Pfad. Side-Effect-Steps müssen soweit erforderlich idempotent bzw. über Execution-/Idempotency-Key vor Doppel-Ausführung geschützt sein | 1.5 Tage |
| G-LOG | Execution-Log pro Step (Input, Output, Duration, Status) | 1 Tag |
| G-WORK | **Workflow/System → zentraler Workstream** — typisierte Status-, Handoff-, Approval-, Action- und MiniApp-Blocks über Communication posten. Bestehende Workflow-`notification`-Produzenten auf zentrales Message-System umstellen; kein separates Workflow-Notification-System | 1 Tag |
| G-APPROVAL | **Generischer Approval-Step auf zentralem `ApprovalRequest`** — den in Phase F angelegten gemeinsamen Kern für Workflows verwenden/erweitern; für beliebige Workflows, Entities und Aktionen nutzbar; Approver/Gruppe, `pending/approved/rejected/expired`, Referenz auf Workflow/Run/Aktion, Kommentar, Zeitstempel, System-Message, Approval-Queue, Audit und optional Timeout. **Keine pauschalen `pending_approval/active/rejected`-Statusfelder auf allen Entities**; fachliche Status nur im jeweiligen Modul, wenn benötigt. Derselbe Mechanismus wird von Agent-Approvals verwendet | 2.5 Tage |
| G-HUMAN-DEC | **Automated-Decision Guard** — für entsprechend konfigurierte AI-Use-Cases dürfen Workflow-/Agent-Ergebnisse keine definierte personen-/risikorelevante Außenwirkung automatisch auslösen, bevor die geforderte Human-Review-/Approval-Policy erfüllt ist. Kein pauschaler Zwang für normale CRM-Automation | 1 Tag |
| G-CTX | **Persistenter Execution-Context** — Daten-Flow zwischen Steps (Variablen, Expressions) wird zusammen mit WorkflowRun dauerhaft gespeichert und kann nach Wait, Restart, Worker-Crash oder Event-Resume fortgesetzt werden | 2 Tage |
| G-RUN | **Durable WorkflowRun / Resume-Semantik** — bestehendes `WorkflowInstance`-Model wird zu `WorkflowRun` erweitert/umbenannt. Run-State, Step-State und Resume-Grund (`resume_at`, Event/Approval/Webhook) persistent halten. Resume lädt denselben Run und setzt exakt am vorgesehenen Step fort; keine zweite Workflow-Runtime. **Concurrency**: zwei Worker die denselben Run resume → Redis-Lock pro `WorkflowRun.id`, nur ein Worker resume, anderer wartet oder überspringt | 2 Tage |
| G-IDEMP | **Idempotency-/Deduplizierungsschutz für Side Effects** — Side-Effect-Steps (z. B. Mail, HTTP, CRM-Mutation) erhalten pro Execution einen stabilen Idempotency-/Execution-Key bzw. deduplizierbare Ausführungslogik, damit Retry/Worker-Restart keine unbeabsichtigten Doppelaktionen erzeugt | 1 Tag |
| G-UI-FORM | Form-basierter Step-Editor — Step-Liste mit Up/Down, Formular pro Step-Typ | 2 Tage |
| G-UI-JSON | JSON-Expert-Mode — Toggle zwischen Form und JSON | 0.5 Tage |
| G-UI-VALID | Validation — Required-Field-Check, Step-Reihenfolge | 0.5 Tage |
| G-UI-TEMPL | Template-Gallery — vorgefertigte Workflows | 1 Tag |
| G-TEST | Tests: Step-Execution, Trigger, Retry, Expressions | 2 Tage |
| G-DOC | `docs/api-documentation.md` aktualisieren | 1 Tag |

**Deliverables Phase G:** Bestehende Workflow/Automation-Basis konsolidiert, Workflow Engine mit Form+JSON Editor, 10+ Step-Types, 4 Trigger-Typen, persistenter/resumable WorkflowRun, idempotency-sicheren Side-Effect-Steps, Retry, Execution-Log, zentralem ApprovalRequest + konfigurierbarem Automated-Decision Guard, Workstream-Ausgabe und Template-Gallery.

---

## Phase H — Knowledge

**Dauer:** 6 Wochen
**Ziel:** Die **gesamte relevante Firmenwissensbasis** über denselben Search/RAG/Graph-Kern nutzbar machen: Wiki, DMS, Mail, Communication/Workstreams und ausgewählte fachliche Entitätsinhalte. Kein erneuter Search-/RAG-Aufbau und kein zweiter universeller Knowledge-Datenspeicher.

**Code-Stand:** GraphRAG/Entity-Beziehungen und Search-Grundlagen existieren; echtes Wiki, Document-RAG und automatische Knowledge-Extraktion fehlen noch.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| H-WIKI | Wiki-Plugin — Knowledge-Artikel mit Markdown-Editor, Kategorien, Tags | 2 Tage |
| H-VER | Versionierung — Artikel-Historie, Diff-View, Restore | 1 Tag |
| H-LINK | Auto-Linking — Artikel verlinken auf Entitäten | 1 Tag |
| H-SEARCH | Wiki Search Provider (in Unified Search) | 0.5 Tage |
| H-EMB | Wiki-Embeddings (in RAG-Pipeline) | 0.5 Tage |
| H-SRC | **Knowledge Source Adapter** — DMS, Wiki, Mail, Communication/Workstreams sowie explizit freigegebene fachliche Text-/Notizfelder über bestehende SearchProvider/RAG-Pipeline anbinden. Originalquelle bleibt authoritative; Permissions/Sensitive Fields gelten durchgängig | 2 Tage |
| H-CITE | **Evidence/Source References** — RAG-/Knowledge-Ergebnisse liefern strukturierte Quellenreferenzen/Deep-Links bzw. Cards auf originales Dokument, Mail, Message oder Businessobjekt; Agenten können diese im Workstream anzeigen | 1 Tag |
| H-EXT | LLM-Relationship-Extraktion — analysiert Texte, extrahiert Beziehungen | 2 Tage |
| H-ENT | Entity-Extraction — erkennt Personen, Firmen, Projekte | 1 Tag |
| H-AUTO | Auto-Relationship-Creation in GraphRAG | 1 Tag |
| H-CONF | Confidence-Score, Low-Confidence → Review-Queue | 1 Tag |
| H-EVT | Event-Driven-Extraction (neue Mail/Dokument/Message bzw. relevante fachliche Wissensänderung → ARQ-Job → Extraktion); nur konfigurierte Knowledge-Quellen | 1 Tag |
| H-DATA-LIFE | **Derived-Data Lifecycle für Knowledge** — Correction/Delete/Erasure der authoritative Quelle propagiert über denselben Event-/Worker-Weg zu RAG-Chunks, Embeddings, Graph-Referenzen und angebundenem Agent Memory; source references ermöglichen gezieltes Rebuild/Remove | 2 Tage |
| H-RET | **Knowledge/Memory Retention** — kleine Retention-/Source-Policy je Wissensquelle/Datenklasse; keine zweite Archivierungsengine, ARQ räumt nur nach konfigurierter Policy auf | 1 Tag |
| H-GRAPH | Wissensgraph-Visualisierung (Cytoscape) | 2 Tage |
| H-EDITOR | Wiki-Artikel-Editor (TipTap) | 1 Tag |
| H-BROWSE | Knowledge-Browser — Baumansicht, Artikel-Liste | 1 Tag |
| H-ASK | **Ask Knowledge im zentralen Workstream** — RAG-Queries und Antworten mit Quellen-Cards über Communication/BlockRenderer; keine neue isolierte Chat-Silo-UI | 1 Tag |
| H-REV | Review-Queue für extrahierte Beziehungen | 0.5 Tage |
| H-TEST | Tests: Wiki CRUD, RAG-Query, Extraction, Graph | 2 Tage |
| H-DOC | `docs/api-documentation.md`, `docs/plugin-development-guide.md` | 1 Tag |

**Deliverables Phase H:** Firmenwissensschicht aus Wiki + DMS + Mail + Communication + freigegebenen Businessinhalten, Document-RAG, Quellen/Evidence-Cards, automatische Wissensgraph-Extraktion, konsistenter Correction/Delete/Retention-Lifecycle für RAG/Embeddings/Graph/Memory, Knowledge-UI mit Graph-Visualisierung und Ask-Knowledge im zentralen Workstream.

---

## Phase I — Integration, Human-AI Workstream & Polish

**Dauer:** 6 Wochen
**Ziel:** Alle Systeme verbinden und den bereits vorhandenen Communication-/Sidebar-/MiniApp-Unterbau zum produktiven **Human-AI Workstream** machen: Menschen, Agenten, Workflows, Firmenwissen und interaktive Business-MiniApps arbeiten in einem gemeinsamen Strom — Desktop und mobil.

### I.1 Cross-System-Integration

Alle in Phase E-H gebauten Systeme müssen miteinander verbunden werden.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| I-AW | **Agent → Workflow** — Agenten können Workflows als Tools aufrufen (`start_workflow`, `check_workflow_status`) | 1 Tag |
| I-WA | **Workflow → Agent** — Workflows können Agenten als Steps aufrufen (bereits G-AGENT, verifizieren) | 0.5 Tage |
| I-AS | **Agent → Search** — Agenten nutzen Unified Search als Tool (bereits E-TOOL, verifizieren) | 0.5 Tage |
| I-AK | **Agent → Knowledge** — Agenten nutzen RAG/Graph/Knowledge mit Evidence-Referenzen | 0.5 Tage |
| I-KS | **Knowledge → Search** — Wiki/Knowledge-Quellen in Unified Search (bereits H-SRC/H-SEARCH, verifizieren) | 0.5 Tage |
| I-MCP | **MCP-Exposure für Plattformfeatures** — Search, Agents, Workflows, Knowledge als dünne Exposure-Schicht auf bestehenden Tools/Services. MCP besitzt keine eigenen Rechte; vorhandener Auth-/Run-as-Kontext und normale Permission-Prüfungen gelten immer | 1.5 Tage |
| I-APPR-LOOP | **Agent Loop Human-in-the-Loop Approval** (ARCH-F-1) — `run_react_loop()` um `require_approval` Parameter erweitern: bei Approval-required Tools pausiert der Loop, erstellt `ApprovalRequest` via `post_approval_request()`, wartet auf Decision (approve/reject/expire), resume bei approve, abort bei reject/expire. Approval-Decision triggert Workstream-Notification | 1.5 Tage |

### I.2 Human-AI Workstream & MiniApp Runtime

**Prinzip:** Kein neues Workstream-Datenmodell. `CommConversation`/`CommMessage` sind der zentrale Arbeitsstrom. Die rechte `MessageSidebar` und mobile Communication-UI werden erweitert. MiniApps visualisieren/steuern vorhandene Domain-Services; Businessdaten bleiben authoritative in ihren Fachmodulen.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| I-WORK-BASE | **Workstream Contract festschreiben** — Menschen, System, Agents und Workflows als Teilnehmer/Akteure im vorhandenen Communication-Modell; typed blocks statt separater Agent-/Notification-/Workflow-Chats | 0.5 Tage |
| I-MINI-MANIFEST | **MiniApps bis Frontend durchreichen** — `/plugins/active-manifests` und `PluginUiManifest` um `miniapps`/Render-Metadaten ergänzen; bestehende `manifest.miniapps`-Definition wirklich nutzbar machen | 1 Tag |
| I-MINI-RENDER | **`MiniAppBlock` Placeholder ersetzen** — `app_id` über gemeinsamen Registry/Resolver zu echter interaktiver Darstellung auflösen; Fehler-/Fallback-State sauber behandeln | 2 Tage |
| I-MINI-SDK | **Kleines MiniApp UI/Schema-SDK** — Standardbausteine für Entity Card/Detail, Form, Auswahl, Liste, Action Buttons, Approval, Progress und Deep-Link. `render_schema` validieren; Aktionen gehen über reguläre APIs/Services + Permissions | 2 Tage |
| I-WORK-ACTOR | **Einheitlicher Posting-Pfad** — Human/System/Agent/Workflow können Text, Entity Cards, Action Cards, Knowledge Evidence, Approval und MiniApps über denselben Communication-Service posten | 1 Tag |
| I-WORK-HANDOFF | **Human↔Agent Handoff** — `review_needed`/`action_required`/`waiting_for_user` als typisierte Workstream-Semantik; Aktion oder User-Änderung kann denselben AgentRun/WorkflowRun fortsetzen. **Task-basierter Handoff**: Handoff erstellt automatisch einen `Task` mit `assignee_type` (user/agent/group), `entity_type+entity_id` Referenz und `task_type='handoff'`; Task-Status-Änderung fortsetzt den Run | 2 Tage |
| I-WORK-PROACTIVE | **Proactive Workstream Feed** — UI-/Domain-Trigger erzeugen kontextuelle Vorschläge/Actions im Workstream mit Priority, Dedupe, Cooldown und User-Einstellungen; kein störendes Popup-/Clippy-Verhalten | 1.5 Tage |
| I-WORK-GROUP | **Shared Group Workstreams** — vorhandene Conversation-/Participant-Rechte für mehrere Menschen + Agenten verifizieren; Mentions/Unread/Assignment/Handoffs auf Gruppenfluss testen | 1 Tag |
| I-WORK-MOBILE | **Mobile/PWA Workstream** — bestehendes mobile Sidebar/Overlay + PWA so fertigstellen, dass alle Standard-Blocks/MiniApps touch-tauglich sind; Datei-/Foto-Upload, Actions, Approval, Deep-Links und Agent-Interaktion mobil E2E testen. Keine Offline-ERP-Sync-Architektur | 2 Tage |
| I-WORK-PLUGINUI | **Branchenplugin-UI-Vertrag verifizieren** — volle React-Pluginseiten werden gebündelt/deployed; runtime-fähige Workstream-MiniApps schema-basiert. Keine Annahme, dass Vite nachträglich beliebigen React-Code hot-loaden kann | 1 Tag |
| I-PLUGIN-REF | **Reference Vertical Plugin / Contract Proof** — kleines Test-/Beispielplugin beweist ohne Core-Sondercode: eigene Migration/Domain-Route, Full-Page-UI, MiniApp, Tool, Skill, Agent/Trigger, Workflow/Automation und Search/Knowledge-Contribution. Kein neues Branchenprodukt, sondern Integrationsbeweis | 2 Tage |
| I-WORK-E2E | **Human-AI-Co-Working E2E** — Referenzfluss: Mail öffnen → UI-Trigger → Agent analysiert Mail+Knowledge → Termin/Projekt-MiniApp im Workstream → User prüft/ändert → Domain/UI-Event → Agent/Workflow setzt fort. Zusätzlich Shared-Group- und Mobile-Flow | 2 Tage |

### I.3 Dashboard & Analytics

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| I-DASH | **Platform Dashboard** — Agent-Status, Workflow-Stats, Search-Metrics, Knowledge-Coverage, Workstream-/Suggestion-Metriken, System-Health | 2 Tage |
| I-COST | **Cost-Tracking Dashboard** — LLM-Kosten pro Agent/Workflow/User, Budget-Alerts, Cost-Trends. LLM Client hat Cost-Tracking (B.1) und Tenant-Cost-Cap (B-COST-CAP), hier wird die UI gebaut: Live-Kosten, Budget-Auslastung, Alert-History, Cost-Per-Tenant/Agent/Workflow, Hard-Stop-Events | 2 Tage |
| I-USE | **Usage-/Collaboration-Analytics** — Feature-Nutzung, Search-Queries, Agent-Runs, Workflow-Executions sowie angenommene/verwerfene Proactive Suggestions/Handoffs als Basis für Phase J | 1 Tag |

### I.4 Performance Review & gezielte Optimierung

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| I-PERF | **Performance-Vergleich zuerst** — gegen Phase-A-Baseline messen, Bottlenecks und Regressionen identifizieren | 1 Tag |
| I-BATCH | **Batch-Embedding** — grundsätzlich vorsehen und anhand Durchsatz/Kosten sinnvoll konfigurieren | 0.5 Tage |
| I-CACHE | **Search-Caching (conditional)** — nur aktivieren/ausbauen, wenn Messwerte Nutzen zeigen; Tenant-/User-/Permission-Kontext und Cache-Invalidierung korrekt berücksichtigen | 1 Tag |
| I-QUEUE | **ARQ-Queue-Tuning (conditional)** — Prioritäten, Concurrency-Limits, DLQ nur anhand realer Last/Bottlenecks konfigurieren | 1 Tag |
| I-IDX | **DB-/FTS-/pgvector-/HNSW-Tuning (conditional)** — Indizes/Parameter anhand Messwerten optimieren; Write-Performance und Ressourcenverbrauch gegenprüfen | 1 Tag |

### I.5 DSGVO-Betroffenenrechte & Compliance Export

Wenn Core, Communication, Agents, Workflows und Knowledge vollständig integriert sind, wird der plattformweite Betroffenenrechts-/Nachweisweg fertiggestellt. Keine universelle Privacy-Engine und kein blindes automatisches Löschen über fachliche/gesetzliche Aufbewahrungspflichten hinweg.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| I-DSGVO | **Vollständiger Plattform-Datenauskunfts-Export** — personenbezogene Daten eines Users/Betroffenen über Core und aktive Plugins hinweg (u. a. CRM, Mail, Calendar, DMS, Communication/Workstreams, Agents, Workflows, Knowledge, Audit) als strukturierter JSON/ZIP-Export. Sensitive-/Exposure-Regeln zwingend beachten | 2 Tage |
| I-DSAR | **Betroffenenrechts-Workflow** — Access/Correction/Erasure/Restriction als nachvollziehbarer administrativer Vorgang: betroffene Quellen finden, fachliche Handler aufrufen, abgeleitete Daten über E/H-Lifecycle nachziehen, Ausnahmen/Retention dokumentieren. Kein generischer Blind-Hard-Delete | 2 Tage |
| I-COMP-EXPORT | **AI/Compliance Evidence Export** — AI-Use-Case-Metadaten, Provider-/Modellbezug, Agent-/Workflow-Versionen, relevante Audit-/Oversight-/Approval-Evidenz und technische Policies als exportierbares Nachweispaket | 1 Tag |

### I.6 Onboarding & Dokumentation

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| I-ONB | **Feature-Onboarding** — Setup-Wizard für Agenten, Workflows, Knowledge, Workstreams/MiniApps und Proactive Collaboration | 1 Tag |
| I-DOC | **Platform-Dokumentation** — Architektur-Doku, Plugin-Dev-Guide final, Agent-Dev-Guide, Workstream/MiniApp-Guide, User-Guide | 2 Tage |
| I-VID | **Feature-Videos** — kurze Screencasts für Agent-Builder, Workflow-Editor, Knowledge und Human-AI Workstream | 1 Tag |

### I.7 Final Polish

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| I-UI | **UI-Polish** — alle neuen Features visuell vereinheitlichen, Loading-/Error-/Empty-/Agent-working-/Review-needed-States konsistent | 2 Tage |
| I-TEST | **Vollständige Test-Pipeline** — alle 8 Checks über das gesamte System, E2E für alle kritischen Flows inklusive Workstream/MiniApps/Mobile | 2 Tage |
| I-DEPLOY | **Production-Deploy** — Deploy, Health-Check, Smoke-Test, Monitoring verifizieren | 1 Tag |

**Deliverables Phase I:** Alle Systeme verbunden (Agent↔Workflow↔Search↔Knowledge↔Communication), produktiver Human-AI Workstream auf dem zentralen Message-System, echte plugin-erweiterbare MiniApps, Proactive Collaboration, Shared Group Workstreams, mobile/PWA-Workstreams, MCP, Dashboard/Analytics, DSGVO-Betroffenenrechtsweg + Compliance Evidence Export, Onboarding und Production-Deploy.

---

## Phase J — Controlled Self-Improvement

**Dauer:** 5 Wochen
**Ziel:** Leo kann aus realer Arbeit Verbesserungspotenziale erkennen und **kontrolliert** bessere Agenten-/Skill-/Trigger-/Workflow-/MiniApp-Konfigurationen vorschlagen. Keine heimliche Selbstmodifikation und keine ungeprüften Production-Code-Änderungen.

### Grundregel

Self-Improvement ist ein **Versionierungs-, Evaluations- und Approval-Loop**, kein autonomer Production-Code-Editor:

```text
Beobachten → Muster/Effekt erkennen → ImprovementProposal
→ versionierten Draft erzeugen → Dry-Run/Simulation/Tests
→ Human Approval → kontrolliert aktivieren
→ Wirkung messen → behalten oder rollback
```

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| J-SIGNAL | **Improvement Signals** — vorhandene `ContextLog`, accepted/dismissed Proactive Suggestions, AgentRuns, WorkflowRuns, AuditLog, EntityHistory, User-Korrekturen/Handoffs und Outcome-Metriken als referenzierte Signale nutzbar machen. Datenminimierung/Exposure-Policy/Retention gelten auch hier; möglichst Referenzen/Aggregate statt unnötiger personenbezogener Vollkopien | 2 Tage |
| J-PATTERN | **Pattern/Bottleneck Detection** — wiederkehrende manuelle Sequenzen, häufige Korrekturen, abgelehnte Vorschläge, Retries/Fehler und repetitive Handoffs erkennen; Confidence/Evidence speichern | 2 Tage |
| J-PROP | **`ImprovementProposal`** — Vorschlag mit Zieltyp (`agent`, `skill`, `trigger`, `workflow`, `miniapp_template`, optional `plugin_patch`), Evidence-Refs, Begründung, erwarteter Nutzen, Risiko und Status | 1.5 Tage |
| J-DRAFT | **Versionierter Draft** — vorhandene Agent-/Automation-/Workflow-Versionierung wiederverwenden und bei Bedarf kleine Skill/MiniApp-Template-Versionierung ergänzen. Keine universelle Versionierungsengine | 2 Tage |
| J-EVAL | **Evaluation/Sandbox** — Vorschläge gegen sichere historische/synthetische Fälle per Replay, Dry-Run und Tests bewerten; keine externen Side Effects | 3 Tage |
| J-APPROVAL | **Human Approval** — Aktivierung immer über zentralen ApprovalRequest/Workstream; Verantwortlicher sieht Evidence, Diff, Tests und erwartete Auswirkung | 1 Tag |
| J-ACTIVATE | **Controlled Activate + Rollback** — atomar die freigegebene Version aktivieren; vorherige Version bleibt rollback-fähig | 1 Tag |
| J-MEASURE | **Pre/Post Impact Measurement** — Zeit, Fehler, Annahmequote, Kosten, Durchsatz und fachliche Outcome-Metriken soweit verfügbar vergleichen; Ergebnis fließt in spätere Proposal-Qualität ein | 2 Tage |
| J-UI | **Improvement Center im Workstream/Settings** — Proposal Cards/MiniApps für Review, Evidence, Simulationsergebnis, Approve/Reject/Rollback | 2 Tage |
| J-CODE | **Code-/Plugin-Verbesserungen nur über normalen Engineering-Weg** — falls Leo einen Plugin-/MiniApp-Codepatch vorschlägt: Patch/Branch → Tests/CI → menschliches Review → normaler Release. Niemals autonomer direkter Production-Code-Write | 1 Tag |
| J-TEST | Tests: Signal-Isolation/Tenant, Proposal-Evidence, Sandbox ohne Side Effects, Approval, Rollback, Measurement | 2 Tage |
| J-DOC | Self-Improvement-Sicherheits-/Betriebsregeln und Plugin-Guide ergänzen | 1 Tag |

**Deliverables Phase J:** kontrollierter Lern-/Verbesserungskreislauf auf realen Nutzungs- und Outcome-Signalen, versionierte Improvement Proposals, Evaluation/Dry-Run, Human Approval, Rollback und Wirkungsmessung — ohne autonome ungeprüfte Production-Selbstmodifikation.

---

## Phase K — EU Compliance Finalization

**Dauer:** 1 Woche
**Ziel:** Die während B–J bereits technisch eingebauten Privacy-/AI-Compliance-Funktionen zu einem prüfbaren Betreiber-/Produktnachweis zusammenführen. Kein neuer Runtime-Kern, keine juristische Auto-Entscheidungsengine.

| Task | Beschreibung | Aufwand |
|------|-------------|---------|
| K-REG | **AI System / Use-Case Register UI** — vorhandene F-AIUSE-Metadaten übersichtlich verwalten: Intended Purpose, Owner, Agent/Workflow/Plugin, Provider/Model, Datenklassen, Oversight, Risk-Class, Status/Version | 1 Tag |
| K-DPIA | **DPIA / AI Impact / FRIA Support** — aus vorhandenen Metadaten und Evidence vorbefüllbare Templates/Exports für Datenschutz-Folgenabschätzung bzw. AI-/Grundrechts-Risikoprüfung, **wo der konkrete Einsatz dies verlangt**. Keine automatische Rechtsbewertung | 1 Tag |
| K-INC | **AI/Privacy Incident Register** — Incident erfassen, betroffene Use-Cases/Versionen/Provider/Runs referenzieren, Maßnahmen und Evidence dokumentieren; Reporting-Fristen/-pflichten bleiben organisatorisch/use-case-spezifisch | 0.5 Tage |
| K-RET | **Retention-/Erasure Admin UI** — vorhandene Daten-/Knowledge-/Memory-Retention-Policies administrierbar und nachvollziehbar machen; Legal Hold/Ausnahme nur als explizite Policy, keine neue Storage-Engine | 0.5 Tage |
| K-COMP-TEST | **Compliance E2E/Contract Tests** — AI-Kennzeichnung, Data-Exposure/Provider-Blocking, Search/RAG/Graph/Memory-Cleanup, Betroffenenrechtsweg, Oversight/Approval-Record, Tenant-Isolation und Evidence Export durchtesten | 1.5 Tage |
| K-DOC | **EU Compliance Betriebsdoku** — Rollen/Verantwortlichkeiten, Provider-Onboarding, Use-Case-Klassifikation, DPIA/AI-Impact-Checkliste, Incident-/DSAR-Ablauf, Plugin-Anforderungen und klare Grenze „Plattformfunktion ≠ automatische Rechtskonformität“ | 0.5 Tage |

**Deliverables Phase K:** prüfbares AI-/Privacy-Use-Case-Register, vorbefüllbare Compliance-Templates, Incident-/Retention-Administration, E2E-Nachweis der technischen Datenschutz-/Oversight-Kontrollen und vollständige EU-Compliance-Betriebsdokumentation.

---

## Zielarchitektur im Endstand

```text
Vertical / Branchen-Plugin
├── Domain Models + Services + Routes
├── Fach-UI / gebündelte React-Seiten
├── MiniApps für Workstreams/Mobile
├── Tools + Skills
├── Agent Definitions / Trigger
├── Workflows / Automation Templates
└── Search-/Knowledge-Contributions
                 │
                 ▼
┌──────────────────────────────────────────────────────────┐
│ LeoPlatform                                              │
├──────────────────────────────────────────────────────────┤
│ Human-AI Workstream                                      │
│ Communication · Groups · Rich Blocks · MiniApps · Mobile │
├──────────────────────────────────────────────────────────┤
│ Agents · Skills · Tools · Memory · Proactive/UI Context  │
├──────────────────────────────────────────────────────────┤
│ Workflows · Automation · Trigger · Approval · ARQ        │
├──────────────────────────────────────────────────────────┤
│ Unified Search · RAG · Graph · Firmenwissen              │
├──────────────────────────────────────────────────────────┤
│ Business Services · Permissions · Tenant · Audit · Files │
├──────────────────────────────────────────────────────────┤
│ Plugin Runtime / Manifest / Registries                   │
├──────────────────────────────────────────────────────────┤
│ Controlled Self-Improvement                              │
├──────────────────────────────────────────────────────────┤
│ Privacy / DSGVO / AI Compliance by Design                │
└──────────────────────────────────────────────────────────┘
```

**Architekturgrenze:** Plugins erweitern die Plattform fachlich. Workstream/MiniApps sind die gemeinsame Interaktionsschicht; sie ersetzen keine Domain-Services. Agenten/Skills/Workflows/MCP greifen immer über normale Services/Tools und deren aktuellen Auth-/Run-as-/Permission-Kontext zu. Privacy-/AI-Compliance nutzt dieselben vorhandenen Daten-, Provider-, Audit-, Approval- und Lifecycle-Grenzen; sie bildet **keine zweite Policy-/Runtime-Architektur**.

---

## Später — Advanced Autonomy/Automation nur bei echtem Bedarf

### Advanced Agent Runtime / Advanced Autonomy

Die Agent-Runtime soll später ohne Grundumbau auf höhere Autonomie ausgebaut werden können. Die heutige Basis aus Tools, Skills, Search/RAG/Graph, Memory, Triggern, Workflows, Permissions/Run-as, Approval, Audit und AgentRun bleibt dabei authoritative und wird erweitert, nicht ersetzt.

Geplante Erweiterungsfähigkeiten:

- **Goal-based Agents** — Agent erhält ein Ziel statt nur eines einzelnen Befehls; Zielzustand und Success Criteria werden explizit gespeichert
- **Task-based Execution** — Ziele können in Tasks/Subtasks zerlegt, priorisiert und nacheinander oder parallel abgearbeitet werden
- **Persistent Agent Jobs** — länger laufende Jobs mit Status wie `pending`, `running`, `waiting`, `blocked`, `approval_required`, `completed`, statt eines einzigen langen LLM-Calls
- **Loop bis Ziel erreicht** — planen → ausführen → Ergebnis prüfen → ggf. neu planen; Ende bei `done`, `blocked`, Approval, Budget-/Step-Limit oder Abbruch
- **Subagents / Delegation** — Parent-/Supervisor-Agent kann spezialisierte Child-Agenten für Teilaufgaben starten und deren Ergebnisse übernehmen
- **Agent-Hierarchien** — Supervisor → spezialisierte Agenten → optionale weitere Subagents; keine starre Organigramm-Architektur nötig
- **Agent-to-Agent Trigger/Delegation** — Agenten können andere Agenten direkt delegieren oder über relevante Events wie `agent.run_completed` / `agent.task_completed` anstoßen
- **Advisor Agents** — Berater-Agenten analysieren Search/RAG/Graph/Analytics und Systemdaten, erkennen Handlungsbedarf und veröffentlichen Evidence-basierte Empfehlungen/Handoffs im passenden gemeinsamen Workstream bzw. starten nach Policy einen Job
- **Job Agents** — Agenten können komplette fachliche Jobs übernehmen, auf externe Ereignisse/Approvals warten, später fortsetzen und mehrere Skills/Tools/Workflows koordinieren; `AgentJob` kann einem Workstream zugeordnet sein und dort sichtbare Handoffs/Status liefern
- **Evaluation & Replanning** — Ergebnisse gegen Success Criteria prüfen, Fehlschläge bewerten und gezielt neu planen

Vorgesehene Erweiterung der Runtime:

```text
AgentJob
├── goal
├── workstream_id (optional)
├── status
├── owner / run_as
├── parent_job_id / parent_agent_run_id
├── budget / limits
├── success_criteria
└── Tasks
    ├── pending
    ├── running
    ├── waiting
    ├── blocked
    └── completed
```

Berechtigungsregel bei Delegation:

```text
Effektive Child-Agent-Fähigkeiten
= Run-as/User-Permissions
∩ vom Parent delegierte Fähigkeiten
∩ Child-Agent-Freigaben
∩ Skill-Freigaben
∩ Tool-Freigaben
```

Ein Parent-/Supervisor-Agent darf einem Child-Agent keine Rechte verleihen, die im aktuellen Run-as-Kontext nicht vorhanden sind. Delegations-Tiefe, Budgets, Max-Runs und Loop-Limits verhindern unkontrollierte Agent-zu-Agent-Schleifen.

**Wichtig:** Diese Fähigkeiten werden jetzt noch nicht vorgebaut. Die aktuelle Agent-MVP-Architektur muss sie nur offenlassen. Später wird die bestehende Runtime um `AgentJob`, Task-Decomposition, Delegation/Subagents, Supervisor-Logik und Evaluation/Replanning erweitert — keine zweite Agent-Plattform. Auch Advanced AgentJobs/Subagents erben dieselbe AI-Use-Case-, Provider/Data-Policy-, Transparency-, Oversight- und Audit-Semantik; keine Sonder-Compliance-Engine für Advanced Agents.

### Advanced Automation Runtime

Die Workflow-/Automation-Runtime soll später ohne Grundumbau zu einer vollständigen langlebigen Business-Automation-Plattform ausgebaut werden können. Die heutige Basis aus gemeinsamem Trigger-Kern, persistentem `WorkflowRun`/ExecutionContext, resumable Wait, idempotency-sicheren Steps, Approval, ARQ, Outbox, Tools/Services und Agent-Integration bleibt authoritative und wird erweitert, nicht ersetzt.

Geplante Erweiterungsfähigkeiten:

- **Long-running Workflows** — Prozesse können Stunden, Tage oder Wochen laufen, ohne Worker dauerhaft zu blockieren
- **Wait for Event / Event Correlation** — Workflow wartet nicht nur auf Zeit, sondern auf ein fachlich passendes Ereignis (z. B. Antwort auf eine bestimmte Mail, Statusänderung eines bestimmten Auftrags) und setzt danach denselben Run fort
- **Branching / Switch** — mehrere fachliche Entscheidungspfade auf Basis von Daten, Expressions oder Agent-Ergebnissen
- **Loops / For-Each** — Listen/Entities kontrolliert iterieren, mit Limits und sauberem Fehlerverhalten
- **Parallel Branches / Join** — unabhängige Zweige parallel ausführen und anschließend auf definierte Ergebnisse warten
- **Subworkflows** — Workflow kann einen anderen Workflow als wiederverwendbaren Baustein starten und auf dessen Ergebnis warten
- **Reusable Workflows** — versionierte, parametrisierte Business-Abläufe als wiederverwendbare Module
- **Plugin-defined Steps & Trigger** — Plugins können über den bestehenden Registry-/Plugin-Mechanismus neue fachliche Steps und Trigger beitragen; keine zweite Workflow-Engine
- **Error Routes / Compensation** — definierte Fehlerpfade und gezielte fachliche Gegenaktionen dort, wo echte Rückabwicklung möglich/sinnvoll ist; kein universelles DB-Rollback über beliebige Systeme
- **Erweiterte Workflow-Versionierung** — laufende Runs bleiben an ihrer gestarteten Definition/Version gebunden; neue Runs verwenden die aktuelle Version
- **Agent ↔ Workflow Orchestration** — Workflows können Agenten einsetzen; Agenten können Workflows als deterministische Business-Prozesse starten und deren Status/Ergebnis verwenden
- **Workstream Correlation/Handoff** — Workstream-Aktionen/User-Reaktionen können wartende WorkflowRuns korreliert fortsetzen; Workflow-Ergebnisse/Handoffs erscheinen als typisierte Communication-Blocks, nicht in einem separaten Workflow-Chat

Zielbild:

```text
Trigger / Event / Cron / Webhook / Agent
                │
                ▼
          WorkflowRun
                │
      ┌─────────┼─────────┐
      │         │         │
  Condition   Agent     Action
      │         │         │
      └─────┬───┴─────────┘
            │
      Wait / Approval / Event
            │
      Run persistent pausiert
            │
      Resume über Trigger
            │
      weitere Steps / Subworkflow
            │
         completed
```

**Wichtig:** Diese erweiterten Fähigkeiten werden jetzt noch nicht vollständig vorgebaut. Phase G legt nur die dafür nötigen Runtime-Invarianten fest: persistenter/resumable `WorkflowRun`, persistenter ExecutionContext und idempotency-/retry-sichere Side-Effect-Ausführung. Später wird dieselbe Workflow-Engine erweitert — keine zweite Automatisierungsplattform.

### Weitere spätere Funktionen

- **Multi-Platform Messaging Gateway** — Plugin-basierte Anbindung an Telegram, Discord, Slack, WhatsApp etc. Eingehend: eigene Webhook-Route → CommMessage mit `participant_type='{platform}_gateway'`. Ausgehend: `comm.after_message` Hook → externe API. Keine Core-Änderung nötig. Rich Content Blocks werden als Text-Fallback + Action-Buttons gemappt
- **Matrix Chat Server Integration** — Synapse (Matrix Server) als eigener Docker-Container im Stack. LeoCRM Matrix-Bridge-Plugin verbindet sich als Matrix Application Service. Sync: CommConversation ↔ Matrix Room. Vorteile: native Mobile/Desktop-Clients (Element), Federation (externe Partner), E2EE, Multi-Platform Bridges (Telegram/Discord/Slack via Matrix Bridges), Push Notifications, Offline-Support. CommMessage bleibt authoritative, Matrix ist Gateway/Mirror. Keine Core-Änderung nötig
- Public Plugin Web Surface (Subdomains, Form Builder, Booking)
- React Flow Workflow Canvas (visueller Editor)
- Theme Editor mit Presets, Font Selector, Compact/Large
- Generic PST Import
- Allgemeines Plugin-Web-Hosting
- Universelle Export-Frameworks
- Code-Node / Raw-SQL-Node in Workflows
- Weitere Spezial-Abstraktionen

---

## Phase O — UI-Overhaul (Status: geplant, 2026-08-30 verifiziert)

> **Umbenannt von 'Phase L' (2026-08-30):** Der Buchstabe L war doppelt vergeben (UI-Overhaul + Dokumente-Generator). UI-Overhaul ist jetzt Phase O; Phase L = Dokumente-Generator (abgeschlossen).
> **Bug-Verifikation Phase 1 (2026-08-30, Live-Messung):** 1.1 Kontakte-Invalidation ✓ gefixt (invalidateQueries vorhanden) · 1.2 Drag-Drop Kontakte→Ordner ✗ offen · 1.3 MoveDialog ✗ offen (existiert nicht) · 1.4 Wiki-Save ✓ verdrahtet (apiPost/apiPatch live) · 1.5 Kalender-Dialog ✓ gefixt (onSaved-Handler) · 1.6 Neuer Chat ✓ gefixt (createConversation + Button) · 1.7 Wiki doppelt ✓ kein Bug (1 Menü-Eintrag + 1 page_route, konsistent). Status 'NICHT gestartet' war falsch — 5/7 Bugs bereits erledigt.

> **Herkunft:** Am 2026-08-25 aus der eigenständigen Datei `UI_OVERHAUL_PLAN.md`
> hier integriert - gemaess AGENTS.md-Regel "PLATFORM_ROADMAP.md ist EINZIGE
> Planungs-Datei". Vollständiges Original inkl. ASCII-Mockups abrufbar via
> `git show c807aac:UI_OVERHAUL_PLAN.md`.
>
> **Konflikt-Notiz (2026-08-25, Block I-D) — ENTSCHIEDEN (2026-08-30):** Option (b)
> gilt — die AI-Assistant-Seite bleibt (962e0ee, repariert die Geister-Route
> /ai-assistant). Phase 2 ("AI Assistant Page entfernen") ist UEBERHOLT und
> wird nicht umgesetzt. Original-Notiz: git show f6516e4:PLATFORM_ROADMAP.md.

> **Erstellt:** 2026-08-21
> **Aktualisiert:** 2026-08-21 — AI Assistent Integration hinzugefügt
> **Status:** Planung — nicht gestartet
> **Leitlinie:** Auf bestehendem Code aufbauen, 3-Spalten-Explorer-Layout als Standard, keine parallelen Systeme

---

### Standard-Layout (Referenz: ContactsList.tsx)

Alle Explorer-Plugins nutzen das 3-Spalten-Layout aus den UI-Design-Guidelines:

```
┌─────────────┬──────────────────┬──────────────────────┐
│   Tree      │   Liste/Ansicht   │   Detail             │
│  (224px)    │   (flex-1)        │   (flex-1 / 60%)     │
│ ResizablePanel│  ResizablePanel   │   ResizablePanel     │
└─────────────┴──────────────────┴──────────────────────┘
```

- **Toolbar oben:** PluginToolbar mit Filter-Dropdowns, Ansichts-Umschaltern, Aktion-Buttons
- **Linke Spalte:** ResizablePanel mit Baumansicht (Ordner, Kategorien, Kalender)
- **Mitte:** Liste, Karten, Kalender-Ansicht — mehrere Ansichten umschaltbar
- **Rechts:** Detail-Bereich für ausgewähltes Element

---

### Phase 1: Echte Bugs fixen (2-3 Tage)

#### 1.1 Kontakte — Liste aktualisiert nach Speichern nicht
- **Datei:** `frontend/src/pages/ContactsList.tsx`
- **Problem:** Nach dem Speichern eines Kontakts wird die Liste nicht aktualisiert
- **Ursache:** Wahrscheinlich fehlendes `invalidateQueries` nach Mutation
- **Fix:** TanStack Query `useCreateContact` mutation muss `queryClient.invalidateQueries({ queryKey: ['contacts'] })` im `onSuccess` haben
- **Aufwand:** 1 Stunde

#### 1.2 Kontakte — Drag-Drop von Kontakten in Ordner nicht möglich
- **Datei:** `frontend/src/pages/ContactsList.tsx`, `frontend/src/components/contacts/`
- **Problem:** Drag-Drop von Kontakten in Ordner funktioniert nicht
- **Fix:** HTML5 Drag-Drop API auf Tree-Nodes implementieren, `onDrop` handler der `updateContact({ folder_id })` aufruft
- **Aufwand:** 3 Stunden

#### 1.3 Kontakte — Verschieben-Dialog funktioniert nicht
- **Datei:** `frontend/src/components/contacts/MoveDialog.tsx` (oder ähnlich)
- **Problem:** Ordner-Auswahl im Verschieben-Dialog leer oder broken
- **Fix:** Ordner-API aufrufen und im Dialog anzeigen, Auswahl speichern
- **Aufwand:** 2 Stunden

#### 1.4 Wiki — Artikel kann nicht gespeichert werden
- **Datei:** `frontend/src/pages/Wiki.tsx`, `frontend/src/api/knowledge.ts`
- **Problem:** Speichern-Button funktioniert nicht oder API gibt Fehler zurück
- **Diagnose:** API-Endpunkt prüfen (`POST /api/v1/wiki/articles` oder `PATCH /api/v1/wiki/articles/:id`), Frontend-Mutation prüfen
- **Fix:** Je nach Diagnose — API-Fehler oder Frontend-Mutation-Fehler
- **Aufwand:** 2 Stunden

#### 1.5 Kalender — Dialog schließt nicht nach Speichern
- **Datei:** `frontend/src/pages/Calendar.tsx`, `frontend/src/components/calendar/AppointmentEditForm.tsx`
- **Problem:** Nach dem Speichern eines Termins schließt sich der Dialog nicht
- **Fix:** `onSuccess` handler muss `setEditingEvent(null)` oder `setShowDialog(false)` aufrufen
- **Aufwand:** 30 Minuten

#### 1.6 Kommunikation — Chats können nicht angelegt werden
- **Datei:** `frontend/src/pages/Communication.tsx`
- **Problem:** "Neuer Chat" Button funktioniert nicht oder API gibt Fehler
- **Diagnose:** API-Endpunkt prüfen (`POST /api/v1/comm/conversations`), Frontend-Mutation prüfen
- **Fix:** Je nach Diagnose
- **Aufwand:** 2 Stunden

#### 1.7 Wiki — Doppelt im Menü
- **Datei:** `frontend/src/routes/index.tsx`, `frontend/src/components/layout/` (Navigation)
- **Problem:** Wiki erscheint zweimal im Menü
- **Diagnose:** Route `/wiki` und möglicherweise Help-Subroute oder Plugin-Route
- **Fix:** Doppelte Route entfernen
- **Aufwand:** 30 Minuten

**Gesamtaufwand Phase 1:** ~13 Stunden (2-3 Tage)

---

### Phase 2: AI Assistent in Kommunikation integrieren (2-3 Tage)

#### Problem
Der AI Assistent ist ein paralleles System das die Kommunikation-Plattform dupliziert:
- **AI Assistant Tabellen:** `ai_conversations`, `ai_messages` (app/models/ai_conversation.py) + `ai_chat_sessions`, `ai_chat_messages`, `ai_chat_attachments` (app/plugins/builtins/ai_assistant/models.py) — 5 Tabellen
- **AI Assistant Frontend:** `AIAssistant.tsx`, `AIAssistantStandalone.tsx`, `SessionList.tsx`, `ChatWindow.tsx` — eigene UI
- **AI Assistant API:** `/api/v1/ai/sessions`, `/api/v1/ai/sessions/:id/messages`, `/api/v1/ai/sessions/:id/stream` — eigene API
- **Kommunikation hat schon AI-Chat:** `comm_conversations` mit `conversation_type='ai'`, `streamChat()` aus `@/api/ai`, `categorizeConversation()` mit 'KI Chats' Kategorie, `new-ai-chat` Toolbar-Button

#### 2.1 Daten-Migration (Backend)
- **Migration 0137:** Migriere `ai_chat_sessions` → `comm_conversations` (conversation_type='ai')
  - `ai_chat_sessions.id` → `comm_conversations.id`
  - `ai_chat_sessions.title` → `comm_conversations.title`
  - `ai_chat_sessions.tenant_id` → `comm_conversations.tenant_id`
  - `ai_chat_sessions.user_id` → `comm_conversations.owner_id`
  - `ai_chat_sessions.agent_id` → `comm_conversations.metadata.agent_id`
  - `ai_chat_sessions.created_at` → `comm_conversations.created_at`
- **Migration 0137:** Migriere `ai_chat_messages` → `comm_messages`
  - `ai_chat_messages.id` → `comm_messages.id`
  - `ai_chat_messages.session_id` → `comm_messages.conversation_id`
  - `ai_chat_messages.role` → `comm_messages.sender_type` ('user' → 'user', 'assistant' → 'ai')
  - `ai_chat_messages.content` → `comm_messages.content`
  - `ai_chat_messages.tenant_id` → `comm_messages.tenant_id`
- **Migration 0137:** Migriere `ai_conversations` → `comm_conversations` (falls Daten vorhanden)
- **Migration 0137:** Migriere `ai_messages` → `comm_messages` (falls Daten vorhanden)
- **Migration 0137:** Drop `ai_conversations`, `ai_messages`, `ai_chat_sessions`, `ai_chat_messages`, `ai_chat_attachments` Tabellen
- **Aufwand:** 1 Tag

#### 2.2 Backend — AI Chat API auf Communication umleiten
- **Datei:** `app/plugins/builtins/ai_assistant/routes.py`
- **Änderung:** `POST /api/v1/ai/sessions` → erstellt `comm_conversations` mit `conversation_type='ai'` statt `ai_chat_sessions`
- **Änderung:** `GET /api/v1/ai/sessions/:id/messages` → liest aus `comm_messages` statt `ai_chat_messages`
- **Änderung:** `POST /api/v1/ai/sessions/:id/stream` → bleibt erhalten (streaming endpoint) aber speichert messages in `comm_messages`
- **Aufwand:** 4 Stunden

#### 2.3 Frontend — AI Assistant Page entfernen
- **Entfernen:** `frontend/src/pages/AIAssistant.tsx`
- **Entfernen:** `frontend/src/pages/AIAssistantStandalone.tsx`
- **Entfernen:** `frontend/src/components/ai/SessionList.tsx`
- **Entfernen:** `frontend/src/components/ai/ChatWindow.tsx`
- **Route anpassen:** `/ai-assistant` → **gelöscht** (kein Redirect nötig)
- **Route anpassen:** `/ai-assistant-standalone` → **gelöscht** (kein Redirect nötig)
- **Navigation:** AI Assistent Menüpunkt entfernen, AI Chat bleibt unter Kommunikation
- **Aufwand:** 2 Stunden

#### 2.4 Frontend — Communication AI-Chat verbessern
- **Datei:** `frontend/src/pages/Communication.tsx`
- **Änderung:** AI Chat Sessions aus `comm_conversations` laden (statt `ai/sessions` API)
- **Änderung:** `streamChat()` bleibt erhalten aber Session-ID ist jetzt `comm_conversation_id`
- **Änderung:** AI Chat Messages aus `comm_messages` laden
- **Aufwand:** 4 Stunden

#### 2.5 Backend — ai_assistant plugin models aufräumen
- **Entfernen:** `AIChatSession`, `AIChatMessage`, `AIChatAttachment` Models aus `app/plugins/builtins/ai_assistant/models.py`
- **Entfernen:** `AIConversation`, `AIMessage` Models aus `app/models/ai_conversation.py`
- **Behalten:** `AIProvider`, `AIModel`, `AIPreset`, `AIChatFolder` Models (für Settings)
- **Behalten:** `ai_assistant` plugin routes für Settings (providers, models, presets)
- **Aufwand:** 2 Stunden

#### 2.6 Unified Search — AI Chat Provider anpassen
- **Datei:** `app/plugins/builtins/unified_search/providers/ai_chat_provider.py`
- **Änderung:** Search auf `comm_messages` (conversation_type='ai') statt `ai_chat_messages`
- **Aufwand:** 1 Stunde

**Gesamtaufwand Phase 2:** ~2-3 Tage

---

### Phase 3: Wiki UI-Überarbeitung (3-4 Tage)

#### 3.1 WYSIWYG Editor
- **Datei:** `frontend/src/components/wiki/WikiEditor.tsx` (neu zu bauen)
- **Anforderung:** WYSIWYG Editor mit allen Möglichkeiten, wie Notion — Bedienelemente über dem Textblock
- **Technologie:** Tiptap (ProseMirror-basiert, React-integration, Notion-ähnliche UX)
  - `@tiptap/react`, `@tiptap/starter-kit`, `@tiptap/extension-*`
  - Floating Toolbar über dem Textblock (wie Notion)
  - Markdown-Export für Backend-Speicherung
- **Aufwand:** 2 Tage

#### 3.2 Wiki Layout — 3-Spalten
- **Datei:** `frontend/src/pages/Wiki.tsx` (umbauen)
- **Anforderung:** Toolbar oben, links Baummenü (Kategorien), Mitte Textbereich
- **Aufbau:**
  - **Toolbar:** View/Edit Mode Toggle (oben rechts), Suche, Neuer Artikel
  - **Links:** WikiBrowser (existiert schon) — Baumansicht mit Kategorien
  - **Mitte:** WYSIWYG Editor (Edit Mode) oder gerenderte Ansicht (View Mode)
  - **Kein separater Detail-Bereich** — Artikel wird in der Mitte angezeigt
- **Aufwand:** 1 Tag

#### 3.3 View/Edit Mode Toggle
- **Datei:** `frontend/src/pages/Wiki.tsx`
- **Anforderung:** Button oben rechts in der Toolbar der zwischen View und Edit Mode wechselt
- **Im Edit Mode:** WYSIWYG Editor mit Floating Toolbar
- **Im View Mode:** Gerenderte Markdown-Ansicht (wie jetzt, aber schöner)
- **Aufwand:** 2 Stunden

**Gesamtaufwand Phase 3:** ~3-4 Tage

---

### Phase 4: Tasks UI-Überarbeitung (2-3 Tage)

#### 4.1 Tasks Layout — 3-Spalten wie Kontakte
- **Datei:** `frontend/src/pages/Tasks.tsx` (kompletter Umbau, 419 → ~600 Zeilen)
- **Anforderung:** Linke Sidebar Baumansicht, Mitte Liste mit mehreren Ansichten, rechts Detailbereich
- **Aufbau:**
  - **Toolbar:** PluginToolbar mit Filter-Dropdowns (Status, Priorität, Zuweisung, Fällig), Ansichts-Umschalter (Liste/Kanban), Neuer Task
  - **Links:** Baumansicht — nach Status (Offen/In Bearbeitung/Erledigt), nach Priorität, nach Zuweisung, nach Liste/Goal
  - **Mitte:** Liste (Tabelle) oder Kanban-Board — umschaltbar
  - **Rechts:** TaskDetail — ausgewählter Task mit Beschreibung, Subtasks, Zuweisung, Fälligkeit
- **Aufwand:** 2-3 Tage

**Gesamtaufwand Phase 4:** ~2-3 Tage

---

### Phase 5: Kalender UI-Überarbeitung (1 Tag)

#### 5.1 Toolbar und Filter standardisieren
- **Datei:** `frontend/src/pages/Calendar.tsx` (anpassen, 759 Zeilen)
- **Problem:** Drucken-Button und Filter-Leiste über dem Kalender entsprechen nicht dem Standard
- **Fix:**
  - Filter in PluginToolbar als Dropdowns (wie Kontakte)
  - Drucken-Button in PluginToolbar
  - Ansichts-Umschalter (Tag/Woche/Monat/Range) in PluginToolbar
- **Aufwand:** 4 Stunden

#### 5.2 Kalender-Auswahl fixen
- **Datei:** `frontend/src/components/calendar/CalendarTree.tsx`
- **Problem:** Einzelnes An- und Abwählen von Kalendern funktioniert nicht richtig
- **Fix:** Checkbox-Toggle Logik reparieren — `visibleCalendars` Set korrekt verwalten
- **Aufwand:** 2 Stunden

**Gesamtaufwand Phase 5:** ~1 Tag

---

### Phase 6: Tags Umstrukturierung (2 Tage)

#### 6.1 Tags in Settings verschieben
- **Datei:** `frontend/src/pages/Tags.tsx` → `frontend/src/pages/SettingsTags.tsx` (neu)
- **Route:** `/settings/tags` statt `/tags`
- **Anforderung:** Tags gehören in die Einstellungen, bei System
- **Aufwand:** 2 Stunden

#### 6.2 Tags Baumstruktur
- **Datei:** `frontend/src/pages/SettingsTags.tsx` (neu)
- **Anforderung:** Baumstruktur um Tags zu sortieren (Parent-Child Beziehung)
- **Backend:** `tags` Tabelle braucht `parent_id` Spalte (Migration 0138)
- **Frontend:** TreeView Komponente für Tags
- **Aufwand:** 1 Tag

#### 6.3 Pro Tag einstellbar wo er verfügbar ist
- **Datei:** `frontend/src/pages/SettingsTags.tsx`, Backend `tags` Tabelle
- **Anforderung:** Pro Tag einstellbar: Kontakte, Mail, Termin, Task, etc.
- **Backend:** `tag_applications` Tabelle (tag_id, entity_type) oder JSON-Spalte `applicable_to` in tags (Migration 0138)
- **Frontend:** Multi-Select im Tag-Editor
- **Aufwand:** 4 Stunden

#### 6.4 Symbol und Farbe pro Tag
- **Datei:** `frontend/src/pages/SettingsTags.tsx`, Backend `tags` Tabelle
- **Anforderung:** Symbol (Icon) und Farbe pro Tag einstellbar
- **Backend:** `icon` Spalte in tags (Migration 0138), `color` existiert schon
- **Frontend:** Icon-Picker und Color-Picker im Tag-Editor
- **Aufwand:** 4 Stunden

**Gesamtaufwand Phase 6:** ~2 Tage

---

### Phase 7: Reports UI-Überarbeitung (2 Tage)

#### 7.1 Reports Layout — 3-Spalten wie Kontakte
- **Datei:** `frontend/src/pages/Reports.tsx` (Umbau, 433 Zeilen)
- **Anforderung:** Linke Sidebar mit Baumstruktur (Ordner zum Sortieren), Mitte verschiedene Ansichten (Liste/Karten), rechts Detailbereich
- **Aufbau:**
  - **Toolbar:** PluginToolbar mit Filter, Ansichts-Umschalter, Neuer Report
  - **Links:** Baumansicht — nach Ordner/Gruppe sortierbar
  - **Mitte:** Liste oder Karten-Ansicht — umschaltbar
  - **Rechts:** ReportDetail — ausgewählter Report mit Vorschau
- **Backend:** `reports` Tabelle braucht `folder_id` Spalte (Migration 0139) für Ordner-Sortierung
- **Aufwand:** 2 Tage

**Gesamtaufwand Phase 7:** ~2 Tage

---

### Phase 8: Kommunikation UI-Überarbeitung (2-3 Tage)

#### 8.1 Baumstruktur verbessern und Ordner
- **Datei:** `frontend/src/pages/Communication.tsx` (anpassen, 859 Zeilen)
- **Anforderung:** Baumstruktur größer/übersichtlicher, Ordner für Chats
- **Aufbau:**
  - **Links:** Baumansicht mit Ordnern — System, AI, Kollegen, Custom Ordner
  - **Baum breiter:** ResizablePanel `initialWidth=280` statt 224
  - **Ordner:** `comm_conversation_folders` Tabelle oder `folder_id` in `comm_conversations` (Migration 0140)
- **Aufwand:** 1-2 Tage

#### 8.2 AI Chat in Kommunikation (nach Phase 2)
- AI Chats werden als eigener Baum-Knoten 'KI Chats' in Communication angezeigt
- Neuer AI Chat Button in Toolbar erstellt `comm_conversation` mit `conversation_type='ai'`
- `streamChat()` wird aufgerufen mit `comm_conversation_id` als Session-ID
- AI Messages werden in `comm_messages` gespeichert
- **Aufwand:** in Phase 2

**Gesamtaufwand Phase 8:** ~1-2 Tage (Phase 2 vorab)

---

### Phase 9: Strukturelle Änderungen (0.5 Tage)

#### 9.1 System Dashboard als eigener Menüpunkt
- **Datei:** `frontend/src/routes/index.tsx`, Navigation
- **Problem:** System Dashboard ist unter Settings, soll eigener Punkt auf Startseite-Ebene sein
- **Fix:** Route `/system-dashboard` existiert schon — muss in Navigation als Top-Level Menüpunkt angezeigt werden
- **Aufwand:** 1 Stunde

#### 9.2 Mail — Postfach mit IMAP anlegen testen
- **Datei:** `frontend/src/pages/Mail.tsx`, `frontend/src/pages/MailSettings.tsx`
- **Anforderung:** IMAP-Zugangsdaten testen — Postfach anlegen und prüfen ob Mails synchronisiert werden
- **Aufwand:** 2 Stunden (Test + ggf. Bugfix)

**Gesamtaufwand Phase 9:** ~0.5 Tage

---

### Phase-O-Phasenübersicht

| Phase | Inhalt | Aufwand | Migration | Abhängigkeit |
|-------|--------|---------|-----------|-------------|
| 1 | Echte Bugs fixen | 2-3 Tage | Keine | Keine |
| 2 | AI Assistent → Kommunikation | 2-3 Tage | 0137 | Phase 1.6 |
| 3 | Wiki UI + WYSIWYG | 3-4 Tage | Keine | Phase 1.4 |
| 4 | Tasks UI neu | 2-3 Tage | Keine | Keine |
| 5 | Kalender UI | 1 Tag | Keine | Phase 1.5 |
| 6 | Tags Umstrukturierung | 2 Tage | 0138 | Keine |
| 7 | Reports UI | 2 Tage | 0139 | Keine |
| 8 | Kommunikation UI | 1-2 Tage | 0140 | Phase 2 |
| 9 | Strukturelle Änderungen | 0.5 Tage | Keine | Keine |

**Gesamtaufwand:** ~17-22 Tage

#### Reihenfolge:
1. **Phase 1** (Bugs) — zuerst, damit grundlegende Funktionen arbeiten
2. **Phase 9** (Strukturelle Änderungen) — schnell, wenig Aufwand
3. **Phase 5** (Kalender) — kleines Update, baut auf Phase 1 auf
4. **Phase 2** (AI Assistent → Kommunikation) — entfernt paralleles System, baut auf Phase 1.6 auf
5. **Phase 6** (Tags) — unabhängig, Backend + Frontend
6. **Phase 4** (Tasks) — großer Umbau, unabhängig
7. **Phase 3** (Wiki) — größter Umbau (WYSIWYG Editor), baut auf Phase 1 auf
8. **Phase 7** (Reports) — großer Umbau, unabhängig
9. **Phase 8** (Kommunikation) — baut auf Phase 2 auf

#### Migrationen:
- **0137:** AI Assistent Tabellen → comm_conversations/comm_messages + Drop alte Tabellen
- **0138:** Tags: parent_id, applicable_to, icon Spalten
- **0139:** Reports: folder_id Spalte
- **0140:** Communication: comm_conversation_folders Tabelle oder folder_id in comm_conversations

#### Was ich NICHT tun werde:
- Keine Massen-Scripts die neue Fehler verursachen
- Keine Änderungen ohne Verifizierung gegen Produktion
- Keine neuen Plugins wenn bestehende erweitert werden können
- Keine neuen Pages wenn bestehende umgebaut werden können
- Jede Änderung wird mit tsc und API-Test verifiziert

#### Was ich brauche:
- **IMAP-Zugangsdaten:** Für Mail-Postfach-Test (Phase 9.2)

---

## Zusammenfassung

| Phase | Dauer | Hauptdeliverable |
|-------|-------|----------------|
| A — Stabilität | 1 Woche | Verifikation, Performance-Baseline |
| B — System-Konsolidierung | 6 Wochen | LLM, Redis, **pgvector HNSW**, Storage, **WebSocket+Redis Pub/Sub**, Event-/Trigger-Kern, Message-Konsolidierung, MiniApp-Wiring, Plugin-Contract |
| C — Core UI | 4 Wochen | vorhandene Navigation/Workspace/Settings/Agent-/Business-UI fertigstellen, PWA-Service-Worker |
| C.5 — Import/Export | 2 Wochen | vorhandenen Import/Export modularisieren, Mapping/Preview, Contact/Company Referenzhandler |
| D — Undo/Restore | 4 Wochen | vorhandene EntityHistory erweitern, Whitelist-Restore, Trash, Bulk-Restore, IMAP-sauberes Mail-Restore |
| E — Search | 6 Wochen | vorhandene Search-Basis → FTS+Vector+RAG+Graph, globale + spezifische Suche, Auto-Indexierung, AI/MCP/API |
| F — Agents | 6 Wochen | vorhandene Agent-Basis → ReAct, kleiner Skill-Kern, Tools+Skills, Permissions, Proactive/UI-Trigger, Workstream, Approval |
| G — Workflows | 6 Wochen | vorhandene Workflow/Automation-Basis → durable/resumable Runtime, Steps, Trigger, Idempotency, Workstream, Approval |
| H — Firmenwissen | 6 Wochen | Wiki + DMS + Mail + Communication + Businesswissen, RAG, Evidence, Graph-Extraktion, Ask Knowledge im Workstream |
| I — Integration & Human-AI Workstream | 6 Wochen | Agent↔Workflow↔Knowledge↔Communication, echte MiniApps, Shared/Proactive/Mobile Workstreams, Dashboard, MCP, Polish |
| J — Controlled Self-Improvement | 5 Wochen | Improvement Signals/Proposals, Evaluation/Dry-Run, Approval, Versionierung/Rollback, Wirkungsmessung |
| K — EU Compliance Finalization | 1 Woche | AI-Use-Case-Register, DPIA/AI-Impact-Support, Incident/Retention, Compliance-E2E, Betriebsdoku |
| **L — Dokumente-Generator** | **~3 Wochen** | Briefpapier + Block-System + Drag/Drop-Editor + KI-Steuerung + E-Rechnung (Contract-Muster wie Import/Export) |
| **Total** | **52 Wochen** | **LeoPlatform Endstand-Kern inkl. Privacy/DSGVO/EU-AI-Act-by-Design** |

---

*Diese Roadmap basiert auf dem Endstand-Audit des aktuellen Code-Archivs und der gemeinsamen Detail-Review. Ziel bleibt: keine unnötigen Universalmodelle, keine Massenrefactorings und keine parallelen Mechanismen. Gemeinsame technische Kerne werden dort genutzt, wo Semantik wirklich gleich ist; fachliche Speziallogik bleibt erlaubt. Bestehender funktionierender Code wird respektiert. Die eingebauten Privacy-/AI-Compliance-Funktionen schaffen technische Voraussetzungen und Nachweise; die rechtliche Konformität eines konkreten Deployments/Branchenplugins hängt zusätzlich von dessen tatsächlichem Zweck, Datenverarbeitung, Betreiberrolle und organisatorischen Maßnahmen ab.*

---

## Phase L — Dokumente-Generator ✓ ABGESCHLOSSEN (2026-08-29/30, Commits b311ab7 + 559bba6, deployed, Health healthy, Alembic 0143)

**Ziel:** Zentrale Dokument-Generierung mit Briefpapier + dynamischen Blöcken, Drag/Drop-Editor, KI-Steuerung, E-Rechnung-Fähigkeit. Module registrieren ihre Blöcke als Contribution (Contract-Muster wie Import/Export).

**Basis:** report_generator-Plugin (Jinja2-Templates, pdf_generator.py, Background-Jobs, ReportTemplate/ReportInstance-Models) — Erweiterung statt Neubau.

### L1 — Block-System (2-3 Tage)
- Briefpapier-Modell (pro Tenant: Logo, Header/Footer, CSS)
- Block-Modell (typ: text/table/chart/placeholder, order, content)
- Block-Registrierung durch Module via Contract (`document_blocks` wie `importexport_entities`)
- print_templates-Tabelle (Briefpapier-Ref + Block-Komposition)

### L2 — Drag/Drop-Editor (3-5 Tage)
- Frontend: Block-Palette (registrierte Blöcke des Moduls), Canvas, Platzierung
- Placeholder-Editor (`{{firstname}}`, `{{company.logo}}`)
- Live-Preview

### L3 — Renderer-Integration (1-2 Tage)
- report_generator-Engine an Block-Komposition anbinden
- Jinja2-Templates aus Block-Komposition generieren
- PDF/Excel/CSV-Output über bestehende Engine

### L4 — KI-Steuerung (1-2 Tage)
- „Erstelle Rechnungsvorlage" via AI-Module (agent_loop existiert)
- Template-Vorschläge aus Block-Komposition

### L5 — E-Rechnung (2-3 Tage)
- XRechnung/ZUGFeRD-Format (Verkauf-Modul registriert Rechnungs-Blöcke)
- Klären: Steuer-Behörden (Deutschland, B2B-Pflicht ab 2027) oder Kunden-Lieferungen?

**Abhängigkeiten:** L5 benötigt Phase F (Agents) und das Verkaufs-Modul (noch nicht gebaut).

**Verwandte Issues:** #359 (Import/Export Contribution — gleiche Plugin-Philosophie).

---

## Phase M — MiniApp-Plattform & Dashboard-Builder (geplant, user-abgestimmt 2026-08-29)

**Ziel:** MiniApps als universelles, teilbares UI-Baustein-System über alle Hosts (Chat, Dashboard, Windows, AI-Agenten). Dashboard-Builder mit Edit-Modus, Drag&Drop, Resize, Tabs und pro-Widget-Settings. System-Dashboard-Teile werden zurück in Plugins gebaut (Core wird zum reinen Host).

**Basis (Live-Bestand 2026-08-29):**
- `kommunikation/miniapp_registry.py` (92 Z., MiniAppDef mit register/unregister/unregister_plugin — inkl. Lifecycle-Cleanup)
- `MiniAppContribution` im Manifest-Schema (app_id, name, icon, description, render_schema) — **LÜCKE: kein permission-Feld**
- `FrontendDashboardWidget` im Manifest (id, component, col_span, row_span, permission) — **LÜCKE: kein settings_schema**
- `MiniAppBlock.tsx` als comm-Block-Typ (Chat-Host — fertig verdrahtet)
- `DashboardGrid`/`DashboardWidgetLoader` + 4 Widgets (RecentContacts, TasksSummary, CalendarUpcoming)
- Dashboard.tsx (170 Z.) mit hardcodierten StatCards (via contacts-Contract `get_counts`), ActivityFeed (via Audit-Log), System-Metrics (Admin-only) — **Rückbau-Bestand**
- `app/routes/dashboard.py` listet manifest `dashboard_widgets` (bereits permission-agnostisch, nur `dashboard:read` auf Endpoint-Ebene)
- @dnd-kit (core/sortable/utilities) bereits im Projekt (Referenz: SettingsMenuOrder, Dokumente-BlockEditor)
- windowStore (Window-Manager) existiert für spätere Hosts

**Architektur-Entscheidung (user-bestiätigt):** EINE Universal-Registry statt zweier paralleler Systeme — `dashboard_widgets` wird Alias von `miniapps`; jedes Plugin/System registriert MiniApps via Contribution (gleiches Muster wie settings_pages/print document blocks, #359-Philosophie). Ein Host-Set: Chat-Block (fertig), Dashboard (neu), Windows (M6), AI-Agenten-Tool-Ausgabe (M6).


**⚠️ Abgrenzung Workspace ≠ Dashboard (user-korrigiert 2026-08-30):**
- **Dashboard (diese Phase M)** = PERSÖNLICH: jeder User baut eigene Dashboards (Layout/Tabs/Instanzen) — Speicher ist die NEUE `dashboards`-Tabelle (owner-basiert). NIEMALS `workspace_widgets` dafür verwenden.
- **Workspace (Phase N)** = ADMIN-Kontext für Gruppen: welche Module sichtbar sind (fertig) + Modul-Teilmengen (Scopes) + welche Widget-TYPEN der Workspace anbietet (`workspace_widgets`, existiert bereits — Workspace-Eigentum).
- Schnittstelle: der aktive Workspace begrenzt nur die VERFÜGBAREN Widget-Typen; das persönliche Layout bleibt User-Eigentum und wird von keinem Workspace überschrieben.


### M1 — Universal-MiniApp-Registry (2-3 Tage)
- miniapp_registry aus kommunikation-Plugin in Plugin-Layer heben (Plattform-Konzept, kommunikation behält Chat-Hosting)
- MiniAppDef/MiniAppContribution erweitern: `permission` (Pflicht-Feld, fail-closed), `settings_schema` (generisches Settings-Form), `col_span`/`row_span`, `min_size`
- `dashboard_widgets` (Manifest) → Alias von `miniapps` (Rückwärtskompatibilität, ein Contribution-Typ)
- `/api/v1/miniapps`-Endpoint: Registry-Listing **server-seitig permission-gefiltert** (nur MiniApps sichtbar, für die der User die Permission hat)
- Host-Rendering prüft Permission zusätzlich beim Render (Defense-in-Depth wie Plugin-Routen)
- Lifecycle: Plugin-Deaktivierung → unregister_plugin → Widgets verschwinden aus allen Hosts

### M2 — Dashboard-Backend (2-3 Tage)
- `dashboards`-Tabelle: pro User mehrere Dashboards, Tabs, Layout als JSONB (`[{tab, widgets: [{app_id, settings, col, row, span}]}]`), RLS fail-closed + crm_api-Policy (0084-Muster)
- CRUD-Endpoints (list/create/update/delete + set-default), Tenant-Scoping, Owner-only oder Admin
- Dual-Path: Plugin-SQL idempotent + Alembic-Konvergenz (Gate-B-Muster wie 0143)
- Default-Dashboard-Seed beim ersten Aufruf (aus Registrierungs-Order abgeleitet)

### M3 — Dashboard-Builder-Frontend (3-5 Tage)
- Edit-Modus als Modus-Schalter: aktiv → Widgets hinzufügen/entfernen, Größe ändern (col/row-span), Einstellungen; beenden → persistiertes Layout, reine Ansicht
- Drag&Drop-Grid (@dnd-kit, Referenz BlockEditor/SettingsMenuOrder): Platzierung + Umsortieren
- Widget-Palette: verfügbare MiniApps (aus `/api/v1/miniapps`, permission-gefiltert), Suche/Kategorie
- Generisches Settings-Form pro Widget aus `settings_schema` (gleiche Philosophie wie Block-Config-Panels beim Dokumente-Editor)
- Tabs: mehrere Dashboards pro User, Tab-Verwaltung im Edit-Modus
- Dashboard.tsx wird zum reinen Host (keine hardcodierten Inhalte mehr)

### M4 — System-Rückbau (2-3 Tage)
- StatCards (Firmen-/Kontakt-Zähler via contacts-Contract) → contacts-Plugin-MiniApp
- Aktiv-diese-Woche/Neu-diesen-Monat + ActivityFeed (Audit-Log) → audit/auditlog-MiniApp
- System-Metrics-Block (DB/Redis/Worker/LLM-Kosten, Admin) → System-MiniApp mit `settings:read`-Permission
- Bestehende Dashboard-Widgets (RecentContacts, TasksSummary, CalendarUpcoming) zu MiniApps migrieren (gleiches Format, dann Chat-fähig)

### M5 — Plugin-MiniApps (2-3 Tage)
- contacts, tasks, calendar, wiki, dms, mail, knowledge (Graph-RAG), automation liefern jeweils MiniApps via Manifest-Contribution
- Jede MiniApp automatisch überall verfügbar: Chat senden + Dashboard platzieren
- Permission je MiniApp passend zum Owner-Modul (z.B. `tasks:read` für TaskSummary)

### M6 — Weitere Hosts (2-3 Tage)
- AI-Agenten-Tool: Agent kann MiniApp als Ausgabe-Block in Chat-Antwort einbetten (miniapp-Block-Typ existiert, Tool-Registry erweitern)
- Windows (windowStore): MiniApp per Klick/Expand in eigenem Fenster öffnen
- Evaluiert: Wiki-Einbettung (BlockRenderer-Muster) — nur wenn Bedarf bleibt

**Abhängigkeiten:** M3 benötigt M1+M2. M4/M5 nach M3 (Host muss stehen). M6 zuletzt.

**Verwandte Phasen/Issues:** Phase L (Gleiche Contribution-Philosophie), #359 (Contract-Muster), Phase F (Agenten für M6).

---

## Phase N — Workspace-Scopes: Modul-Teilmengen pro Arbeitskontext (geplant, user-abgestimmt 2026-08-30)

**Ziel:** Workspaces werden zu voll anpassbaren Arbeitskontexten: jedes Modul kann pro Workspace auf eine Teilmenge eingeschränkt werden (z.B. nur Kontakt-Ordner X+Y, nur DMS-Ordner „Angebote", nur Mail-Postfach vertrieb@, nur Kalender „Vertrieb"). Admin-definiert für zugewiesene User-Gruppen — klar getrennt vom persönlichen Dashboard (Phase M).

**Klare Trennung (user-korrigiert):**
- Workspace = Admin-Kontext, Gruppen-Feature: WAS ist sichtbar/verfügbar (Module, Teilmengen, Widget-Typ-Angebot via `workspace_widgets`)
- Dashboard = persönlich, User-Feature: WIE ICH mein Dashboard baue (Phase M, `dashboards`-Tabelle)
- Beide Systeme berühren sich NUR an einer Schnittstelle: der aktive Workspace begrenzt das Widget-Typ-Angebot; das persönliche Layout bleibt unberührt.

**Basis (Live-Bestand, 0 Umbau):**
- `workspace_modules.config` (JSONB) — existiert, ungenutzt → Scope-Speicher pro Modul
- `X-Workspace-ID` Header + API-Client-Interceptor (pro Tab) — existiert, wird vom Backend gelesen
- `/api/v1/workspaces/context` — existiert, liefert Modul-Konfiguration aus
- Sidebar filtert bereits live (isModuleVisible — Consumer-Beweis)
- 17/17 Workspace-Tests grün, RLS auf allen 4 Tabellen
- Contract-Muster für die Scope-Registry (wie document_placeholders)

**Security-Invariante:** Scope = reine UND-Einschränkung. Sichtbarkeit = Workspace-Scope ∧ RLS ∧ ABAC ∧ Permissions. Ein Workspace kann NIE mehr sichtbar machen, nur weniger. Ohne aktiven Workspace = kein Filter (rückwärtskompatibel, wie Sidebar).

### N1 — Scope-Registry via Contract (2 Tage)
- Plugins deklarieren `workspace_scopes()` → verfügbare Scope-Dimensionen + Wertequellen (z.B. „folder_ids, Multiselect, via /contacts/folders")
- `/context` liefert `config` der Module mit aus; Scope-Definitionen-Endpoint für den Editor

### N2 — Dynamischer Scope-Editor (2-3 Tage)
- WorkspaceManager: pro Modul automatisches Filter-UI aus der Registry (Multiselects für Ordner/Postfächer/Kalender, Toggles, Standard-Ansichten)
- Speicherung in `workspace_modules.config`

### N3 — Erste vier Module integrieren (2-3 Tage)
- Contacts: Ordner-Teilmengen, Firmen/Personen-Filter, Standard-Saved-View
- DMS: Ordner-Teilmengen, Datei-Typ-Filter
- Mail: Postfach-Teilmengen
- Calendar: Kalender-Teilmengen, Standard-Ansicht
- Backend respektiert X-Workspace-ID bei Listen (additive Filter-Logik, kein Umbau bestehender Routes)

### N4 — Restliche Module (2-3 Tage)
- Tasks (Boards/Listen, „nur meine"), Kommunikation (Räume), Wiki (Kategorien), Reports/Dokumente (Vorlagen), Automation (Agenten), Tags, Suche (Provider), Navigation (Menü-Reihenfolge, Startseite pro Workspace)
- Dashboard-Schnittstelle: workspace_widgets bestimmt verfügbare Widget-TYPEN pro Workspace (Admin) — persönliches Layout bleibt Phase M

**Abhängigkeiten:** unabhängig von Phase M. N3/N4 nach N1+N2.

---

## Phase P — Notizen-App (Notion-artig, ersetzt das Wiki komplett) (geplant, user-abgestimmt 2026-08-30)

**Ziel:** Aus dem Wiki wird eine Notion-artige Notizen-/Firmen-Wissen-App: Seiten-Baum (beliebig tief, statt flacher Kategorien), Inline-Block-Editor mit Slash-Menü und Drag&Drop, Quer-Verweise zwischen Seiten, MiniApp-Einbettung, vollständige Such-Indexierung. Das alte Wiki wird KOMPLETT ersetzt (keine Legacy-App parallel).

**User-Entscheidungen (2026-08-30):**
- Keine Notion-Datenbanken zunächst — stattdessen MiniApps als einbettbare Blöcke (Phase M-Synergie)
- Später: Plugin-Erweiterbarkeit (eigene Block-Typen via Contract), evtl. Datenbank-Block als Plugin nachlieferbar
- Vollständige Such-Indexierung ist PFLICHT (Notizen/Firmen-Wissen auffindbar)
- Quer-Verweise (Seiten verlinken Seiten)

**Edit-Konzept (Notion-Recherche 2026-08-30):** Notion hat KEINEN separaten Bearbeitungsmodus — "all content is editable by default": Klick in die Seite = tippen, Auto-Save im Hintergrund, Slash-Menü für Block-Typen. Confluence macht stattdessen Draft/Publish-Workflow. Für uns: Live-Inline-Editing wie Notion als Standard; der "Lese-Modus" entsteht natürlich über Permissions (nur-Lesen = gerenderte Seite ohne Editierfunktion) + optional Page-Lock. Kein Mode-Toggle im UI nötig.

**Basis:** Wiki-Plugin (486 Z. Backend: WikiCategory/WikiArticle/WikiArticleVersion + 10 Endpoints) wird erweitert, nicht neu gebaut. Block-Muster aus Phase L (JSONB {id, type, config}), dnd-kit vorhanden, Custom-Field-Engine für spätere Properties, Entity-Links für CRM-Quer-Verweise vorhanden. Unified Search: Provider-Registry + BaseSearchProvider (Embeddings + hybrid FTS/vector) + chunking existieren — die App liefert Provider + Re-Index-Hook.

### P1 — Datenmodell & Migration (2 Tage)
- WikiArticle → WikiPage: `blocks JSONB` (statt content Text), `parent_id` (Seiten-Hierarchie statt Kategorien), `icon`, `is_favorite`, **`is_locked` (Page-Lock, user-entschieden 2026-08-30)**; Quer-Verweise als Block-Typ page_link
- Migration: Markdown-Artikel → Text-Blöcke, Kategorien → Eltern-Seiten, Versionen (WikiArticleVersion) bleiben erhalten
- Dual-Path: Plugin-SQL idempotent + Alembic-Konvergenz (Gate-B-Muster)

### P2 — Sidebar mit Seiten-Baum (2 Tage)
- Notion-artiger Baum: Seiten anlegen/umbenennen/löschen, Drag&Drop-Umsortierung (dnd-kit), + Button, Kontextmenü, Favoriten, Seitensuche
- Ersetzt die alte Kategorien-Navigation komplett

### P3 — Inline-Block-Editor (4-5 Tage) — Herzstück
- Live-Inline-Editing (Klick = tippen, kein Mode-Toggle), Auto-Save debounced in blocks JSONB
- Slash-Menü: „/" → Block-Typ-Auswahl
- Block-Typen: Text, H1-H3, To-do, Toggle (auf/zu), Quote, Callout, Code, Divider, Bild, Page-Link (Quer-Verweis mit Auto-Vervollständigung), MiniApp
- Drag&Drop-Block-Umsortierung (dnd-kit, Phase-L-Erfahrung)
- **Page-Lock (user-bestaetigt 2026-08-30):** `is_locked = true` = Seite nicht editierbar (auch mit wiki:write). Backend lehnt Block-Updates mit 409 `page_locked` ab; Frontend zeigt rein gerenderte Seite + Schloss-Badge; Lock setzen/loeschen nur Owner oder Admin (Lock-Button in der Seitentoolbar); gelockte Seiten bleiben fuer Search/Versionen/Kommentare normal indexiert

### P4 — MiniApp-Blöcke + Plugin-Erweiterbarkeit (1-2 Tage)
- „/ MiniApp"-Block-Typ: registrierte MiniApps in Seiten rendern (erster MiniApp-Konsument neben Chat — treibt Phase M mit)
- Contract `wiki_blocks()`: Plugins melden eigene Block-Typen für den Editor an (Muster document_blocks) — Basis für späteren Datenbank-Block

### P5 — Vollständige Such-Indexierung (1-2 Tage)
- Content-Extraktion aus Blöcken (Text/Überschriften/To-do/Callout) → content_tsv + Embedding-Chunks (chunking.py)
- WikiPage-Search-Provider an unified_search (hybrid FTS + vector, Re-Index bei jedem Auto-Save)
- Suchergebnis verlinkt direkt auf Seite + Sprungmarke

**Abhängigkeiten:** P4 benötigt M1 (Universal-Registry). P1-P3, P5 unabhängig startbar.

## Phase Q — Frontend-Plugin-Architektur ✓ ABGESCHLOSSEN (2026-09-13, Commits 895f85d + b666fe5, deployed, Health healthy)

> **Umgesetzt am selben Tag wie geplant.** Q3 (Generator + PluginLoader) + Q4 (MiniAppHost)
> in 895f85d; Q1 (statische Plugin-Routen entfernt) + Q2 (Settings-Routen + Renderer-Variante)
> in b666fe5. Details und Live-Beweise: PROGRESS.md Phase-Q-Section.


**Ziel:** Die letzten verbliebenen Plugin-Grenzverletzungen im Frontend beseitigen — ein Plugin soll sein Backend, Manifest UND React-Seite liefern können, ohne dass zentrale Frontend-Dateien angefasst werden müssen. Basis: externes Architektur-Audit (2026-09-13), dessen Backend-Punkte bereits gefixt sind (siehe PROGRESS.md „Externer Architektur-Audit"); die vier Frontend-Punkte sind bewusst als eigene Phase geplant, weil sie ein durchdachtes Build-Time-Discovery-Konzept erfordern (Vite kann dynamische Imports zur Laufzeit im Production-Bundle nicht zuverlässig auflösen).

### Q1 — Statische Plugin-Routen aus routes/index.tsx entfernen (Doppel-Architektur)
- Status quo: `/calendar`, `/dms`, `/mail`, `/reports`, `/tasks`, `/communication`, `/workflows`, `/import-export`, `/wiki`, `/agents`, `/automation` sind statisch im zentralen Router eingetragen UND kommen gleichzeitig über die Plugin-Manifeste via PluginRouteRenderer.
- Ziel: Nur noch PluginRouteRenderer bedient Plugin-Seiten; statische Einträge nur für echte Core-Seiten (Dashboard, Settings-Shell, Login, Trash, Approvals bis Core-Migration).
- Risiko: Manifest-Routen müssen Permissions, Layout-Einbindung (AppShell-Children vs. eigenständig) und Ladezustände 1:1 abbilden.

### Q2 — Statische Settings-Routen ausdünnen
- Status quo: settings/roles, users, groups, mail, notifications, ai, ai-proactive, automation, documents sind statisch UND via settings_pages der Manifeste vorhanden.
- Ziel: settings_pages (Manifest) wird einzige Wahrheit für Plugin-Settings-Seiten; statische Einträge nur für Core-Settings (theme, system, backup, webhooks, menu, workspaces).

### Q3 — STATIC_COMPONENT_MAP ersetzen durch Build-Time-Discovery
- Status quo: PluginLoader.tsx hält eine zentrale Komponenten-Liste (~26 Einträge). Ein neues Plugin muss die Leo-Frontend-Codebasis anfassen.
- Ziel: Build-Skript scannt app/plugins/builtins/*/plugin.py auf FrontendPageRoute/SettingsPage/Component-Pfade und generiert automatisch eine Import-Map (generated, committet), die Vite statisch chunken kann. Keine manuelle Zentral-Liste mehr.

### Q4 — widgetRegistry in MiniAppHost durch generierte Map ersetzen
- Status quo: 11 Widget-Komponenten sind zentral hardcodiert (RecentContactsWidget, TasksSummaryWidget, ...).
- Ziel: Q3-Mechanismus deckt auch dashboard_widgets/miniapps component-Pfade ab; MiniAppHost nutzt dieselbe generierte Import-Map.

**Reihenfolge (wie umgesetzt):** Q3 → Q1/Q2 → Q4 (Q4 fiel mit Q3 mit, da MiniAppHost dieselbe generierte Map nutzt). Jeder Schritt mit Vitest-Sicherung der betroffenen Seiten und Production-Build-Verifikation (Chunk-Existenz prüfen).

## Externaudit Astra 2026-09-17 (41 Findings) — Sanierung PHASE S (bestätigt, NÄCHSTE PHASE, vor/neben R)

**Auditergebnis:** 2 P0 (KI führt nicht freigegebene Tools aus; Mandantenverwaltung kann globale Anmeldeidentitäten ändern), 29 P1, 10 P2. Geprüft am vollständigen Stand ee5545d (ZIP). Interne Verifikation am 2026-09-17: 10 Findings stichprobenartig am Code nachgelesen (F01, F02, F05, F08, F10, F12, F17, F24, F37, F41) — **alle 10 korrekt**. Übrige Findings: detailliert mit Zeilennummern belegt, Detail-Verifikation erfolgt jeweils bei Umsetzung. Volltext des Audits: [docs/audits/astra-audit-2026-09-17.md](docs/audits/astra-audit-2026-09-17.md); Kernpunkte je Finding in den Wellen-Issues.

**Strukturdiagnose (Astra):** Mehrere Stellen verwalten denselben Zustand (Plugin-Aktivität, Schema); Contracts garantieren zu wenig Verhalten; API- und Worker-Ausführung nicht gleichwertig; Berechtigungsprüfungen liegen zu weit vom Seiteneffekt entfernt; Statusanzeigen teils von tatsächlicher Funktion entkoppelt. — Bestätigt und deckt sich mit den realen Incidents (#389 Plugin down 4 Wochen, #380 158 Events failed).

**Sanierungswellen (Reihenfolge nach Risiko, an Astra-Empfehlung angelehnt):**

### Welle S1 — Sicherheitsgrenzen (P0 + Auth/Permission-Kette) — ZUERST
- **F01 (P0)** agent_loop._execute_tool: Tool-Ausführung ohne Allowlist- und Permission-Check — unmittelbar vor Handleraufruf prüfen: Tool in der dem LLM angebotenen Liste, required_permission gegen aktuelle User-Rechte, Verbote, Mandant, Plugin aktiv, ggf. Approval. Abnahme: nicht angebotenes Tool → Ablehnung, Handler bleibt null.
- **F02 (P0)** users.py update_user: globale User.email durch Mandanten-Admin (users:write) änderbar → globale Identitätsänderungen (email, is_system_admin global, Passwort) von Mandantenverwaltung trennen; nur Selbstservice oder echte globale Admin. Abnahme: Tenant-Admin kann globale E-Mail/Aktivstatus fremder Mandanten-Mitglieder nicht ändern.
- **F10** require_permission: Token-Scopes ersetzen User-Rechte (early-return) → effektive Rechte = Schnittmenge(User, Token-Scopes, Delegation), Verbote vorrangig. Abnahme: Token mail:write + User ohne mail:write → 403.
- **F05** require_active_plugin läuft vor Auth/ohne Mandantenkontext → Plugin-Gate an authentifizierten Kontext binden, fehlender Kontext = ablehnen. Abnahme: mandantendeaktiviertes Plugin → 403 auch bei gültiger Session.
- **F03** Session-Widerruf: Deaktivierung/Austritt/Löschen/Passwortwechsel müssen in Redis- UND DB-Fallback-Sessionpfaden wirken; Widerruf dauerhaft speichern. Abnahme: Widerruf wirkt auch bei Redis-Ausfall.
- **F11** Approval-Resolution: approver_id/Ablauf/Gruppe/Atomarität prüfen, Entscheider getrennt speichern, Approval an Aktion+Argumente+Revision binden.
- **F15** Workflow-HTTP: aufgelöste IPv4/6-Ziele gegen Privatnetz prüfen, Verbindung an geprüfte Auflösung binden, Redirects prüfen.
- **F20** prestart überschreibt gezielte Rechte-Entzüge (0100) mit pauschalem GRANT DELETE → Tabellenschutz nur migrieren; keine Rechteanhebung beim Start.
- **F21** test_migrations.sh: MIGRATION_DATABASE_URL überschreiben + Zielidentität vor DDL prüfen (sonst Gefahr für echte DB).
- **F23** Tenant-Backup-API triggert datenbankweiten Restore → Gesamtrestore als globale Betriebsoperation mit separater Berechtigung.
- **F30** Admin-Standardpasswort bei unkonfiguriertem Start → verpflichtendes Secret oder sicherer Einmal-Generierung.

### Welle S2 — Ausführung verbinden (Worker, Jobs, Contracts, Migrationen)
- **F06** Worker registriert keine der 44 Plugin-Event-Handler (BasePlugin.register_event_handlers ist leer) → API und Worker dieselbe idempotente Registrierung; Abnahme über echten Outbox-Durchgriff (Kontakt anlegen → Worker → Suchindex).
- **F07** Hintergrundjobs verlieren Mandantenkontext/Transaktionen → Mandant+Auftraggeber im Job-Payload Pflicht; Kontext vor erstem SQL; fachliche Änderung+Audit+Outbox gemeinsam committen.
- **F08** External-Agent-API: require_permission an Cookie-Auth gebunden (Bearer nie erreicht) + get_db() ist kein Contextmanager (TypeError) → gemeinsamer geprüfter Auth-Kontext für Cookie+Token; Session-Factory statt get_db.
- **F09** CRM-/MCP-Tools senden nicht anerkannte interne Header → Delegationsmechanismus (delegation_token.py) einbinden; UI und Agent gleiche Rechte-Antwort.
- **F12** Workflow approve/reject: approval["id"] auf ORM-Objekt (TypeError) + falsche resolve-Signatur → an zentralen Vertrag anpassen, wartende Freigabe auflösen statt Selbst-Genehmigung.
- **F13** Workflow-Engine: acquire_lock ohne Aufrufer, Idempotenz unvollständig, Resume ungesperrt → Engine als verbindlichen Zustandsübergang; Abnahme: Worker-Neustart + parallele Resume → keine Doppel-Mails.
- **F14** enforce_data_policy lässt Strings ungefiltert + läuft nur vor der Schleife mit db=None → strukturierte Filterung vor Serialisierung; JEDE LLM-Anfrage (inkl. Tool-Antworten) durch Policy; nicht ladbare Policy = Versand-Stop.
- **F16** Plugin-Lifecycle: prestart reaktiviert absichtlich deaktivierte Plugins; Aktivierungsfehler lassen DB-Zustand aktiv → gewünschten Zustand von Installation/Mandantenfreigabe/Laufzeitgesundheit trennen; Abnahme: Deaktivierung überlebt Neustart.
- **F17** 6 Produktionsstellen rufen ContractRegistry.get() auf (existiert nicht; nur get_contract) → Aufrufer fixen; Abnahme über reale Einstiegspunkte (Miniapp-Tools, proaktive Hinweise, Report-Jobs).
- **F18** Drei Schema-Verfahren (Alembic/Plugin-SQL/sync_plugin_schema) mit Sync-Verlust bei Unique/Partial-Indizes → einen Migrationsbesitzer pro Objekt; Startup-Sync als lesender Driftbericht.
- **F19** alembic/env.py lädt nur app.models (46/129 Tabellen; Sortierung scheitert) → deterministische vollständige Modelldiscovery.
- **F31** Provider-Registry vs. Reindex-Listen divergieren → Plugin-Beiträge als gemeinsame Quelle; Abnahme: neuer Provider wird vollständig indiziert.
- **F37** SMTP-Env-Namen (SMTP_USER vs smtp_username u.a.) → Compose/Config/Doku angleichen; Abnahme: Reset-/Alarm-Mail authentifiziert.
- **F40** Plugin-Migrationen nur Dateiname-Tracking → Hashes speichern und prüfen; Sollzustand vorhandener Tabellen (Spalten/FKs/Policies) vergleichen.
- **F41** Agenten-Stundenlimit zählt ab jetzt() statt letzte Stunde → timedelta(hours=1); Kontingent atomar reservieren.

### Welle S3 — Fachliche Integrität (Daten- und UI-Korrektheit)
- **F25** CSV-Import: Rollback vernichtet frühere Zeilen, Zähler behalten Erfolge, RLS-Kontext weg → Savepoints pro Zeile, Original-Zeilennummern; Zähler = Persistenz.
- **F26** DMS-Dedup vermischft Identität (fremder Datensatz statt eigener Upload) → Content-Storage vs. Fachobjekt trennen; jeder Upload eigene Identität/Rechte.
- **F27** Kalender: SQL-Filter wirft Serien weg bevor Wiederholungen berechnet werden; end_at-Dauer; Mehrtagesüberlappung → Serie nach Laufzeit selektieren, Wiederholungen im Fenster erzeugen.
- **F28** Import/Export ohne Fachrechte (import_export:write ≠ contacts:write; Export ohne Feldrechte) → Fachrechte UND Importrecht; Feldfilter vor Dateierzeugung.
- **F32** Suche: entity_types=[] = alle (soll 0), Filter nach Top-N, Offset unwirksam, before_search zu spät → None/[] unterscheiden; Filter vor Limit; Hook vor Parametern.
- **F33** Workspace-Wechsel invalidiert fachliche Querykeys nicht → Workspace in Query-Identität oder kontrolliert verwerfen.
- **F34** Mandantenwechsel: alte Daten bis Refetch sichtbar → kontrollierter Kontextwechsel (Abbrechen, Caches leeren, Header synchronisieren).
- **F38** pluginStore-Fehler → Dauerspinner (loaded bleibt false) → Fehler/Leer/Erfolg getrennt rendern, Retry anbieten.
- **F39** Office-Edit-Session verweist auf /preview (PDF-only) + Callback-Route existiert nicht → funktionsfähigen Ablauf anbinden oder Feature als nicht-betriebsbereit kennzeichnen.

### Welle S4 — Betriebsfreigabe (inkl. korrigierter Phase R)
- **F22** Backup im Container nicht betriebsfähig (pg_dump fehlt, Pfade nicht persistiert, Kontext-/User-Bugs) → dokumentierter Ablauf mit Programmen, Rechten, persistiertem Ziel.
- **F24** /health/ready liefert 200 bei not_ready; Worker-Check meldet up ohne Worker → korrekte HTTP-Codes (503), Heartbeat-Alter statt Queue-Länge.
- **F29** CI ohne Lockfiles/Testdienste/tatsächliches Artefakt → reproduzierbare Pipeline gegen eigenes Image.
- **F36** Komponenten-Map-Generator nicht verbindlich im Build → Check an npm-Build/Dockerfile/CI hängen.
- **F04** Suche: autocomplete/similar ohne Objekt-/Feldrechte; Snippet/Titel unfiltert zur LLM → ein Schutzpfad für ALLE Suchvarianten vor Snippet- und LLM-Übergabe.
- **F35** PWA abgeschaltet, aber Offline-Banner verspricht Schreibspeicherung → PWA wiederherstellen ODER Banner an Realität anpassen.
- Phase-R-Korrektur (siehe unten, bereits eingearbeitet).

**Abnahmeszenarien quer über alle Wellen (Astra-Vorschlag, verbindlich):**
1. Kontaktanlage → Audit/Outbox → separater Worker → Suchindex → erlaubte KI-Abfrage (F06, F07, F17, F04)
2. Mailentwurf → Freigabe → einmaliger Versand → nachvollziehbares Ergebnis (F11, F12, F13)

**Reihenfolge-Logik:** S1 zuerst (jede nicht autorisierte Aktion verboten), S2 parallel startbar nach S1-P0s, S3/S4 danach. Nach S1+S2 verifizierter Welle: Aufwand neu schätzen (Astra-Hinweis: die 9-14 Tage aus Phase R sind keine Schätzung für 41 Findings).

## Phase R — Betriebssicherheit & 95%-Produktionsreife (geplant, user-abgestimmt 2026-09-16 — läuft in S4 auf; korrigiert 2026-09-17 nach Astra-Kritik)

**Ziel:** Von „Produktion läuft stabil" zu „Produktion verlässlich": stille Ausfälle werden automatisch erkannt und alarmiert (Minuten statt Wochen), die Test-Suite wird zum vertrauenswürdigen Regressionsschutz, Schema-Drift wird automatisch erkannt, Kernprozesse werden nach jedem Deploy regressionsgetestet, Backups sind nachweislich wiederherstellbar.

**Warum diese Phase (Evidenz aus realen Incidents):**
- KI-Chat war 4 Wochen still down — ai_assistant migration_failed seit 2026-08-21, entdeckt am 2026-09-16 nur durch Zufall (#389)
- External-API war durch CSRF-Middleware für externe Systeme unbrauchbar (fix b91ee5b)
- Outbox: 158 failed Events wochenlang unbemerkt (#380)
- Suite-Isolation und alembic-check-Blockade verhindern verlässliche Regressionsschutz-Gates

**95%-Definition (korrigiert 2026-09-17 nach Astra-Kritik):** Die fünf Kriterien sind kein mathematischer Reifegrad, sondern **konkrete Freigabekriterien**. Dokumentiert wird: erfüllte Kriterien, verbleibende Risiken und bekannte Grenzen (Battle-Testing im Echtbetrieb). „95 %" = Zustand, in dem jeder Ausfall laut statt still wird; die restlichen ~5 % sind Echtbetriebs-Edge-Cases, die nur echte Nutzung findet.

**Astra-Kritik an Phase R (8 Punkte, 2026-09-17) — eingearbeitet:**
1. ARQ-Heartbeat überwacht sich nicht selbst → zusätzlich externe Überwachung außerhalb der ARQ/Redis-Ausfallkette (z.B. Cron auf Host oder externer Uptime-Check gegen /health/ready).
2. „Installiert aber inaktiv"-Alarm trifft absichtliche Deaktivierung → **Sollzustand** (DB desired state) mit tatsächlicher Betriebsbereitschaft vergleichen; nur Abweichung alarmiert.
3. Leere Queue ≠ laufender Worker → Worker-Heartbeat-ALTER und Verarbeitungsnachweis messen, nicht Queue-Länge.
4. Komplette Suite grün reicht nicht (Mocks/Admin-Tests können Rechtefehler verdecken) → zusätzlich echte API-/Worker-Prozesse mit tatsächlichen Laufzeitrollen prüfen.
5. Ein FK-Fix + Migrationshash genügt nicht → vollständige Modelldiscovery (F19) und eindeutige Schema-Verantwortung (F18) sind Voraussetzung; R3 hängt an S2.
6. E2E-Normalfälle prüfen Rechteentzug/Neustart nicht → Mehrmandanten-, Rollen-, Fehler- und Wiederaufnahme-Szenarien ergänzen.
7. Monatlicher Restorejob beweist keine sichere Zielwahl → isoliertes Ziel und tatsächliche DB-+Datei-Wiederherstellung nach Containerersatz nachweisen.
8. „95 % Produktionsreife" ist keine messbare Zahl → konkrete Freigabekriterien + verbleibende Risiken dokumentieren (siehe oben).

**Aufwandskorrektur (Astra):** Die 9-14 Tage gelten NICHT für die Behebung aller 41 Audit-Findings (Phase S). Neue Schätzung nach Abschluss von S1+S2.

### R1 — Stille-Ausfälle-Wächter + Alerting (2-3 Tage) — PRIORITY 1, größter Risikoreduktor
- ARQ-Heartbeat-Job (alle 5 Min) prüft: (a) /api/v1/plugins — installiert aber nicht active → ALARM (exakt der #389-Fall), (b) /health/ready — DB/Redis/Storage/Worker, (c) Outbox-DLQ — failed > 0 (#380-Klasse), (d) Worker-Queue-Länge
- Alarm-Kanal: E-Mail über bestehende Mail-Infra (SMTP) an Admins; Alarm-Zustand zusätzlich als rote Badge im Admin-UI (System-Dashboard)
- Abnahme live: Plugin absichtlich deaktivieren → Alarm muss nachweislich auslösen (Chaos-Test)
- Bestand, auf dem aufgebaut wird (kein Neubau): /health/ready (docs/monitoring.md), ARQ-Worker (app/core/worker.py), Mail-Plugin (SMTP), System-Dashboard-Routen

### R2 — Test-Suite verlässlich machen (2-3 Tage)
- Suite-Isolation fixen: Combo-Runs quaken mit „relation users does not exist" (Solo grün) — conftest.py-DB-Setup deterministisch machen
- Vitest-Worker-OOM fixen (Worker-/Fork-Konfiguration)
- Abnahme: `python -m pytest` kompletter Lauf grün + `npx vitest run` kompletter Lauf grün — erst DANACH gilt die Suite als verbindliches DoD-Gate

### R3 — Schema-Integrität automatisieren (1-2 Tage)
- entity_attachments-FK fixen → `alembic check` läuft als Schema-Drift-Gate
- Migration-Runner: Hash-Check ergänzen — geänderte getrackte Migration = Alarm statt stiller Skip (verhindert die #389-Bugklasse systemisch)
- scripts/schema_drift_check.py + scripts/check_migration_hashes.py in scripts/ci_pipeline.sh integrieren

### R4 — E2E-Kernprozess-Regression (2-3 Tage)
- Playwright-Suite über Kern-Flows: Login, Kontakte-CRUD, Mail senden/lesen, DMS upload/download, Kalender-Termin, KI-Chat-Antwort, Workflow-Ausführung, Gäste einladen
- Automatischer Run nach jedem Full-Deploy (fast-deploy.sh-Erweiterung)
- Bestand: Playwright-Setup existiert (frontend/e2e/, Login-E2E bewiesen funktioniert)

### R5 — Backup-/Restore-Nachweis (1-2 Tage)
- scripts/restore_drill.sh monatlich per ARQ-Job/Cron ausführen + Ergebnis alarmieren
- RTO/RPO messen und dokumentieren (scripts/backup.py, scripts/restore.py, restore_test.sh existieren)

### R6 — Ops-Runbook & Alarm-Kette final (1 Tag)
- Eskalationskette: Wer wird wie alarmiert (E-Mail/Handy), wer reagiert
- docs/incident-response-runbook.md um die realen Ausfallklassen ergänzen (Plugin-inactive, DLQ-Vollauf, Migration-Crash, CSRF/Auth-Layer, Worker-Stillstand) — jede mit Schritt-für-Schritt-Fix aus dem echten Incident

**Aufwand gesamt: ~9-14 Arbeitstage.** R1 zuerst (unabhängig startbar), R2 parallel, R3 nach R2, R4 nach R1, R5/R6 unabhängig. Kann mit Phase O/P verzahnt werden — aber R1-R3 vor neuen Features.

**Definition of Done Phase R:** Alle 5 Abnahmekriterien live gemessen und grün + ein dokumentierter Chaos-Test (absichtlicher Ausfall → Alarm in < 30 Min). Pro Task ein Forgejo-Issue mit Milestone „Phase R — Betriebssicherung" (AGENTS.md §9).

## UI-Backlog — Backend-Module ohne UI (laufend seit 2026-09-08, Source of Truth: PROGRESS.md-Tabelle)

**Kontext:** Frontend-Backend-Gegenüberstellung (2026-09-01) ergab 16 Backend-Module ohne UI (~64 Ops). User-Entscheidung: Module einzeln mit UI ausstatten, priorisiert nach Business-Nutzen. Jedes Modul folgt derselben Verifikationskette: Vitest → tsc → Production-Build → Deploy → Live-API-Check → Forgejo-Issue → PROGRESS.md-Update.

**Status 2026-09-16: 16/16 erledigt — UI-BACKLOG KOMPLETT.**
- Erledigt: 1 Approvals, 2 Delegations, 3 API-Tokens, 4 Tenants, 5 Marketplace, 6 Permission-Templates, 7 Skills, 8 Agent-Memory, 9 Outbox, 10 Policies, 11 Graph-RAG, 12 Companies, 13 Public-Share, 14 Guests, 15 External-Agent, 16 Ownership-Transfer (Commits + Issues #369, #372-#388 in PROGRESS.md-Tabelle)
- Alle 16 Backend-Module haben jetzt UI. Bei neuen Backend-Modulen ohne UI: analog verfahren.

**Architektur-Regel (seit Phase Q):** Plugin-Module (wie Marketplace, Skills, Agent-Memory) werden AUSSCHLIESSLICH via Plugin-Manifest registriert (page_routes + menu_items + Komponenten-Map-Generator) — routes/index.tsx und Sidebar.tsx bleiben unangetastet. Core-Module (wie Delegations, API-Tokens, Tenants, Permission-Templates) laufen als statische Core-Routen + Settings-Nav.

**Muster:** Jedes Modul = api/<modul>.ts (TanStack-Hooks) + pages/<Modul>.tsx (Karten/Dialoge/Permission-Gating) + i18n de/en + Vitest-Tests + Registrierung. Referenz-Implementierungen: Approvals (Core) und Marketplace (Plugin/Phase Q).