diff --git a/PLATFORM_ROADMAP.md b/PLATFORM_ROADMAP.md index d756736..eee2a97 100644 --- a/PLATFORM_ROADMAP.md +++ b/PLATFORM_ROADMAP.md @@ -1,1284 +1,1003 @@ # LeoCRM → LeoPlatform: Entwicklungs-Roadmap > **Erstellt:** 2026-08-11 -> **Aktualisiert:** 2026-08-12 — Phase 0.5 (Universal Undo & Restore) hinzugefügt -> **Status:** Draft — zur Diskussion -> **Prämisse:** LeoCRM wird zu einer KI-gesteuerten Business-Plattform erweitert +> **Überarbeitet:** 2026-08-13 — Endstand-Audit gegen aktuellen Code + vollständiges Produktziel eingearbeitet +> **Status:** Finale Endstand-Roadmap +> **Leitlinie:** «LeoCRM soll einfacher, konsistenter und erweiterbarer werden – nicht abstrakter, generischer oder frameworklastiger.» --- -## Ausgangslage +## Entscheidungsregel für alle Änderungen -LeoCRM ist bereits keine reine CRM-Anwendung mehr. Die bestehende Architektur bietet: +Bevor eine neue zentrale Abstraktion gebaut wird, müssen drei Fragen beantwortet werden: -- **26 Built-in-Plugins** inkl. AI Assistant, AI Proactive, AI UI Control, Automation, Agent Memory, GraphRAG, Unified Search, MCP Client/Server, Workflow Engine -- **Plugin-Manifest** mit Agent-Definitionen, Automation-Templates, Cron-Jobs, Heartbeats, Frontend-Komponenten, Custom Fields, Dashboard-Widgets -- **Event Bus + Transactional Outbox** für zuverlässige asynchrone Workflows -- **Hooks-System** (WordPress-style Actions + Filters) -- **Tool Registry** mit OpenAI Function-Calling Schema -- **CRM API Tool** — KI bekommt alle API-Endpunkte via OpenAPI-Spec-Injection -- **Agent Runner** mit Safety-Checks (Rate-Limit, Budget, Infinite-Loop-Detection) -- **Agent Coordinator** für Multi-Agent-Subtask-Delegation -- **10 Search Provider** (contact, company, mail, file, event, task, contactperson, tag, conversation, user) -- **pgvector** Embeddings (768-dim, HNSW Index) -- **ARQ Worker** für Background-Jobs -- **Multi-Tenant + RBAC + ABAC + Field-Permissions + Audit-Log** +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? -**Sicherheit:** Phase 1-5 Security Fix Plan komplett abgeschlossen. +Wenn eine Antwort nein ist: **Nicht generalisieren.** -**Offen:** 14 Frontend-Features in 4 Phasen (IMPLEMENTATION_PLAN.md, nicht begonnen). +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. + +### 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 0 — Foundation Cleanup & Frontend Completion [Woche 1-4] -Phase 0.5 — Universal Undo & Restore System [Woche 5-9] -Phase 0.7 — System-Konsolidierung (Attachments, LLM, [Woche 10-19] - WebSocket, Redis, Events, File Upload, - Import/Export, Error/Custom Fields, - Plugin-Specification & Contract, - Plugin Public Web Content) -Phase 0.8 — Frontend-Konsolidierung & UI-System [Woche 20-24] -Phase 1 — Unified Search Platform [Woche 25-28] -Phase 2 — Autonomous Agent Engine (ReAct-Loop) [Woche 29-34] -Phase 3 — Workflow Platform (n8n-Ersatz) [Woche 35-40] -Phase 4 — Knowledge Management & RAG [Woche 41-46] -Phase 5 — Platform Integration & Polish [Woche 47-50] -``` - -``` - ┌──────────────────────────────────────────────────────────┐ - │ LeoPlatform │ - │ │ - │ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │ - │ │ Search │ │ Agents │ │ Workflows │ │ Knowledge │ │ - │ │ (Phase 1)│ │ (Phase 2)│ │ (Phase 3)│ │ (Phase 4) │ │ - │ └────┬────┘ └────┬─────┘ └────┬─────┘ └─────┬─────┘ │ - │ │ │ │ │ │ - │ ┌────┴────────────┴──────────────┴──────────────┴────┐ │ - │ │ Plugin System + Event Bus │ │ - │ │ ┌────────┐ ┌─────────┐ ┌───────┐ ┌───────────────┐ │ │ - │ │ │ Tools │ │ Memory │ │ MCP │ │ Contracts │ │ │ - │ │ │Registry│ │ +GraphRAG│ │ C/S │ │ (Cross-Plugin)│ │ │ - │ │ └────────┘ └─────────┘ └───────┘ └───────────────┘ │ │ - │ └─────────────────────────────────────────────────────┘ │ - │ ┌─────────────────────────────────────────────────────┐ │ - │ │ Undo & Restore (Phase 0.5) — durchdringt alle Layer │ │ - │ └─────────────────────────────────────────────────────┘ │ - │ ┌─────────────────────────────────────────────────────┐ │ - │ │ PostgreSQL 16 + pgvector + Redis + ARQ Worker │ │ - │ └─────────────────────────────────────────────────────┘ │ - └──────────────────────────────────────────────────────────┘ +Phase A — Stabilität verifizieren [Woche 1] +Phase B — Kleine System-Konsolidierung [Woche 2-7] +Phase C — Core UI abschließen [Woche 8-11] +Phase C.5 — Modularer Import/Export [Woche 12-13] +Phase D — Minimal Undo/Restore [Woche 14-17] +Phase E — Unified Search vollständig [Woche 18-23] +Phase F — Agent MVP [Woche 24-29] +Phase G — Workflow MVP [Woche 30-35] +Phase H — Knowledge [Woche 36-41] +Phase I — Integration, Workstream & Polish [Woche 42-47] +Phase J — Controlled Self-Improvement [Woche 48-52] +Später — Advanced Autonomy/Automation nur bei echtem Bedarf ``` --- -## Phase 0 — Foundation Cleanup & Frontend Completion +## Phase A — Stabilität verifizieren -**Dauer:** 4 Wochen -**Ziel:** Offene Frontend-Features abschließen, Tests ergänzen, technische Schulden abbauen -**Begründung:** Bevor Platform-Features gebaut werden, muss das Fundament stabil sein. - -### 0.1 Frontend-Features (aus IMPLEMENTATION_PLAN.md) - -| Task | Beschreibung | Priorität | Aufwand | -|------|-------------|-----------|---------| -| F-WF-UI | Workflows UI — Liste, Editor, Instanz-Detail | Hoch | 3-4 Tage | -| F-DEDUP | Dedup/Merge UI für Kontakte | Mittel | 2-3 Tage | -| F-IMPORT | Import/Export UI (CSV, vCard) | Hoch | 2-3 Tage | -| F-PRINT | Print/PDF für Contact/Company | Niedrig | 1 Tag | -| F-TAGS | Tags UI — Tag-Manager, Tag-Filter | Mittel | 2 Tage | -| F-CF | Custom Fields UI — Editor, Anzeige in Detail | Mittel | 2-3 Tage | -| F-NOTIF | Notifications Dropdown in TopBar | Hoch | 1-2 Tage | -| F-FILTER | Saved Filters — speichern, laden, teilen | Mittel | 2 Tage | -| F-HISTORY | Entity History (Audit-Log UI) | Mittel | 2 Tage | -| F-TIMELINE | Activity Timeline (Kontakt-Historie) | Niedrig | 2 Tage | -| F-DOCS | API Docs UI (Swagger-UI Embed) | Niedrig | 0.5 Tage | -| F-WEBHOOK | Webhooks UI — CRUD, Test-Send | Niedrig | 1-2 Tage | -| F-BACKUP | Backup/Restore UI | Niedrig | 1 Tag | -| F-ONBOARD | Onboarding-Wizard für neue Nutzer | Niedrig | 1-2 Tage | - -### 0.4 Navigation & Workspace-UI - -Konkrete UI-Verbesserungen an der Navigation, Workspace-Verwaltung, und Seiten-Struktur. - -| Task | Beschreibung | Priorität | Aufwand | -|------|-------------|-----------|---------| -| F-NAV-WS-UI | **Workspace-Editor UI** — UI um Workspaces zusammenzustellen: Module auswählen, Unterpunkte/Reihenfolge konfigurieren, Vorschau. Drag-and-Drop für Menü-Reihenfolge | Hoch | 2-3 Tage | -| F-NAV-WS-DEFAULT | **Standard-Workspace konfigurierbar** — Standard-Workspace zeigt aktuell nichts. Soll stattdessen alles anzeigen was für den User freigeschaltet ist (basierend auf Permissions). Standard-Workspace muss konfigurierbar sein (Admin kann definieren was im Standard angezeigt wird) | Hoch | 1-2 Tage | -| F-NAV-WS-BACK | **Workspace Zurück-Button** — jeder Workspace braucht einen Zurück-Button um zum Startbildschirm zu kommen | Hoch | 0.5 Tage | -| F-NAV-AGENT | **Agentenverwaltung als eigene Seite** — eigener Menüpunkt im Startseiten-Menü (links der Workspace-Auswahl). Eigene Seite mit Menü links. NICHT innerhalb eines Workspaces — nur Topbar sichtbar mit Zurück-Button | Hoch | 1-2 Tage | -| F-NAV-SETTINGS | **Einstellungen als eigene Seite** — eigener Menüpunkt im Startseiten-Menü (links der Workspace-Auswahl). Einstellungen hat schon vertikale Reiter — komplett auf eigene Seite mit nur Topbar + Zurück-Button. NICHT innerhalb eines Workspaces | Hoch | 1-2 Tage | -| F-NAV-LAYOUT | **Seiten-Layout-Typen** — zwei Layout-Typen: (1) Workspace-Layout (mit Sidebar + Workspace-Menü), (2) Standalone-Layout (nur Topbar + eigenes Menü links + Zurück-Button). Agentenverwaltung und Einstellungen nutzen Standalone-Layout | Hoch | 1 Tag | - -### 0.2 Test-Ergänzungen +**Dauer:** 1 Woche +**Ziel:** Verifizieren dass die 9 Minimal-Fix-Pakete stabil sind. Keine neue Architekturarbeit. | Task | Beschreibung | |------|-------------| -| T-AM | Tests für agent_memory Plugin | -| T-GR | Tests für graph_rag Plugin | -| T-MP | Tests für marketplace Plugin | -| T-AUTO | Tests für automation Plugin (agent_runner, coordinator, scheduler) | -| T-E2E | E2E-Tests für kritische User-Flows (Login, Contact CRUD, Mail, Search) | - -### 0.3 Cleanup - -- Test-Instanzen CRM2/CRM3 löschen -- `dump.rdb` entfernen (in .gitignore prüfen) -- Veraltete ENV-Variablen bereinigen - -**Deliverables:** Stabile Frontend-UI für alle Core-Features, Test-Coverage > 80% für neue Plugins. +| 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-DOC | `docs/test-strategy.md` aktualisieren mit verbindlicher Test-Pipeline | --- -## Phase 0.5 — Universal Undo & Restore System - -**Dauer:** 5 Wochen -**Ziel:** Ein einziges universelles Undo/Restore-System für ALLE Entitäten — alle bestehenden fragmentierten History-Systeme werden konsolidiert und rückgebaut. Zukünftige Plugins bekommen eine klare Bauanleitung. -**Begründung:** Das bestehende EntityHistory-System ist nur halb implementiert. `restore_from_history()` unterstützt hardcoded nur `entity_type == "contact"`. `record_history()` wird nur in `contact_service.py` (3x) und `companies.py` (1x) aufgerufen — keine Plugins nutzen es. Gleichzeitig existieren 7+ separate History/Version-Systeme parallel (EntityHistory, AuditLog, CommMessageEdit, AgentVersion, AutomationVersion, ContactMergeHistory, WorkflowStepHistory, Backup) die alle etwas Ähnliches machen, aber völlig unabhängig voneinander. Das muss vereinheitlicht werden — ein System, eine Logik, eine API. - -### Aktueller State - -| Komponente | Status | -|---|---| -| EntityHistory Model | ✅ Vorhanden (snapshot_before, snapshot_after, changes) | -| entity_history_service | 🟡 Vorhanden, aber restore nur für Contact hardcoded | -| record_history() Aufrufe | 🟡 Nur Contact (3x) + Company (1x), keine Plugins | -| Soft-Delete (deleted_at) | ✅ Contact, Company, Mail, MailAccount, MailFolder, DMS, Tasks, Calendar | -| Backup/Restore (DB-Level) | ✅ pg_dump-basiert, scripts/backup.py + restore.py | -| Undo UI | ❌ Nicht vorhanden | -| Plugin-History-Integration | ❌ Nicht vorhanden | -| Mail-Undo (IMAP) | ❌ Nicht vorhanden | -| AI Chat History/Undo | ❌ Nicht vorhanden — AIChatSession, AIChatMessage, AIConversation, AIMessage haben kein deleted_at, keine History, kein Undo | -| Kommunikation Chat Undo | 🟡 CommMessage hat deleted_at + CommMessageEdit, aber kein Restore-Mechanismus | - -### 0.5.0 Konsolidierung & Rückbau bestehender Systeme - -Bevor das neue universelle System gebaut wird, müssen alle bestehenden fragmentierten History/Version-Systeme konsolidiert werden. Es darf nach Phase 0.5 nur noch **ein** Undo/Restore-System geben: EntityHistory. - -**Bestehende Systeme die konsolidiert werden:** - -| # | System | Model | Aktuelle Nutzung | Migration nach | Rückbau | -|---|---|---|---|---|---| -| 1 | EntityHistory | `EntityHistory` | Contact (3x), Company (1x) | Bleibt als einziges System | Wird erweitert | -| 2 | AuditLog | `AuditLog` | Calendar, DMS, Mail, Groups, MCP, Contacts | Bleibt als Compliance-Trail (kein Undo) | Kein Rückbau, klarere Trennung | -| 3 | CommMessageEdit | `CommMessageEdit` | Kommunikation Chat | EntityHistory mit `action=edit` | Table wird deprecated, Daten migriert | -| 4 | AgentVersion | `AgentVersion` | Automation Plugin | EntityHistory mit `action=version` | Table wird deprecated, Daten migriert | -| 5 | AutomationVersion | `AutomationVersion` | Automation Plugin | EntityHistory mit `action=version` | Table wird deprecated, Daten migriert | -| 6 | ContactMergeHistory | `ContactMergeHistory` | Contact Merge | EntityHistory mit `action=merge` | Table wird deprecated, Daten migriert | -| 7 | WorkflowStepHistory | `WorkflowStepHistory` | Workflow Engine | Bleibt (Runtime-Log, kein Undo) | Kein Rückbau, anderes Konzept | -| 8 | Backup | `Backup` | Backup Service | Bleibt (Disaster Recovery) | Kein Rückbau, andere Ebene | - -**Ziel-Architektur nach Konsolidierung:** - -``` -┌──────────────────────────────────────────────────┐ -│ EntityHistory (EINZIGES Undo/Restore-System) │ -│ • snapshot_before / snapshot_after / changes │ -│ • action: create | update | delete | edit | │ -│ merge | version | import | restore │ -│ • Generische restore_from_history() │ -│ • Hook-basierte Aufzeichnung für ALLE Entities │ -│ • Cascade-Restore für abhängige Entitäten │ -└────────────────────────┬─────────────────────────┘ - │ - ┌──────────────────┼──────────────────┐ - │ │ │ -┌─────┴─────┐ ┌───────┴───────┐ ┌──────┴──────┐ -│ AuditLog │ │ Workflow │ │ Backup │ -│ Compliance │ │ StepHistory │ │ Disaster │ -│ Wer/Wann/ │ │ Runtime-Status │ │ Recovery │ -│ Was/Why │ │ (Log only) │ │ (pg_dump) │ -│ Kein Undo │ │ Kein Undo │ │ Kein Entity │ -└────────────┘ └───────────────┘ └─────────────┘ - -Deprecated & Migriert: - ✗ CommMessageEdit → EntityHistory (action=edit) - ✗ AgentVersion → EntityHistory (action=version) - ✗ AutomationVersion → EntityHistory (action=version) - ✗ ContactMergeHistory → EntityHistory (action=merge) -``` - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| U-K-ANAL | **Bestandsaufnahme** — alle Verwendungen der 7 Systeme dokumentieren, Abhängigkeiten mapping | 0.5 Tage | -| U-K-COMM | **CommMessageEdit migrieren** — bestehende Edit-History in EntityHistory mit `action=edit` importieren, CommMessageEdit deprecated, Services auf EntityHistory umstellen | 1 Tag | -| U-K-AGENT | **AgentVersion migrieren** — bestehende Version-Snapshots in EntityHistory mit `action=version` importieren, AgentVersion deprecated, `restore_version()` auf `restore_from_history()` umstellen | 1 Tag | -| U-K-AUTO | **AutomationVersion migrieren** — gleiche Migration wie AgentVersion | 1 Tag | -| U-K-MERGE | **ContactMergeHistory migrieren** — Merge-Historie in EntityHistory mit `action=merge` importieren, ContactMergeHistory deprecated | 0.5 Tage | -| U-K-AUDIT | **AuditLog trennen** — AuditLog bleibt als Compliance-Trail, aber alle `log_audit()` Aufrufe die aktuell Snapshots speichern werden auf `record_history()` umgestellt. AuditLog speichert nur noch Wer/Wann/Was (keine Snapshots) | 1 Tag | -| U-K-CLEAN | **Deprecated Tables löschen** — nach erfolgreicher Migration und Verifikation: CommMessageEdit, AgentVersion, AutomationVersion, ContactMergeHistory Tables löschen (Migration + Data-Migration) | 1 Tag | -| U-K-TEST | **Migration-Tests** — sicherstellen dass alle migrierten Daten korrekt in EntityHistory liegen, Restore funktioniert, keine Datenverluste | 1 Tag | - -### 0.5.1 Generic Restore Engine - -Das Kernproblem: `restore_from_history()` ist hardcoded auf Contact. Es braucht eine generische Engine, die jede Entität wiederherstellen kann. - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| U-REG | **Entity Registry** — zentrales Mapping `entity_type → ORM Model` mit allen Core- und Plugin-Modellen | 1 Tag | -| U-GEN | **Generic restore_from_history()** — ersetzt hardcoded Contact-Logik durch generisches Model-Lookup + Field-Restore | 1 Tag | -| U-SER | **Generic serialize/deserialize** — einheitliches Snapshot-Format für alle Modelle (UUID→Objekt-Resolution, JSONB-Fields, Relations) | 1 Tag | -| U-REL | **Relation-Restore** — abhängige Entitäten (z.B. Contact→ContactPersons, Mail→Attachments) mit wiederherstellen | 1 Tag | -| U-CON | **Conflict-Detection** — prüft ob Entität zwischenzeitlich geändert wurde (optimistic locking via updated_at-Vergleich) | 0.5 Tage | -| U-CAS | **Cascade-Restore** — wenn Parent wiederhergestellt wird, alle soft-deleted Children ebenfalls wiederherstellen | 1 Tag | - -### 0.5.2 Universal History Recording - -`record_history()` muss bei JEDER CRUD-Operation auf JEDER Entität aufgerufen werden — nicht nur bei Contacts. - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| U-HOOK | **Hook-basierte History** — `do_action('entity.after_create/after_update/after_delete')` Hooks, die automatisch record_history aufrufen | 1 Tag | -| U-MW | **Middleware-Integration** — SQLAlchemy-Event-Listener (before_update/after_delete) die Snapshots erstellen | 1 Tag | -| U-CORE | **Core-Modelle** — Contact, Company: record_history in allen CRUD-Operationen (create/update/delete) | 0.5 Tage | -| U-PLUG | **Plugin-Modelle** — Mail, DMS, Tasks, Calendar, Tags, EntityLinks: record_history in allen Services | 2 Tage | -| U-WF | **Workflow-Modelle** — Workflow, WorkflowInstance: History für Definition-Änderungen und Instanz-Status | 0.5 Tage | -| U-AUDIT | **Audit-Log-Dedup** — EntityHistory und AuditLog überschneiden sich. EntityHistory = Snapshots für Undo, AuditLog = Compliance-Trail. Beide behalten, aber klar trennen. | 0.5 Tage | - -### 0.5.3 Mail Undo & Restore (Spezialfall) - -Mail ist der schwierigste Fall, weil Mails mit IMAP-Servern synchronisiert werden. Eine Löschung auf dem IMAP-Server ist nicht einfach rückgängig zu machen. - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| U-MSOFT | **Mail Soft-Delete** — Mail-Löschung in CRM setzt `deleted_at` (DB-only), NICHT IMAP-DELETE. IMAP-DELETE nur bei `?gdpr=true` oder explizitem Hard-Delete | 1 Tag | -| U-MTRASH | **IMAP Trash-Mapping** — Mail-Löschung verschiebt IMAP-Seite in Trash-Folder (nicht permanent löschen). Restore verschiebt zurück in Original-Folder | 1 Tag | -| U-MRESTORE | **Mail-Restore** — `deleted_at` zurücksetzen + IMAP-MOVE von Trash zurück in Original-Folder | 1 Tag | -| U-MSEND | **Mail-Send-Undo** — gesendete Mails können nicht ungesendet werden. Stattdessen: "Recall"-Funktion (Delete-Notification an Empfänger) oder Draft-Retention | 0.5 Tage | -| U-MATT | **Attachment-Restore** — Mail-Attachments werden auf Disk gespeichert. Restore muss prüfen ob Datei noch existiert, sonst aus IMAP neu synchronisieren | 1 Tag | -| U-MSYNC | **Sync-Conflict-Resolution** — wenn Mail zwischenzeitlich vom IMAP-Server gelöscht wurde, Restore nur DB-seitig mit Warnung | 0.5 Tage | -| U-MFOLDER | **Folder-Restore** — MailFolder-Löschung: Children-Mails werden nicht gelöscht, sondern auf "unfiled" gesetzt. Folder-Restore stellt Hierarchie wieder her | 0.5 Tage | -| U-MACC | **Account-Restore** — MailAccount-Löschung: Account wird deaktiviert (is_active=false), nicht gelöscht. Restore reaktiviert. Hard-Delete löscht Credentials + sync'd Mails | 0.5 Tage | - -### 0.5.4 DMS, Tasks, Calendar Undo & Restore - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| U-DOCS | **DMS File-Restore** — gelöschte Dateien: `deleted_at` zurücksetzen. Physische Datei auf Disk bleibt erhalten (wird erst bei Hard-Delete gelöscht) | 0.5 Tage | -| U-DFOLD | **DMS Folder-Restore** — Folder-Restore stellt auch alle Children (Files + Sub-Folders) wieder her (Cascade) | 0.5 Tage | -| U-DVER | **DMS Version-Restore** — Datei-Versionierung: alte Version kann wiederhergestellt werden (bereits vorhanden? prüfen) | 0.5 Tage | -| U-TASK | **Task-Restore** — gelöschte Tasks wiederherstellen mit allen abhängigen Subtasks | 0.5 Tage | -| U-CAL | **Calendar-Event-Restore** — gelöschte Events wiederherstellen. ICS-Sync: Restore muss prüfen ob Event auf externem Kalender noch existiert | 1 Tag | -| U-CREC | **Calendar-Recurring-Restore** — wiederkehrende Events: einzelne Ausnahme-Events vs. Serie wiederherstellen | 0.5 Tage | - -### 0.5.5 Bulk Undo & Batch Operations - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| U-BULK | **Bulk-Undo** — mehrere Entitäten gleichzeitig wiederherstellen (z.B. alle Kontakte die in den letzten 10 Minuten gelöscht wurden) | 1 Tag | -| U-BATCH | **Batch-History** — eine Aktion (z.B. Import von 100 Kontakten) als eine History-Gruppe speichern, Undo stellt alle 100 wieder her | 1 Tag | -| U-IMPEXP | **Import-Undo** — kompletten Import rückgängig machen (alle importierten Entitäten löschen, alle geänderten reverten) | 1 Tag | -| U-MERGE | **Merge-Undo** — Contact-Merge rückgängig machen (merged Contact wiederherstellen, Duplicate-Contact reaktivieren) | 1 Tag | - -### 0.5.6 Undo UI - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| U-TOAST | **Undo-Toast** — nach jeder Aktion erscheint ein Toast "Gelöscht — Undo?" für 5 Sekunden (wie Gmail) | 1 Tag | -| U-HIST | **History-Panel** — Timeline-View pro Entität mit allen Änderungen, Diff-View, Restore-Button pro Eintrag | 2 Tage | -| U-TRASH | **Trash-View** — globale Papierkorb-Ansicht: alle gelöschten Entitäten nach Typ filterbar, Multi-Select-Restore | 1 Tag | -| U-CONF | **Restore-Confirmation** — Modal mit Diff-Preview vor Restore: "Diese Aktion wird folgende Felder zurücksetzen: ..." | 0.5 Tage | -| U-LOG | **Undo-Log** — Audit-Trail aller Undo-Operationen (wer hat was wann wiederhergestellt) | 0.5 Tage | - -### 0.5.7 Retention & Cleanup - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| U-RET | **Retention-Policy** — EntityHistory-Einträge älter als X Tage werden archiviert/gelöscht (konfigurierbar, default 90 Tage) | 0.5 Tage | -| U-GDPR | **GDPR-Hard-Delete** — `?gdpr=true` löscht Entität + History + Snapshots unwiderruflich (DSGVO-Recht auf Vergessenwerden) | 0.5 Tage | -| U-SIZE | **Storage-Management** — EntityHistory kann groß werden. Partitionierung nach Monat (bereits setup_audit_partitioning.sql vorhanden) | 0.5 Tage | - -### 0.5.8 Chat & AI History/Undo - -Das KI-Chat und der Kommunikations-Chat haben aktuell KEIN Undo-System. Das ist ein systemischer Design-Fehler, nicht nur ein fehlendes Feature. - -**Current State (Code-Analyse):** - -| Modell | deleted_at | History | Undo | Restore | -|---|---|---|---|---| -| AIConversation (Copilot) | ❌ | ❌ | ❌ | ❌ | -| AIMessage (Copilot) | ❌ | ❌ | ❌ | ❌ | -| AIChatSession (Assistant) | ❌ | ❌ | ❌ | ❌ | -| AIChatMessage (Assistant) | ❌ | ❌ | ❌ | ❌ | -| AIChatAttachment | ❌ | ❌ | ❌ | ❌ | -| AIChatFolder | ❌ | ❌ | ❌ | ❌ | -| CommConversation | ✅ | ❌ | ❌ | ❌ | -| CommMessage | ✅ | 🟡 (CommMessageEdit) | ❌ | ❌ | -| CommMessageBlock | ✅ | ❌ | ❌ | ❌ | -| CommMessageAttachment | ✅ | ❌ | ❌ | ❌ | -| CommMessageReaction | ❌ | ❌ | ❌ | ❌ | -| CommParticipant | ❌ | ❌ | ❌ | ❌ | - -**Das Problem:** Eine gelöschte Chat-Nachricht, ein gelöschter Chat-Verlauf, eine gelöschte AI-Konversation — all das ist aktuell unwiederbringlich verloren. CommMessageEdit speichert zwar alte Versionen, aber es gibt keinen Restore-Mechanismus. - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| U-AI-DEL | **AI Chat Soft-Delete** — `deleted_at` auf AIChatSession, AIChatMessage, AIConversation, AIMessage hinzufügen. Löschung setzt deleted_at, nicht hard-delete | 1 Tag | -| U-AI-HIST | **AI Chat History** — record_history() für AIChatMessage (edit/delete), AIChatSession (rename/delete), AIConversation (delete) | 1 Tag | -| U-AI-RESTORE | **AI Chat Restore** — gelöschte Chat-Sessions wiederherstellen mit allen Messages, Attachments, Tool-Results | 1 Tag | -| U-AI-EDIT | **AI Message Edit** — AIChatMessage editieren (z.B. System-Prompt nachträglich ändern), alte Version in History speichern | 0.5 Tage | -| U-AI-UNDO | **AI Action Undo** — wenn AI eine Aktion ausgeführt hat (proposed_actions → executed_action), Undo stellt den Entity-Zustand vor der Aktion wieder her (nutzt EntityHistory) | 1 Tag | -| U-COM-RESTORE | **CommMessage Restore** — gelöschte Nachrichten wiederherstellen (deleted_at zurücksetzen + Blocks/Attachments/Reactions wiederherstellen) | 1 Tag | -| U-COM-EDIT-RESTORE | **CommMessageEdit Restore** — CommMessageEdit hat bereits alte Versionen. Restore-Endpoint implementieren der alte Version wiederherstellt | 0.5 Tage | -| U-COM-CONV-RESTORE | **CommConversation Restore** — gelöschte Konversationen wiederherstellen mit allen Messages, Participants, Pinned-Items | 1 Tag | -| U-COM-REACT | **CommMessageReaction Undo** — Reactions haben kein deleted_at. Soft-Delete + Restore hinzufügen | 0.5 Tage | -| U-COM-PART | **CommParticipant Restore** — Participant hat left_at. "Re-Join" = left_at zurücksetzen. History für Role-Changes | 0.5 Tage | -| U-CHAT-UI | **Chat Undo UI** — "Nachricht löschen — Undo?" Toast, "Konversation wiederherstellen" in Trash-View, Edit-History-Dropdown pro Nachricht | 1.5 Tage | - -**Deliverables:** Vollständiges Undo/Restore-System für alle Entitäten (Core + Plugins + AI Chat + Kommunikation), generische Restore-Engine, Mail-spezifische IMAP-Trash-Logik, Chat-History/Undo, Bulk-Undo, Trash-View UI, Undo-Toast, Retention-Policies. - ---- - -## Phase 0.7 — System-Konsolidierung - -**Dauer:** 5 Wochen -**Ziel:** Alle verbleibenden fragmentierten Systeme vereinheitlichen — Attachments, LLM Clients, WebSocket Managers, Redis Connections, Event/Notification, File Upload. Mit Rechte-System für Files. Alle abhängigen Plugins und Code werden mit aktualisiert. -**Begründung:** Genau wie bei History und Search gibt es 6 weitere Bereiche mit fragmentierter Implementierung. Jeder Bereich hat mehrere eigene Modelle, eigene Logik, eigene Endpoints. Das muss vereinheitlicht werden bevor Feature-Phasen gebaut werden. - -### 0.7.1 Unified Attachment System - -Aktuell: 6 verschiedene Attachment-Modelle (Attachment, EntityAttachment, DMS File, MailAttachment, CommMessageAttachment, AIChatAttachment) mit eigener Storage-Logik, eigenen Upload-Endpoints, eigenen Schemas. - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| C-ATT-MODEL | **Unified Attachment Model** — ein generisches Attachment-Model das alle Typen abdeckt: `entity_type` (contact, mail, dms, chat, ai_chat, comm_message), `entity_id`, `filename`, `mime_type`, `size_bytes`, `storage_path`, `metadata` | 1 Tag | -| C-ATT-STORAGE | **Unified Storage Layer** — ein Storage-Backend für alle Files: `core/storage.py` erweitern mit `save_attachment()`, `get_attachment()`, `delete_attachment()`, `get_attachment_url()`. Path-Traversal-Schutz, MIME-Validation, Size-Limits | 1 Tag | -| C-ATT-PERM | **File Permissions** — Rechte-System für Files: `file:read`, `file:write`, `file:delete` Permissions. Entity-Level: wer das Parent-Entity lesen kann, darf auch das Attachment lesen. Owner-Level: Owner darf eigene Attachments verwalten. **Permissions Plugin (`plugins/builtins/permissions/`) wird deprecated** — eigenes `Permission` Model (`permissions` Table) wird migriert zu `EntityPermission` mit `entity_type='attachment'`. ShareLink wird zu Core-Model oder EntityAttachment-Metadata | 1.5 Tage | -| C-ATT-UP | **Unified Upload Endpoint** — `POST /api/v1/attachments` mit `entity_type` + `entity_id` Parameter. Alle 6 alten Endpoints werden deprecated und leiten auf diesen um | 1 Tag | -| C-ATT-DOWN | **Unified Download Endpoint** — `GET /api/v1/attachments/{id}` mit Permission-Check + Signed-URL-Support | 0.5 Tage | -| C-ATT-MIGRATE | **Migration** — bestehende Attachments aus DMS File, MailAttachment, CommMessageAttachment, AIChatAttachment in neues Unified Attachment Model migrieren. Alte Tables behalten als Views für Übergang | 2 Tage | -| C-ATT-PLUGIN | **Plugin-Integration** — alle Plugins (Mail, DMS, Kommunikation, AI Assistant) auf Unified Attachment umstellen. Eigene Attachment-Models werden deprecated | 2 Tage | -| C-ATT-UI | **Attachment UI** — einheitliche Upload-Komponente, Attachment-Liste pro Entity, Preview (Image/PDF/Office), Download-Button | 1 Tag | - -### 0.7.2 Unified LLM Client - -Aktuell: 7+ Stellen rufen LiteLLM direkt auf, jede mit eigener Provider-Logik, eigenem API-Key-Lookup, eigener Error-Handling. `llm_client.py` existiert aber wird nicht überall genutzt. - -**Prinzip:** LiteLLM ist der zentrale LLM-Manager. Alle KI-Komponenten nutzen denselben Client, denselben Provider-Lookup, dieselbe Error-Handling. Model-Auswahl überall möglich. - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| C-LLM-CORE | **Zentraler LLM Client** — `app/ai/llm_client.py` erweitern zur einzigen Anlaufstelle: `llm_complete(model, messages, tools, ...)`, `llm_embed(texts, model)`. Provider-Lookup aus DB (AIProvider), Fallback auf ENV | 1.5 Tage | -| C-LLM-MODEL | **Model-Auswahl** — überall wo ein LLM gebraucht wird, kann ein Model aus dem AIProvider/AIModel-System ausgewählt werden. Default-Model pro Use-Case konfigurierbar (Copilot, Proactive, Search, Agent) | 1 Tag | -| C-LLM-ERR | **Unified Error-Handling** — einheitliche Error-Handling für alle LLM-Calls: Retry (3x mit Backoff), Fallback-Model, Rate-Limit-Handling, Timeout | 1 Tag | -| C-LLM-COST | **Cost-Tracking** — jeder LLM-Call loggt Token-Count + Cost. Unified Cost-Tracking in `ai_cost_log` Table | 0.5 Tage | -| C-LLM-MIGRATE | **Migration** — alle 7+ direkten `litellm.acompletion()` Aufrufe umstellen auf `llm_client.llm_complete()`: ai_assistant, ai_proactive, unified_search, automation, ai_copilot | 2 Tage | -| C-LLM-STREAM | **Unified Streaming** — einheitliches SSE-Streaming für alle LLM-Calls (Chat, Agent, Copilot) | 1 Tag | -| C-LLM-PLUGIN | **Plugin-Dev-Guide** — wie Plugins LLM-Calls machen: `from app.ai.llm_client import llm_complete`. Keine direkten LiteLLM-Aufrufe | 0.5 Tage | - -### 0.7.3 Unified WebSocket Manager - -Aktuell: 2 separate WebSocket-Manager (Kommunikation, AI UI Control) ohne gemeinsame Basis, ohne gemeinsame Auth-Prüfung. - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| C-WS-BASE | **Base WebSocket Manager** — `core/websocket_manager.py` mit gemeinsamer Basis: Connection-Verwaltung, Auth-Prüfung (Session-Cookie + Origin-Check), Broadcast, Room-Management, Heartbeat | 1.5 Tage | -| C-WS-AUTH | **WebSocket Auth** — Session-Verifikation vor `websocket.accept()`, Origin-Header-Check gegen CORS-Whitelist, CSRF-Schutz | 1 Tag | -| C-WS-PERM | **WebSocket Permissions** — Permission-Check pro Message-Type: wer darf welche Messages senden/empfangen. RBAC wird pro WS-Message geprüft | 1 Tag | -| C-WS-MIGRATE | **Migration** — Kommunikation WebSocketManager und AIUIControlWSManager auf Basis-Klasse umstellen | 1 Tag | -| C-WS-PLUGIN | **Plugin-Dev-Guide** — wie Plugins WebSocket-Endpoints erstellen: erben von BaseWebSocketManager, registrieren Message-Handlers | 0.5 Tage | - -### 0.7.4 Unified Redis Connection - -Aktuell: 4 verschiedene Wege Redis-Verbindungen zu erstellen (Singleton, Cache, Middleware pro Request, Monitoring). - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| C-RED-SINGLE | **Single Redis Pool** — `core/redis.py` als einzige Anlaufstelle: `get_redis()` gibt Singleton-Pool zurück. Alle anderen Module importieren von hier | 0.5 Tage | -| C-RED-MIGRATE | **Migration** — `core/cache.py`, `core/middleware.py`, `core/monitoring.py`, `core/auth.py` auf `get_redis()` umstellen. Per-Request-Connection-Erstellung entfernen | 1 Tag | -| C-RED-POOL | **Connection Pool Config** — konfigurierbare Pool-Size, Timeout, Retry. Health-Check für Pool | 0.5 Tage | -| C-RED-TEST | **Tests** — sicherstellen dass keine Connection-Leaks mehr auftreten unter Last | 0.5 Tage | - -### 0.7.5 Unified Event/Notification System - -Aktuell: 4 Mechanismen (EventBus, HookRegistry, EventOutbox, WebhookDispatcher) die teilweise dasselbe tun. - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| C-EVT-CONCEPT | **Klar definierte Rollen** — EventBus = in-process ephemeral (cache invalidation, UI updates), HookRegistry = data modification (before/after create/update/delete), EventOutbox = durable domain events (contact.created, mail.received), WebhookDispatcher = external HTTP delivery | 0.5 Tage | -| C-EVT-DOC | **Decision Guide** — Dokumentation wann welches System zu nutzen ist. Flow-Chart für Plugin-Entwickler | 0.5 Tage | -| C-EVT-CLEANUP | **Bereinigung** — doppelte Handler entfernen, klare Trennung. EventBus-Handler die eigentlich Hooks sein sollten umstellen | 1 Tag | -| C-EVT-NOTIF | **Unified Notification Service** — `core/notifications.py` als einzige Notification-API. Alle Plugins nutzen `create_notification()`. Notification-Types aus Plugin-Manifest registrierbar | 1 Tag | -| C-EVT-PLUGIN | **Plugin-Dev-Guide** — wann EventBus vs Hooks vs Outbox vs Webhooks. Klare Regeln | 0.5 Tage | - -### 0.7.6 Unified File Upload - -Aktuell: 6 verschiedene Upload-Endpoints mit unterschiedlicher Logik, Validierung, Storage-Verhalten. - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| C-UP-VALID | **Unified Validation** — Path-Traversal-Schutz, MIME-Type-Whitelist, File-Size-Limit, Content-Type-Check. In `core/storage.py` zentral | 1 Tag | -| C-UP-ENDPOINT | **Unified Upload Endpoint** — `POST /api/v1/attachments` (aus 0.7.1) als einziger Upload-Endpoint. Alle alten Endpoints deprecated | 0.5 Tage | -| C-UP-MIGRATE | **Migration** — alle 6 alten Upload-Endpoints (attachments, dms, mail, kommunikation, ai_assistant, plugins) auf Unified Endpoint umstellen | 1.5 Tage | -| C-UP-PERM | **Upload Permissions** — `file:upload` Permission + Entity-Level-Check (kann User zu diesem Entity etwas hochladen?) | 0.5 Tage | -| C-UP-PLUGIN | **Plugin-Dev-Guide** — wie Plugins File-Upload implementieren: nutzen `core/storage.py`, keinen eigenen Upload-Endpoint | 0.5 Tage | - -### 0.7.7 Plugin-Dev-Guide: System-Konventionen - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| C-PD-ALL | **Unified Plugin-Dev-Guide** — `docs/plugin-development-guide.md` erweitern mit: Attachments (0.7.1), LLM (0.7.2), WebSocket (0.7.3), Redis (0.7.4), Events (0.7.5), File Upload (0.7.6). Klare DOs und DON'Ts | 1 Tag | -| C-PD-MANIFEST | **Manifest-Erweiterung** — `attachment_config`, `llm_config`, `websocket_config`, `event_config` Felder in PluginManifest | 0.5 Tage | -| C-PD-TEST | **Plugin-Dev-Tests** — Test-Suite die prüft ob ein Plugin alle Konventionen einhält (keine direkten LiteLLM-Calls, keine eigenen Attachment-Models, keine eigenen WS-Managers, etc.) | 1 Tag | - -### 0.7.8 Unified Import/Export - -Aktuell: Import/Export ist hardcoded auf Contacts/Companies (CSV). Calendar hat ICS-Import/Export. Alle anderen Entitäten (Mail, Tasks, DMS, AI Chat, Workflows, Agenten) haben gar kein Import/Export. - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| C-IE-FRAME | **Generic Import/Export Framework** — `core/import_export.py` mit generischer API: `export_entities(entity_type, filters, format)` → CSV/JSON/XLSX, `import_entities(entity_type, data, dry_run)` → Preview + Import. Entity Registry liefert Felder-Mapping | 2 Tage | -| C-IE-CONTACT | **Contact/Company** — bestehenden CSV-Import/Export auf generisches Framework umstellen | 0.5 Tage | -| C-IE-MAIL | **Mail Export** — Mails als EML/PST/CSV exportieren (Subject, From, To, Date, Body). Import aus EML/CSV | 1 Tag | -| C-IE-TASKS | **Tasks Import/Export** — CSV/JSON Import/Export für Tasks (Title, Description, Status, Due-Date, Assignee) | 0.5 Tage | -| C-IE-CAL | **Calendar ICS** — bestehenden ICS-Import/Export auf generisches Framework umstellen | 0.5 Tage | -| C-IE-DMS | **DMS Export** — Datei-Metadaten als CSV/JSON exportieren. Bulk-Download als ZIP | 0.5 Tage | -| C-IE-CHAT | **AI Chat Export** — Chat-Verläufe als JSON/Markdown exportieren (für Backup, Archivierung, DSGVO-Auskunft) | 0.5 Tage | -| C-IE-WF | **Workflow Export** — Workflow-Definitionen als JSON exportieren/importieren (für Template-Sharing) | 0.5 Tage | -| C-IE-AGENT | **Agent Export** — Agent-Definitionen als JSON exportieren/importieren | 0.5 Tage | -| C-IE-UI | **Import/Export UI** — einheitliche UI: Entity-Typ auswählen, Format wählen, Filter setzen, Preview, Download/Upload | 1.5 Tage | -| C-IE-PERM | **Permission-Aware Export** — Export respektiert Visibility-Filter (nur sichtbare Entities). Import respektiert Permissions (nur mit write-Permission) | 0.5 Tage | -| C-IE-PLUGIN | **Plugin-Dev-Guide** — wie Plugins Import/Export implementieren: Entity Registry registrieren, Felder-Mapping definieren | 0.5 Tage | - -### 0.7.9 Error Handling & Custom Fields Bereinigung - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| C-ERR-REDIS | **Error Rate-Limiter auf Redis** — in-memory Rate-Limiter in `routes/errors.py` durch Redis-basierten `check_rate_limit()` ersetzen (Security Risk H-7) | 0.5 Tage | -| C-CF-PLUGIN | **Custom Fields für Plugins** — `custom_field_definition` und `custom_field_service` erweitern sodass Plugin-Entities (Mail, DMS, Tasks, Calendar) Custom Fields nutzen können. Entity Registry muss Plugin-Entities unterstützen | 1.5 Tage | -| C-CF-UI | **Custom Fields UI für Plugins** — Plugin-Detail-Seiten zeigen Custom Fields an, Editor zum Definieren | 1 Tag | - -### 0.7.10 Plugin-Specification & Contract - -Plugins brauchen klare, exakte Vorgaben was sie mitbringen müssen, wie sie funktionieren, und wie sie sich an alle Systeme anbinden. Dies wird die definitive Plugin-Bauanleitung. - -**Grundprinzip:** Jedes Plugin ist ein vollständiger Modul-Baustein der sich nahtlos in die Plattform integriert — mit History, Search, Permissions, LLM, Tools, Events, UI. Ein Plugin ist nicht nur "Routes + Model" — es ist ein vollständiger Bürger der Plattform. - -#### Was jedes Plugin MITBRINGEN MUSS (Pflicht) - -| # | Vorgabe | Beschreibung | -|---|---|---| -| 1 | **PluginManifest** | Vollständiges Manifest mit name, version, display_name, description, dependencies, permissions, routes, events, hooks, contract_version | -| 2 | **BasePlugin** | Erbt von `BasePlugin`, implementiert `on_activate()` und `on_deactivate()` | -| 3 | **ORM Models** | Alle Models erben von `Base, TenantMixin` (tenant_id Pflicht), haben `deleted_at` (Soft-Delete Pflicht), `created_at`, `updated_at`, `created_by`, `updated_by` | -| 4 | **Entity Registry** | Alle Entitäten in zentraler Entity Registry registrieren: `register_entity("my_entity", MyModel)` | -| 5 | **History/Undo** | Hooks registrieren für automatische History-Aufzeichnung: `register_action("my_entity.after_create/after_update/after_delete")` | -| 6 | **Search Provider** | SearchProvider registrieren für jede durchsuchbare Entität: `register_search_provider(MyEntitySearchProvider)` | -| 7 | **Permissions** | Plugin-Permissions im Manifest deklarieren: `permissions=["my_plugin:read", "my_plugin:write"]`. Permission-Registry wird automatisch aktualisiert | -| 8 | **Migrations** | SQL-Migrations in `migrations/` Ordner, alle Tables müssen `tenant_id` haben, MigrationRunner validiert | -| 9 | **Schemas** | Pydantic Schemas: `Create`, `Update`, `Read` für jede Entität | -| 10 | **Routes** | APIRouter mit korrektem Prefix (`/api/v1/plugin-`), alle Routes mit `require_permission()` geschützt | -| 11 | **Contracts** | Plugin-Contract registrieren für Cross-Plugin-Kommunikation: `get_contract_registry().register("my_plugin", MyPluginContract())` | -| 12 | **Audit Log** | Alle Mutationen erstellen AuditLog-Einträge via `log_audit()` | - -#### Was ein Plugin KANN (Optional aber empfohlen) - -| # | Feature | Wie | -|---|---|---| -| 13 | **AI Tools** | Tools in ToolRegistry registrieren: `register_tool(name, description, parameters, handler, required_permission)`. Agenten können diese Tools nutzen | -| 14 | **LLM Integration** | LLM-Calls über zentralen Client: `from app.ai.llm_client import llm_complete`. NIE direkte `litellm.acompletion()` Aufrufe | -| 15 | **MCP Tools** | Plugin-Features als MCP-Tools exposed: `register_mcp_tool(name, description, handler)`. Externe KI-Systeme können zugreifen | -| 16 | **Event Bus** | Events subscribieren: `event_bus.subscribe("contact.created", handler)`. Events publishen: `await event_bus.publish("my_plugin.thing_happened", payload)` | -| 17 | **Hooks** | Actions registrieren: `register_action("contact.before_create", handler)`. Filters registrieren: `register_filter("contact.format_name", handler)` | -| 18 | **Outbox Events** | Durable Domain Events: `enqueue_outbox_event(db, tenant_id, "my_plugin.entity_created", {...})`. Werden zuverlässig zugestellt | -| 19 | **Webhooks** | Plugin kann Webhook-Subscriptions anbieten: Events im Manifest deklarieren, WebhookDispatcher liefert automatisch | -| 20 | **Frontend UI** | FrontendMenuItem, FrontendPageRoute, FrontendDetailTab, FrontendSettingsPage, FrontendDashboardWidget im Manifest deklarieren | -| 21 | **Custom Fields** | Plugin-Entities können Custom Fields nutzen: Entity in CustomField-Registry registrieren | -| 22 | **Import/Export** | Import/Export-Mapping im Plugin definieren: Felder-Mapping für generisches Import/Export-System | -| 23 | **WebSocket** | WebSocket-Endpoint über BaseWebSocketManager: erben, Message-Handlers registrieren | -| 24 | **Attachments** | Unified Attachment System nutzen: `save_attachment(entity_type, entity_id, file)`. KEINE eigenen Attachment-Models | -| 25 | **Agent Definitions** | AgentDefinitionContribution im Manifest: Plugin kann autonome Agenten definieren | -| 26 | **Automation Templates** | AutomationTemplateContribution im Manifest: Plugin kann Workflow-Templates beisteuern | -| 27 | **Cron Jobs** | CronJobContribution im Manifest: Plugin kann geplante Jobs definieren | -| 28 | **Dashboard Widgets** | FrontendDashboardWidget im Manifest: Plugin kann Dashboard-Kacheln beisteuern | -| 29 | **Notification Types** | `get_notification_types()` überschreiben: Plugin-spezifische Notification-Types registrieren | -| 30 | **Field Definitions** | FieldDefinitions im Manifest: Plugin kann sensitive Felder deklarieren für Field-Level-Permissions | - -#### Was ein Plugin NICHT DARF (Verboten) - -| # | Verbot | Warum | -|---|---|---| -| ❌ 1 | Eigene History-Tabellen | EntityHistory ist das einzige Undo-System | -| ❌ 2 | Eigene Version-Tabellen | EntityHistory mit `action=version` nutzen | -| ❌ 3 | Eigene Search-Systeme | Unified Search Provider nutzen | -| ❌ 4 | Eigene Attachment-Models | Unified Attachment System nutzen | -| ❌ 5 | Direkte `litellm.acompletion()` Aufrufe | Zentralen `llm_client.llm_complete()` nutzen | -| ❌ 6 | Eigene WebSocket-Manager | BaseWebSocketManager erben | -| ❌ 7 | Eigene Redis-Verbindungen | `get_redis()` aus `core/redis.py` nutzen | -| ❌ 8 | Eigene File-Upload-Endpoints | `POST /api/v1/attachments` nutzen | -| ❌ 9 | Eigene Import/Export-Logik | Generisches Import/Export-Framework nutzen | -| ❌ 10 | `log_audit()` für Snapshots | AuditLog = Compliance, EntityHistory = Snapshots | -| ❌ 11 | Hard-Delete ohne `?gdpr=true` | Soft-Delete ist Default, Hard-Delete nur mit GDPR-Flag | -| ❌ 12 | Plugin-Tables ohne `tenant_id` | MigrationRunner validiert, aber Pflicht | -| ❌ 13 | Sync I/O in Routes | Async-first: `async def`, asyncpg, aiofiles | -| ❌ 14 | Plaintext Passwörter | bcrypt cost=12 | -| ❌ 15 | JWT Auth | Session-based mit HttpOnly cookies | -| ❌ 16 | Raw SQL ohne tenant_id check | ORM mit auto-filter nutzen | -| ❌ 17 | Server-side HTML rendering | API-only backend, React SPA frontend | -| ❌ 18 | Integer IDs | UUID only | -| ❌ 19 | Naive datetime | TIMESTAMPTZ only | -| ❌ 20 | Class components (Frontend) | Functional components only | - -#### Plugin-Manifest-Vollständigkeit - -Das Plugin-Manifest wird erweitert um alle neuen Config-Felder: - -```python -class PluginManifest(BaseModel): - # Bestehend - name: str - version: str - display_name: str - description: str - dependencies: list[str] - routes: list[PluginRouteDef] - events: list[str] - hooks: list[str] - permissions: list[str] - is_core: bool - author: str - min_app_version: str - contract_version: str - migrations: list[str] - field_definitions: list[FieldDefinition] - # Frontend - frontend_menu_items: list[FrontendMenuItem] - frontend_page_routes: list[FrontendPageRoute] - frontend_detail_tabs: list[FrontendDetailTab] - frontend_settings_pages: list[FrontendSettingsPage] - frontend_dashboard_widgets: list[FrontendDashboardWidget] - # AI / Agenten - agent_definitions: list[AgentDefinitionContribution] - automation_templates: list[AutomationTemplateContribution] - cron_jobs: list[CronJobContribution] - heartbeat_configs: list[HeartbeatConfigContribution] - # NEU: System-Integration - history_config: HistoryConfig # Welche Entitäten History/Undo haben - search_config: SearchConfig # Welche Entitäten durchsuchbar sind - attachment_config: AttachmentConfig # Welche Entitäten Attachments haben - llm_config: LLMConfig # Welche LLM-Modelle/Use-Cases das Plugin nutzt - websocket_config: WebSocketConfig # WebSocket-Endpoints - event_config: EventConfig # Welche Outbox-Events das Plugin publishen - import_export_config: ImportExportConfig # Import/Export-Mappings - custom_field_config: CustomFieldConfig # Welche Entitäten Custom Fields unterstützen - mcp_config: MCPConfig # Welche Features als MCP-Tools exposed werden - -class HistoryConfig(BaseModel): - entities: list[str] = [] - custom_restore_handlers: bool = False - cascade_dependencies: list[dict] = [] - retention_days: int = 90 - -class SearchConfig(BaseModel): - entities: list[str] = [] - fts_columns: dict[str, str] = {} # entity_type -> tsv_column - embedding_columns: dict[str, str] = {} # entity_type -> embedding_column - auto_index: bool = True - -class AttachmentConfig(BaseModel): - entities: list[str] = [] # entity_types that can have attachments - allowed_mime_types: list[str] = [] - max_file_size_mb: int = 25 - -class LLMConfig(BaseModel): - use_cases: list[str] = [] # e.g. ["chat", "proactive", "search", "agent"] - default_model: str | None = None - tools: list[dict] = [] # AI tools the plugin registers - -class WebSocketConfig(BaseModel): - endpoints: list[dict] = [] # [{path, message_types, auth_required}] - -class EventConfig(BaseModel): - publishes: list[str] = [] # outbox events the plugin publishes - subscribes: list[str] = [] # events the plugin subscribes to - -class ImportExportConfig(BaseModel): - entities: list[dict] = [] # [{entity_type, fields, required_fields, formats}] - -class CustomFieldConfig(BaseModel): - entities: list[str] = [] # entity_types that support custom fields - -class MCPConfig(BaseModel): - tools: list[dict] = [] # [{name, description, handler_ref}] -``` - -#### Plugin-Lifecycle (vollständig) - -``` -1. Discovery — PluginRegistry.discover_builtins() findet Plugin -2. Install — MigrationRunner läuft, on_install() wird aufgerufen -3. Activate — on_activate(): Entity Registry, Search Providers, Hooks, Tools, Contracts registrieren -4. Running — Plugin verarbeitet Requests, Events, Tool-Calls, Background-Jobs -5. Deactivate — on_deactivate(): alle Registrierungen entfernen -6. Uninstall — on_uninstall(): Cleanup, MigrationRunner droppt Tables -``` - -#### Plugin-Validation (automatisiert) - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| C-PS-VALIDATOR | **Plugin-Validator** — automatisierte Prüfung beim Installieren: Manifest vollständig? Alle Pflicht-Felder vorhanden? Models haben tenant_id + deleted_at? Migrations validiert? Permissions deklariert? | 1.5 Tage | -| C-PS-TESTS | **Plugin-Test-Suite** — Tests die jedes Plugin durchlaufen muss: History funktioniert? Search funktioniert? Permissions korrekt? Undo/Restore funktioniert? | 1.5 Tage | -| C-PS-DOCS | **Plugin-Dev-Guide** — `docs/plugin-development-guide.md` komplett überarbeiten mit allen Vorgaben, DOs, DON'Ts, Code-Beispielen | 2 Tage | -| C-PS-EXAMPLE | **Referenz-Plugin** — vollständiges Beispiel-Plugin das ALLE Features korrekt implementiert (History, Search, Tools, LLM, MCP, Events, Attachments, Import/Export, Custom Fields) | 2 Tage | -| C-PS-MANIFEST | **Manifest-Erweiterung** — alle neuen Config-Felder (HistoryConfig, SearchConfig, AttachmentConfig, LLMConfig, etc.) in PluginManifest implementieren | 1.5 Tage | -| C-PS-CHECK | **Cross-Plugin-Import-Checker** — prüft ob Plugins direkte Imports von anderen Plugin-Internals haben (statt Contracts zu nutzen) | 0.5 Tage | - -### 0.7.11 Plugin Public Web Content (Subdomain & Unterordner) - -Plugins sollen eigene Web-Inhalte öffentlich zur Verfügung stellen können — über Subdomain (`forms.crm.media-on.de`) oder Unterordner (`crm.media-on.de/public/forms/{id}`). Aktuell gibt es nur `is_public` für API-Routes (ohne Auth), aber keinen Mechanismus für öffentliche Web-Seiten, statische Files, oder Subdomain-Routing. - -**Use-Cases:** -- Formular-Plugin: öffentliche Formulare unter `forms.crm.media-on.de/{form_id}` oder `crm.media-on.de/public/forms/{form_id}` -- Booking-Plugin: öffentliche Terminbuchung unter `book.crm.media-on.de` -- Survey-Plugin: öffentliche Umfragen -- Landing-Page-Plugin: öffentliche Landing-Pages -- Portal-Plugin: Kunden-Portal mit Login-Page -- Newsletter-Plugin: öffentliche Anmeldeseite - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| C-PW-SUB | **Subdomain-Routing** — FastAPI Host-Middleware die Subdomain extrahiert und an Plugin-Router weiterleitet. `forms.crm.media-on.de` → Form-Plugin. Konfigurierbares Subdomain-Mapping pro Plugin im Manifest | 2 Tage | -| C-PW-PATH | **Unterordner-Routing** — `/public/{plugin_name}/...` Prefix für öffentliche Plugin-Web-Inhalte. Keine Auth, keine CSRF, aber Rate-Limiting | 1 Tag | -| C-PW-STATIC | **Static File Serving** — Plugins können statische Files (HTML, CSS, JS, Images) in `public/` Ordner ablegen. FastAPI StaticFiles mount pro Plugin | 1 Tag | -| C-PW-DYN | **Dynamic Pages** — Plugins können dynamische Web-Seiten generieren (Jinja2-Template-Engine, server-side rendering NUR für öffentliche Seiten — nicht für CRM-UI). Template-Registry pro Plugin | 2 Tage | -| C-PW-MANIFEST | **Manifest-Erweiterung** — `public_web_config` Feld: `subdomain: str` (z.B. 'forms'), `path_prefix: str` (z.B. '/public/forms'), `static_dir: str` (z.B. 'public/'), `templates: list[dict]` | 1 Tag | -| C-PW-PROXY | **Reverse-Proxy Config** — nginx/Coolify Konfiguration für Subdomain-Routing. Wildcard-DNS (*.crm.media-on.de) oder explizite Subdomain-Einträge pro Plugin | 1 Tag | -| C-PW-RATE | **Public Rate-Limiting** — öffentliche Seiten brauchen eigenes Rate-Limiting (Redis-basiert, pro IP, höher als auth-Routes). Anti-Abuse-Schutz | 1 Tag | -| C-PW-CORS | **Public CORS** — öffentliche Seiten brauchen eigene CORS-Regeln (keine Cookies, keine CSRF, aber CORS für externe Aufrufe) | 0.5 Tage | -| C-PW-CACHE | **Public Caching** — öffentliche Seiten cachen (Redis + HTTP Cache-Headers). CDN-kompatibel | 0.5 Tage | -| C-PW-THEME | **Theme-Integration** — öffentliche Plugin-Seiten können CRM-Theme nutzen (Farben, Fonts, Logo) oder eigenes Theme | 1 Tag | -| C-PW-FORM | **Form-Plugin (Referenz)** — Referenz-Plugin das öffentliche Formulare bereitstellt: Form-Builder im CRM, öffentliche Form-Seite unter `forms.crm.media-on.de/{form_id}`, Submit → Daten ins CRM, E-Mail-Bestätigung | 3 Tage | -| C-PW-SEC | **Security** — öffentliche Seiten dürfen KEINE CRM-Session-Cookies empfangen, KEINE CSRF-Tokens, KEINE interne API-Endpunkte. Isolierte Public-Surface | 1 Tag | -| C-PW-PLUGIN | **Plugin-Dev-Guide** — wie Plugins öffentliche Web-Inhalte erstellen: Manifest deklarieren, Templates bauen, Static-Files ablegen, Subdomain konfigurieren | 0.5 Tage | - -**Deliverables:** Vereinheitlichte Systeme für Attachments (1 Model, 1 Storage, 1 Endpoint, mit Permissions), LLM (1 Client, Model-Auswahl überall, Cost-Tracking), WebSocket (1 Base-Klasse, Auth, Permissions), Redis (1 Pool, keine Leaks), Events (klare Trennung 4 Systeme, Notification-API), File Upload (1 Endpoint, 1 Validation). Alle Plugins und abhängiger Code aktualisiert. Plugin-Dev-Guide erweitert. - -### 0.5.9 Plugin-Entwickler-Leitfaden: Undo & Restore - -Nach dem Umbau müssen Plugin-Entwickler wissen, wie sie History/Undo/Restore für ihre Plugin-Entitäten implementieren. Dies wird Teil der offiziellen Plugin-Development-Guide (`docs/plugin-development-guide.md`). - -**Das Prinzip:** Plugin-Entitäten nutzen DASSELBE EntityHistory-System wie Core-Entitäten. Kein Plugin baut ein eigenes History-System. Alles läuft über die zentrale `record_history()` API und Hook-Integration. - -**Was ein Plugin tun muss (Pflicht):** - -1. **Entity Registry registrieren** — Plugin registriert seine Modelle in der zentralen Entity Registry: - ```python - # In plugin.py on_activate() - from app.core.entity_registry import register_entity - register_entity("my_plugin_entity", MyPluginModel) - ``` - -2. **Hooks nutzen** — Plugin nutzt die zentralen Hooks für automatische History-Aufzeichnung: - ```python - # In plugin.py on_activate() - from app.core.hooks import get_hook_registry - reg = get_hook_registry() - reg.register_action("my_plugin_entity.before_create", self._before_create) - reg.register_action("my_plugin_entity.after_update", self._after_update) - reg.register_action("my_plugin_entity.after_delete", self._after_delete) - # Die Hook-Handler rufen automatisch record_history() auf - ``` - -3. **Soft-Delete implementieren** — Plugin-Modelle müssen `deleted_at` haben: - ```python - class MyPluginModel(Base, TenantMixin): - deleted_at: Mapped[datetime | None] = mapped_column( - DateTime(timezone=True), nullable=True - ) - ``` - -4. **Restore-Handler (optional)** — wenn das Plugin spezielle Restore-Logik braucht (z.B. IMAP-Sync bei Mail, Disk-Files bei DMS): - ```python - # In plugin.py on_activate() - from app.core.entity_registry import register_restore_handler - async def my_restore_handler(db, entity_id, snapshot, tenant_id): - # Custom restore logic (z.B. IMAP-MOVE, Disk-File-Check) - ... - register_restore_handler("my_plugin_entity", my_restore_handler) - ``` - -5. **Cascade-Dependencies definieren** — wenn das Plugin Parent-Child-Beziehungen hat: - ```python - from app.core.entity_registry import register_cascade - register_cascade("my_plugin_parent", "my_plugin_child", fk_field="parent_id") - # Parent-Restore → alle soft-deleted Children werden mit wiederhergestellt - ``` - -**Was ein Plugin NICHT tun darf (Verboten):** - -- ❌ Eigene History-Tabellen erstellen (z.B. `MyPluginEditHistory`) -- ❌ Eigene Version-Tabellen erstellen (z.B. `MyPluginVersion`) -- ❌ Eigene Restore-Logik implementieren (stattdessen Restore-Handler registrieren) -- ❌ `log_audit()` für Snapshots nutzen (AuditLog ist nur Compliance-Trail) -- ❌ Hard-Delete ohne `?gdpr=true` Parameter - -**Plugin-Manifest-Erweiterung:** - -Das Plugin-Manifest bekommt ein neues Feld `history_config`: -```python -class PluginManifest(BaseModel): - history_config: HistoryConfig = Field(default_factory=HistoryConfig) - -class HistoryConfig(BaseModel): - entities: list[str] = Field(default_factory=list) # entity_type names - custom_restore_handlers: bool = Field(default=False) - cascade_dependencies: list[dict] = Field(default_factory=list) - retention_days: int = Field(default=90) -``` - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| U-PD-REG | **Entity Registry API** — `register_entity()`, `register_restore_handler()`, `register_cascade()` implementieren | 1 Tag | -| U-PD-HOOK | **Auto-Hook-Integration** — Hooks die automatisch record_history aufrufen für registrierte Entities | 1 Tag | -| U-PD-DOC | **Plugin-Dev-Guide Update** — `docs/plugin-development-guide.md` mit Undo/Restore-Kapitel erweitern | 1 Tag | -| U-PD-MANIFEST | **Manifest-Erweiterung** — `history_config` Feld in PluginManifest hinzufügen | 0.5 Tage | -| U-PD-EXAMPLE | **Beispiel-Plugin** — Referenz-Plugin das zeigt wie History/Undo/Restore korrekt implementiert wird | 1 Tag | -| U-PD-TEST | **Plugin-Dev-Tests** — Test-Suite die prüft ob ein Plugin die Undo/Restore-Konventionen einhält | 1 Tag | - ---- - -## Phase 0.8 — Frontend-Konsolidierung & UI-System - -**Dauer:** 5 Wochen -**Ziel:** Einheitliches UI-System mit Standard-Komponenten für Plugins, globalem Template-System (Farben, Schriftart, Größe), und Bereinigung aller Regelverletzungen (inline styles, any types, class components, hardcoded strings, dangerouslySetInnerHTML). -**Begründung:** Das Frontend ist größtenteils gut strukturiert (TanStack Query, Zustand, i18n, ARIA, ErrorBoundary), aber es gibt 6 klare Probleme: 96 inline styles, 360 any types, 3 class components, 3 dangerouslySetInnerHTML, 23 hardcoded strings, und fehlendes Plugin-UI-Loading-System. Plugins brauchen Standard-Komponenten und ein Template-System damit die UI vereinheitlich wird. - -### 0.8.1 Code-Bereinigung — Regelverletzungen entfernen - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| F-CL-INLINE | **Inline Styles entfernen** — alle 96 `style={}` durch Tailwind-Klassen ersetzen | 2 Tage | -| F-CL-ANY | **any Types entfernen** — alle 360 `: any` / `as any` durch korrekte TypeScript-Types ersetzen | 3 Tage | -| F-CL-CLASS | **Class Components entfernen** — alle 3 class components in functional components umschreiben | 0.5 Tage | -| F-CL-DANGEROUS | **dangerouslySetInnerHTML** — alle 3 Verwendungen prüfen: DOMPurify-Sanitization sicherstellen oder entfernen | 0.5 Tage | -| F-CL-STRINGS | **Hardcoded Strings** — alle 23 hardcoded Strings durch `t()` ersetzen | 1 Tag | -| F-CL-LINT | **ESLint-Strict-Config** — eslint-config auf strict setzen (no-inline-styles, no-any, no-class-components, no-dangerouslySetInnerHTML, no-hardcoded-strings). CI-Pipeline prüft automatisch | 1 Tag | -| F-CL-PWA | **PWA Service Worker** — SW ist aktuell deaktiviert (main.tsx unregister). Entweder reaktivieren mit korrektem Cache-Strategy oder PWA komplett entfernen | 0.5 Tage | -| F-CL-A11Y | **Accessibility ergänzen** — sr-only Texte für Screen-Reader ergänzen (Button-Beschreibungen, Status-Updates, ARIA-Live-Regions). Aktuell nur 4 sr-only — sollte deutlich mehr sein | 1 Tag | - -### 0.8.2 Standard-Komponenten-Bibliothek für Plugins - -Plugins sollen Standard-Komponenten nutzen können (aber nicht müssen). Diese Bibliothek stellt einheitliche UI-Bausteine zur Verfügung die das CRM-Theme automatisch nutzen. - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| F-SC-AUDIT | **Bestandsaufnahme** — alle bestehenden UI-Komponenten (`components/ui/`) und Shared-Komponenten (`components/shared/`) dokumentieren: welche gibt es, welche fehlen, welche inkonsistent sind | 1 Tag | -| F-SC-CORE | **Core-Komponenten vereinheitlichen** — Button, Input, Select, Modal, Table, Card, Badge, Avatar, Pagination, Skeleton, Toast, ConfirmDialog auf einheitliche API bringen. Props standardisieren. Varianten (primary, secondary, danger, ghost) definieren | 2 Tage | -| F-SC-FORM | **Form-Komponenten** — FormField, FormInput, FormSelect, FormCheckbox, FormRadio, FormTextarea, FormDatePicker, FormFileUpload — alle mit React Hook Form + Zod Integration, automatische Error-Anzeige, Label/Helper-Text | 2 Tage | -| F-SC-DATA | **Data-Komponenten** — DataGrid (sortierbar, filterbar, paginierbar), DataList, DataCard, DataTimeline — mit TanStack Query Integration, automatisches Loading/Error/Empty-State | 2 Tage | -| F-SC-LAYOUT | **Layout-Komponenten** — PageHeader, PageContent, Sidebar, TabBar, Breadcrumb, Toolbar — einheitliche Seitenstruktur | 1 Tag | -| F-SC-ENTITY | **Entity-Komponenten** — EntityDetailLayout (Tabs, Sidebar, Header), EntityListLayout, EntityFormLayout — Standard-Layouts für CRM-Entitäten | 1.5 Tage | -| F-SC-AI | **AI-Komponenten** — ChatBubble, ToolCallDisplay, AgentStatusBadge, SuggestionCard, AIProgressIndicator — für KI-Features | 1 Tag | -| F-SC-SEARCH | **Search-Komponenten** — SearchBar, SearchResults, SearchFacets, SearchFilters — für Unified Search | 1 Tag | -| F-SC-EXPORT | **Export-Komponenten** — ExportButton, ImportDialog, CsvPreview — für Import/Export | 0.5 Tage | -| F-SC-DOCS | **Komponenten-Dokumentation** — Storybook oder Markdown-Doku für alle Standard-Komponenten mit Props, Beispielen, Live-Preview | 2 Tage | - -### 0.8.3 Template-System (Globale Theme-Einstellungen) - -Ein Template-System das globale Einstellungen für Farben, Schriftart, Größe etc. ermöglicht — konfigurierbar über Admin-Settings, gespeichert in SystemSettings, angewendet via CSS Custom Properties. - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| F-TS-CSS | **CSS Custom Properties System** — alle Theme-Werte als CSS Custom Properties (`--color-primary`, `--color-secondary`, `--font-family`, `--font-size-base`, `--border-radius`, `--spacing-unit`, etc.). Tailwind nutzt diese Variablen | 1 Tag | -| F-TS-SETTINGS | **Theme-Settings Model** — SystemSettings erweitern mit `theme_config` JSONB: primary_color, secondary_color, accent_color, danger_color, success_color, warning_color, font_family, font_size_base, border_radius, spacing_unit, sidebar_width, content_max_width | 1 Tag | -| F-TS-ADMIN | **Admin Theme-Editor UI** — Settings-Seite mit Color-Picker, Font-Selector, Size-Slider, Live-Preview. Änderungen werden sofort angewendet (CSS-Variablen aktualisieren) | 2 Tage | -| F-TS-PRESET | **Theme-Presets** — vorgefertigte Themes (Default, Dark, Compact, Large, High-Contrast, Brand-Custom). Admin kann Preset wählen und anpassen | 1 Tag | -| F-TS-DARK | **Dark Mode Integration** — Dark Mode nutzt dieselben CSS-Variablen mit anderen Werten. Toggle in Settings + System-Preference-Detection | 1 Tag | -| F-TS-PLUGIN | **Plugin-Theme-Access** — Plugins können Theme-Werte lesen: `useTheme()` Hook gibt aktuelle Theme-Config. Standard-Komponenten nutzen Theme automatisch | 0.5 Tage | -| F-TS-PUBLIC | **Public-Page-Theme** — öffentliche Plugin-Seiten können CRM-Theme nutzen oder eigenes Theme (siehe 0.7.11) | 0.5 Tage | -| F-TS-RESP | **Responsive Breakpoints** — einheitliche Breakpoints (sm, md, lg, xl, 2xl) in Tailwind Config. Standard-Komponenten nutzen diese Breakpoints | 0.5 Tage | - -### 0.8.4 Plugin-UI-Loading-System - -Aktuell ist `frontend/src/plugins/` leer — das Plugin-UI-Loading-System fehlt oder ist woanders. Plugins müssen ihre Frontend-Komponenten (Pages, Tabs, Widgets, Settings) dynamisch laden können. - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| F-PL-REG | **Plugin-UI-Registry** — zentrale Registry die Plugin-Frontend-Komponenten verwaltet: MenuItems, PageRoutes, DetailTabs, SettingsPages, DashboardWidgets. Lädt Manifest vom Backend und registriert Komponenten | 2 Tage | -| F-PL-LOAD | **Dynamic Component Loading** — React.lazy + Suspense für Plugin-Komponenten. ErrorBoundary pro Plugin-Komponente (ein fehlerhaftes Plugin bricht nicht die ganze UI) | 1 Tag | -| F-PL-CACHE | **Component-Cache** — geladene Plugin-Komponenten cachen (nicht bei jedem Render neu laden). Cache invalidation bei Plugin-Update | 0.5 Tage | -| F-PL-SANDBOX | **Plugin-Sandbox** — Plugin-Komponenten laufen in isoliertem Context (eigener ErrorBoundary, eigener State-Scope). Plugins können Core-State lesen aber nicht direkt mutieren | 1 Tag | -| F-PL-MANIFEST | **Manifest-Driven UI** — Frontend liest Plugin-Manifest vom Backend und baut Menu/Pages/Tabs/Widgets dynamisch auf. Keine hardcoded Plugin-Imports im Frontend | 1 Tag | -| F-PL-THEME | **Plugin-Theme-Integration** — Plugin-Komponenten nutzen automatisch CRM-Theme (CSS-Variablen). Plugins können Standard-Komponenten nutzen | 0.5 Tage | -| F-PL-DEV | **Plugin-Dev-Guide (Frontend)** — wie Plugins Frontend-Komponenten erstellen: Standard-Komponenten nutzen, Manifest deklarieren, Theme respektieren, i18n nutzen | 1 Tag | - -### 0.8.5 Frontend-Regeln (verbindlich) - -Diese Regeln werden in `AGENTS.md` und `docs/ui-design-guidelines.md` als verbindlich dokumentiert und durch ESLint-Config + CI-Pipeline durchgesetzt: - -| Regel | Beschreibung | Durchsetzung | -|---|---|---| -| **Tailwind only** | Keine inline styles. Alle Styles als Tailwind-Klassen oder CSS-Variablen | ESLint: no-inline-styles | -| **TypeScript strict** | Keine `any` types. Alle Props und States haben explizite Types | ESLint: no-explicit-any | -| **Functional components only** | Keine class components. React Hooks statt Lifecycle-Methods | ESLint: no-class-components | -| **i18n for all strings** | Keine hardcoded Strings. Alle Texte via `t()` aus react-i18next | ESLint: no-hardcoded-strings | -| **ARIA on interactive elements** | Alle interaktiven Elemente haben ARIA-Attribute. 44px touch targets | ESLint: jsx-a11y | -| **TanStack Query for server state** | Server-Daten via useQuery/useMutation. Kein manuelles fetch/axios in Komponenten | Code-Review | -| **Zustand for client state only** | Keine Server-Daten in Zustand. Zustand nur für UI-State, Theme, Auth, Preferences | Code-Review | -| **React Hook Form + Zod** | Alle Forms nutzen useForm + zodResolver. Keine manuelle Form-Validierung | Code-Review | -| **Standard-Komponenten bevorzugt** | Plugins sollen Standard-Komponenten nutzen (Button, Input, Modal, etc.) wenn möglich | Code-Review | -| **Theme via CSS-Variablen** | Farben, Fonts, Größen via CSS Custom Properties. Keine hardcoded Farben in Komponenten | ESLint: no-hardcoded-colors | -| **ErrorBoundary pro Plugin** | Jedes Plugin hat eigenen ErrorBoundary. Plugin-Fehler bricht nicht die ganze UI | Code-Review | -| **dangerouslySetInnerHTML verboten** | Außer mit DOMPurify-Sanitization | ESLint: no-danger | - -**Deliverables:** Bereinigtes Frontend (0 inline styles, 0 any types, 0 class components, 0 hardcoded strings), Standard-Komponenten-Bibliothek für Plugins, globales Template-System (Farben, Schriftart, Größe konfigurierbar), Plugin-UI-Loading-System (dynamisch, manifest-driven, sandboxed), verbindliche Frontend-Regeln in AGENTS.md und ESLint-Config. +## Phase B — Kleine System-Konsolidierung **Dauer:** 4 Wochen -**Ziel:** Eine einzige vereinheitlichte Suche über ALLES — alle Entitäten, alle Such-Modi (FTS, Vector, RAG, Graph), selbstständige Hintergrund-Indexierung, KI-voll-nutzbar (Tool, MCP, API). Alle fragmentierten Such-Systeme werden konsolidiert. -**Begründung:** Genau wie bei History gibt es fragmentierte Such-Systeme. Unified Search Plugin ist gut (10 Provider, RRF Fusion, LLM Query-Understanding, pgvector), aber Mail/DMS/Tasks haben eigene ILIKE-Suchen, Agent Memory hat eigene Vector-Suche, AI-Chats/Workflows/Agenten/AuditLog sind gar nicht suchbar. Das muss vereinheitlicht werden — ein System, ein Index, eine API, für alles. +**Ziel:** Nur wirklich gemeinsame technische Infrastruktur konsolidieren. Keine Universalmodelle. -### Aktueller State +### B.1 Zentraler LLM Client -| System | Status | -|---|---| -| Unified Search Plugin | ✅ 10 Provider, RRF Fusion (FTS+Vector), LLM Query-Understanding, pgvector | -| Mail eigene Suche | ❌ Eigene ILIKE-Suche in mail/routes.py, nicht unified | -| DMS eigene Suche | ❌ Eigene ILIKE-Suche in dms/routes.py, nicht unified | -| Tasks inline search | ❌ Query-Parameter, keine Vektorsuche | -| Agent Memory Suche | ❌ Eigene pgvector-Suche, nicht unified | -| GraphRAG Suche | ✅ Schon als SearchProvider registriert | -| Kommunikation Suche | 🟡 Registriert, aber auch eigene search() Methode | -| AI Chats (Session/Message) | ❌ Gar nicht suchbar | -| AI Copilot (Conversation/Message) | ❌ Gar nicht suchbar | -| Workflows | ❌ Nicht suchbar | -| Agenten (Definitions/Runs) | ❌ Nicht suchbar | -| AuditLog | ❌ Nicht suchbar | -| EntityHistory | ❌ Nicht suchbar | -| Auto-Indexierung | ❌ Nicht vorhanden — Embeddings werden nicht automatisch aktualisiert | -| KI-Nutzbarkeit | 🟡 AI Proactive nutzt unified_search, aber kein MCP-Exposure | - -### 1.0 Konsolidierung & Rückbau - -Alle fragmentierten Such-Systeme werden in das Unified Search Plugin migriert. Nach Phase 1 gibt es nur noch **ein** Such-System. +Im Code-Audit verbleiben **8 direkte `litellm.acompletion()` Aufrufe außerhalb des zentralen Clients** (automation, ai_assistant, ai_proactive, unified_search). Diese auf den vorhandenen zentralen Client umstellen. | Task | Beschreibung | Aufwand | |------|-------------|---------| -| S-K-MAIL | **Mail-Suche migrieren** — `mail/routes.py:search_mails()` eigene ILIKE-Suche entfernen, MailSearchProvider erweitern, Mail-Routen leiten auf Unified Search um | 1 Tag | -| S-K-DMS | **DMS-Suche migrieren** — `dms/routes.py:search_files()` eigene ILIKE-Suche entfernen, FileSearchProvider erweitern, DMS-Routen leiten auf Unified Search um | 1 Tag | -| S-K-TASKS | **Tasks-Suche migrieren** — inline search-Parameter durch Unified Search ersetzen, TaskSearchProvider erweitern | 0.5 Tage | -| S-K-MEM | **Agent Memory Suche migrieren** — eigene pgvector-Suche in agent_memory/routes.py entfernen, als SearchProvider in Unified Search registrieren | 1 Tag | -| S-K-COMM | **Kommunikation Suche bereinigen** — eigene search() Methode entfernen, nur noch über SearchProvider | 0.5 Tage | -| S-K-DEPREC | **Deprecated Routes entfernen** — alle alten /search Endpoints in Mail/DMS/Tasks durch Redirect auf /api/v1/search ersetzen | 0.5 Tage | +| 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 8 verbleibenden direkten `litellm.acompletion()` Aufrufe außerhalb `llm_client.py` 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 | -### 1.1 Universal Search Providers — ALLE Entitäten +### B.2 Zentraler Redis Pool -Jede Entität im System muss suchbar sein. Neue Provider für alle fehlenden Entitäten. +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 | |------|-------------|---------| -| S-P-AI-CHAT | **AI Chat Search Provider** — AIChatSession (Titel), AIChatMessage (Content, Tool-Calls, Tool-Results) — Vektorsuche über Chat-Inhalte | 1 Tag | -| S-P-AI-COPILOT | **AI Copilot Search Provider** — AIConversation (Titel), AIMessage (Content, Proposed Actions, Execution Results) | 0.5 Tage | -| S-P-COMM | **Kommunikation Messages Provider** — CommMessage (Content, Blocks), CommConversation (Titel) — bereits registriert, prüfen/erweitern | 0.5 Tage | -| S-P-WF | **Workflow Search Provider** — Workflow (Name, Steps), WorkflowInstance (Status, Step-History) | 0.5 Tage | -| S-P-AGENT | **Agent Search Provider** — AgentDefinition (Name, System-Prompt, Tools), AgentRun (Status, Result, Cost) | 0.5 Tage | -| S-P-AUDIT | **AuditLog Search Provider** — AuditLog (Action, Entity-Type, Changes) | 0.5 Tage | -| S-P-HIST | **EntityHistory Search Provider** — EntityHistory (Action, Entity-Type, Snapshot-Fields) | 0.5 Tage | -| S-P-AUTO | **Automation Search Provider** — AutomationDefinition (Name, Trigger, Actions), AutomationRun (Status) | 0.5 Tage | -| S-P-GRAPH | **GraphRAG Provider erweitern** — EntityRelationship (Type, Source, Target, Metadata) — bereits registriert, prüfen/erweitern | 0.5 Tage | -| S-P-SETTINGS | **Settings/System Search Provider** — SystemSettings, AIProvider, AIModel, AIPreset (für Admin-Suche) | 0.5 Tage | +| 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 | -### 1.2 Selbstständige Hintergrund-Indexierung +### B.2b pgvector HNSW Optimierung -Die Suche muss sich selbst aktualisieren. Wenn eine Entität erstellt/geändert/gelöscht wird, wird automatisch re-indexiert — ohne manuellen Eingriff. +pgvector mit HNSW-Index direkt optimieren — nicht auf Phase I verschieben. Bei 100k+ Embeddings ohne Tuning wird Search langsam. | Task | Beschreibung | Aufwand | |------|-------------|---------| -| S-IX-EVT | **Event-getriebene Auto-Indexierung** — Event Bus Listener für alle CRUD-Events (entity.created, entity.updated, entity.deleted) → ARQ Re-Embedding Job | 1.5 Tage | -| S-IX-HOOK | **Hook-basierte Indexierung** — `do_action('entity.after_create/after_update/after_delete')` Hooks die Auto-Indexierung triggern (wie bei History) | 1 Tag | -| S-IX-QUEUE | **Indexierungs-Queue** — ARQ-Queue mit Prioritäten (Create/Update = normal, Delete = high), Rate-Limit (nicht DB überlasten), Batch-Verarbeitung | 1 Tag | -| S-IX-BATCH | **Batch-Reindex** — CLI-Kommando + API-Endpoint für initiale/manuelle Re-Embedding aller Entitäten (z.B. nach Model-Wechsel) | 0.5 Tage | -| S-IX-DEL | **Delete-Handling** — bei Soft-Delete: Embedding behalten aber als deleted markieren. Bei Hard-Delete (?gdpr=true): Embedding löschen | 0.5 Tage | -| S-IX-MON | **Indexierungs-Monitoring** — Stats: wie viele Entitäten indexiert, wie viele pending, letzte Indexierung, Fehler-Rate | 0.5 Tage | -| S-IX-RETRY | **Retry-Logic** — fehlgeschlagene Indexierungs-Jobs automatisch wiederholen (3x mit Backoff) | 0.5 Tage | +| 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 | -### 1.3 Multi-Mode Search — FTS + Vector + RAG + Graph +### B.3 Gemeinsamer File Storage -Die Suche muss mehrere Such-Modi unterstützen und diese fusionieren. +Gemeinsame technische Storage-Schicht für alle File-Typen. Domainmodelle (DMS File, MailAttachment, CommMessageAttachment, AIChatAttachment) bleiben separat. | Task | Beschreibung | Aufwand | |------|-------------|---------| -| S-MM-FTS | **Full-Text-Search** — PostgreSQL tsvector/tsquery für alle Entitäten (bereits vorhanden für 4, auf alle erweitern) | 1 Tag | -| S-MM-VEC | **Vector/Embedding Search** — pgvector cosine similarity für alle Entitäten (bereits vorhanden, auf alle Provider erweitern) | 1 Tag | -| S-MM-RAG | **RAG-Search** — Document-Chunk-Retrieval für DMS-Dokumente (Chunk → Embedding → Query → Top-K) — wird in Phase 4 vertieft, aber Basis hier | 1 Tag | -| S-MM-GRAPH | **Graph-Traversal Search** — GraphRAG BFS-Traversal als Such-Modus ("Zeige mir alle Kontakte die mit Firma X verbunden sind") | 1 Tag | -| S-MM-FUSE | **RRF Fusion erweitern** — Reciprocal Rank Fusion über FTS + Vector + Graph (aktuell nur FTS+Vector) | 1 Tag | -| S-MM-LLM | **LLM Query Understanding** — bereits vorhanden (Intent, Entities, Semantic Terms), erweitern für neue Entitätstypen | 0.5 Tage | -| S-MM-AGG | **LLM Result Aggregation** — bereits vorhanden (Summary, Facets, Suggestions), erweitern für neue Entitätstypen | 0.5 Tage | +| 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 | -### 1.4 KI-Nutzbarkeit — Tool, MCP, API +### B.4 WebSocket Helpers -Die Suche muss für KI-Systeme voll nutzbar sein — als internes Tool, über MCP, und über API. +Gemeinsame Helpers statt großer BaseWebSocketManager. Spezialisierte Manager bleiben. | Task | Beschreibung | Aufwand | |------|-------------|---------| -| S-KI-TOOL | **AI Tool Registry** — `unified_search` als Tool in der ToolRegistry registrieren (OpenAI Function-Calling Schema). Agenten können suchen. | 1 Tag | -| S-KI-MCP | **MCP-Server Exposure** — Suche als MCP-Tool exposed (`search`, `find_similar`, `suggest`, `reindex`). Externe KI-Systeme können über MCP suchen. | 1.5 Tage | -| S-KI-API | **Search API** — REST API für Suche (`/api/v1/search`), bereits vorhanden, erweitern mit Filter-Parametern für alle Entitätstypen | 0.5 Tage | -| S-KI-CTX | **Context-Aware Search** — Suche mit User-Kontext (Tenant, Permissions, Visibility-Filter). KI sieht nur was der User sehen darf. | 1 Tag | -| S-KI-SIM | **Find-Similar** — "Ähnliche Entitäten finden" — bereits vorhanden, erweitern auf alle Entitätstypen | 0.5 Tage | -| S-KI-SUGG | **Search Suggestions** — Auto-Complete, Query-Suggestions, "Meintest du...?" | 0.5 Tage | +| 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 | -### 1.5 Search UI +### B.5 Event-System Rollen dokumentieren + +4 Systeme bleiben, Rollen klar definieren. Keine neue Abstraktion. | Task | Beschreibung | Aufwand | |------|-------------|---------| -| S-UI-CMD | **Command Palette** (Cmd+K / Ctrl+K) — globale Suchleiste wie Raycast/Spotlight, öffnet über Tastatur, sucht über alle Entitäten | 2 Tage | -| S-UI-FAC | **Facetten-Filter** — Type (Contact, Mail, DMS, Task, Chat, Workflow, Agent, ...), Date Range, People, Tags, Tenant | 1 Tag | -| S-UI-PRE | **Result-Preview-Cards** — Entity-Icon, Snippet mit Highlight, Type-Badge, Relevance-Score | 1 Tag | -| S-UI-NAV | **Click-through** — Klick auf Result → Entity-Detail-Ansicht (oder Chat-Verlauf, Workflow-Instanz, etc.) | 0.5 Tage | -| S-UI-REC | **Recent + Saved Searches** — letzte Suchen speichern, Saved Searches mit Namen | 0.5 Tage | -| S-UI-ADV | **Advanced Search** — erweiterte Suche mit Filter-Konstruktor (Type, Date, Owner, Tags, Custom Fields) | 1 Tag | -| S-UI-STATS | **Search Stats UI** — Indexierungs-Status, Provider-Übersicht, Such-Statistiken | 0.5 Tage | +| 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 | -### 1.6 Plugin-Dev-Guide: Search - -Genau wie bei History: Plugins müssen wissen wie sie Search implementieren. +### B.6 Schema Authority definieren | Task | Beschreibung | Aufwand | |------|-------------|---------| -| S-PD-PROV | **SearchProvider API** — `register_search_provider()` für Plugins: Provider registriert entity_type, FTS-Column, Embedding-Column, get_embedding_text() | 1 Tag | -| S-PD-AUTO | **Auto-Registration** — Plugin-Manifest `search_config` Feld: Plugins deklarieren welche Entitäten suchbar sind, System registriert automatisch Provider + Hooks | 1 Tag | -| S-PD-DOC | **Plugin-Dev-Guide Update** — `docs/plugin-development-guide.md` mit Search-Kapitel erweitern | 0.5 Tage | -| S-PD-TEST | **Plugin-Dev-Tests** — Test-Suite die prüft ob ein Plugin die Search-Konventionen einhält | 0.5 Tage | +| B-SCHEMA | Dokumentieren: Core → Alembic, Plugin → Plugin-Migrationsweg, Runtime Auto-Sync → nicht authoritative. Kein neuer Schema-Mechanismus | 0.5 Tage | -**Deliverables:** Eine vereinheitlichte Such-Plattform über alle Entitäten (Core + Plugins + AI Chat + Workflows + Agenten + AuditLog + EntityHistory), mit FTS + Vector + RAG + Graph Such-Modi, selbstständiger Hintergrund-Indexierung, KI-Nutzbarkeit (Tool, MCP, API), Command-Palette UI, und Plugin-Dev-Guide. Alle fragmentierten Such-Systeme sind konsolidiert und rückgebaut. +### 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. **Test-Strategie** — wie Plugin Tests schreibt (Backend: pytest, Frontend: Vitest, E2E: Playwright), was getestet werden muss + +### 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.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 | 1 Tag | +| 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 | + +**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, konsistente Lifecycle-Hooks + relevante Domain-Outbox-Events, gemeinsamer Trigger-Kern sowie vollständige Notification→Message-Konsolidierung. --- -## Phase 2 — Autonomous Agent Engine (ReAct-Loop) - -**Dauer:** 6 Wochen -**Ziel:** Autonome KI-Agenten, die CRM-Workflows selbstständig ausführen können -**Begründung:** Kernstück der Plattform-Vision. Die Infrastruktur (Agent Runner, Coordinator, Tool Registry, CRM API Tool, Scheduler, Memory) existiert. Die ReAct-Loop fehlt. - -### 2.1 ReAct Agent Loop - -Die zentrale Komponente: Ein Agent-Loop nach dem ReAct-Pattern (Reason → Act → Observe → Repeat), der LiteLLM Function-Calling nutzt. - -``` -User/Trigger → Agent Loop: - 1. System Prompt + Context + Tools → LLM - 2. LLM responds with: text + tool_calls - 3. Execute tool_calls via ToolRegistry - 4. Append tool results to conversation - 5. If tool_calls present → goto 1 (next iteration) - 6. If no tool_calls → agent is done, return final answer - 7. Safety checks after each iteration (max_steps, budget, timeout) -``` - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| A-LOOP | `agent_loop.py` — ReAct-Loop mit LiteLLM `acompletion()` + `tools=` Parameter | 3 Tage | -| A-CALL | Tool-Call-Parser — extrahiert function_calls aus LLM-Response, ruft ToolRegistry auf | 1 Tag | -| A-CTX | Context-Builder — sammelt System-Prompt, Agent-Definition, Memory, CRM-API-Spec, Tool-Schemas | 2 Tage | -| A-MAX | Max-Steps-Limit (z.B. 20 Iterationen) + Graceful-Stop mit Zusammenfassung | 0.5 Tage | -| A-ERR | Error-Handling: Tool-Fehler → LLM bekommt Error-Message, kann adaptieren | 1 Tag | -| A-STR | Streaming: SSE-Stream von Agent-Reasoning + Tool-Calls für UI | 1 Tag | - -### 2.2 Agent-Definition & Management - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| A-DEF | AgentDefinition CRUD API — erweitert bestehende automation/agent_routes.py | 1 Tag | -| A-TOOL | Tool-Binding — Agent definiert welche Tools er nutzen darf (Subset aus ToolRegistry) | 1 Tag | -| A-PERM | Permission-Context — Agent agiert im Kontext eines Users (RBAC wird geprüft pro Tool-Call) | 1 Tag | -| A-MEM | Memory-Integration — Agent nutzt agent_memory Plugin für persistente Erinnerungen | 1 Tag | -| A-HEART | Heartbeat — proactive Agenten pollen regelmäßig Kontext und generieren Vorschläge | 1 Tag | - -### 2.3 Agent UI - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| A-LIST | Agent-Liste — alle Agenten mit Status, letzter Run, Kosten. **Kartenansicht und Listenansicht** (Toggle zwischen Grid-Cards und Table-List). Karten zeigen: Name, Beschreibung, Status-Badge, Modell, letzte Aktivität, Kosten-Summe. Liste zeigt: alle Spalten sortierbar/filterbar | 1.5 Tage | -| A-EDIT | Agent-Editor — System-Prompt, Modell, Tools, Limits, Trigger konfigurieren | 2 Tage | -| A-CHAT | Agent-Chat-UI — interaktive Konversation mit Agent (wie AI Copilot, aber mit Tool-Calls) | 2 Tage | -| A-LOG | Agent-Run-Log — Step-by-Step Reasoning-Trace, Tool-Calls, Results, Kosten | 1 Tag | -| A-MON | Agent-Monitoring — Live-Status, aktive Runs, Queue, Budget-Verbrauch | 1 Tag | - -### 2.4 Pre-Built Agenten - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| A-EMAIL | E-Mail-Triage-Agent — liest Inbox, kategorisiert, schlägt Antworten vor, erstellt Tasks | 2 Tage | -| A-CONTACT | Contact-Enrichment-Agent — sucht fehlende Daten, dedupliziert, aktualisiert | 1 Tag | -| A-FOLLOW | Follow-up-Agent — erinnert an unbeantwortete Mails, schlägt Follow-ups vor | 1 Tag | -| A-REPORT | Report-Agent — generiert wöchentliche Zusammenfassungen, Dashboards | 1 Tag | - -### 2.5 Guardrails & Safety - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| A-APPR | Approval-Pipeline — destruktive Aktionen (DELETE, bulk UPDATE) erfordern User-Approval | 2 Tage | -| A-DRY | Dry-Run-Mode — Agent plant Aktionen, führt aber nichts aus (nur Vorschläge) | 0.5 Tage | -| A-REV | Reversibility-Check — Agent prüft ob Aktion umkehrbar ist vor Ausführung | 1 Tag | -| A-AUDIT | Audit-Log für jeden Tool-Call (wer, was, wann, result, cost) | 1 Tag | - -### 2.6 KI-Agent Permission-Integration - -KI-Agenten müssen wie User behandelt werden und vollständig ins Rechte-System integriert werden. Aktuell nutzt der Agent Runner nur `tenant_id` — kein `user_id`, kein Permission-Kontext. Das muss sich ändern. - -**Prinzip:** Jeder Agent agiert im Kontext eines Users. Jeder Tool-Call wird gegen die Permissions dieses Users geprüft. Ein Agent kann niemals mehr als sein User darf. - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| A-PERM-CTX | **Agent Permission Context** — AgentDefinition bekommt `acting_user_id` Feld. Agent agiert im Kontext dieses Users. Permission-Resolution wird beim Agent-Start geladen (wie bei normalem User-Login) | 1 Tag | -| A-PERM-CHECK | **RBAC pro Tool-Call** — jeder Tool-Call wird gegen `check_permission(user_context, required_permission)` geprüft. Tool hat `required_permission` (bereits im ToolRegistry). Agent darf Tool nur aufrufen wenn User die Permission hat | 1 Tag | -| A-PERM-VIS | **Visibility-Filter** — Agent-Queries (z.B. "zeige alle Kontakte") werden mit `apply_visibility_filter()` gefiltert. Agent sieht nur was der User sehen darf | 1 Tag | -| A-PERM-ENTITY | **Entity-Level-Permissions** — Agent respektiert EntityPermission (ABAC). Wenn User nur Read-Zugriff auf Kontakt X hat, kann Agent Kontakt X nicht ändern | 1 Tag | -| A-PERM-ROLE | **Agent-Rollen** — AgentDefinition kann eine Rolle zugewiesen bekommen (z.B. "read-only-agent", "mail-agent"). Rolle definiert welche Tools/Permissions der Agent nutzen darf — unabhängig vom User | 1 Tag | -| A-PERM-AUDIT | **Permission-Audit-Trail** — jeder Permission-Check wird geloggt: Agent-ID, User-ID, Tool, Required-Permission, Granted/Denied. Nachvollziehbar wer was erlaubt hat | 0.5 Tage | -| A-PERM-ESCAL | **Escalation-Prevention** — Agent kann keine Permissions eskalieren. Kein Tool-Call der Permissions ändert (roles:write, permissions:write) ohne User-Approval | 0.5 Tage | -| A-PERM-UI | **Permission-UI im Agent-Editor** — Admin sieht welche Permissions der Agent braucht, kann sie genehmigen/entziehen. Permission-Matrix pro Agent | 1 Tag | -| A-PERM-VIS-USER | **User-Agent Visibility** — User sehen nur Agenten die für sie freigeschaltet sind. Nutzt bestehendes Rechte-System: `agents:read` Permission + EntityPermission mit `entity_type='agent_definition'`. Admin kann Agenten für bestimmte User/Gruppen freischalten. KEIN extra Bauten — alles über bestehendes RBAC/ABAC | 1 Tag | -| A-PERM-USE | **User-Agent Usage Permission** — User können nur Agenten benutzen die für sie freigeschaltet sind. `agents:execute` Permission pro Agent. Agent-Chat-UI prüft Permission vor Start. KEIN extra System — über bestehendes `require_permission()` | 0.5 Tage | - -**Deliverables:** Funktionierende autonome Agenten mit ReAct-Loop, Tool-Calling, Memory, Guardrails, UI für Definition/Monitoring/Chat, 4 Pre-Built Agenten. - ---- - -## Phase 3 — Workflow Platform (n8n-Ersatz) - -**Dauer:** 6 Wochen -**Ziel:** Visuelle Workflow-Engine die n8n ersetzt — tief in das CRM integriert -**Begründung:** Die Workflow-Engine (action/approval/notification/condition) und das Automation-Plugin (execution_engine, scheduler, cron) existieren. Es fehlen: visuelle Editor, erweiterte Step-Types, Integration-Nodes. - -### 3.1 Erweiterte Step-Types - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| W-LOOP | Loop-Step — iteriere über Array/Query-Result | 1 Tag | -| W-PAR | Parallel-Branch — mehrere Steps gleichzeitig ausführen | 1 Tag | -| W-WAIT | Wait/Delay-Step — pausiert für Duration oder bis Datum | 0.5 Tage | -| W-WEB | Webhook-Trigger-Step — externer HTTP-Call startet Workflow | 1 Tag | -| W-CODE | Code-Step — sichere Ausführung von Python/JS-Snippet (Sandbox) | 2 Tage | -| W-AGENT | Agent-Step — ruft autonomen Agenten auf (Phase 2 Integration) | 1 Tag | -| W-TRANS | Transform-Step — Daten-Transformation (Mapping, Filter, Aggregation) | 1 Tag | - -### 3.2 Integration-Nodes - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| W-HTTP | HTTP-Request-Node — generischer REST-Aufruf (wie n8n HTTP Request) | 1 Tag | -| W-DB | DB-Query-Node — SQL-Query ausführen (tenant-scoped, read-only default) | 1 Tag | -| W-MAIL | Mail-Send-Node — E-Mail über CRM-Mail-Plugin senden | 0.5 Tage | -| W-CAL | Calendar-Node — Termine erstellen/lesen | 0.5 Tage | -| W-DMS | DMS-Node — Dokumente hochladen/metadaten aktualisieren | 0.5 Tage | -| W-AI | AI-Node — LLM-Call (einzelner Prompt, nicht voller Agent) | 0.5 Tage | -| W-SEARCH | Search-Node — Unified Search als Workflow-Step | 0.5 Tage | -| W-SLACK | Webhook-Node — Slack/Teams/Discord Notification via Webhook | 0.5 Tage | - -### 3.3 Workflow-Editor (Hybrid: Form + JSON) - -Statt eines visuellen Drag-and-Drop-Canvas (wie n8n) wird ein form-basierter Editor mit JSON-Expert-Mode gebaut. Spart 3.5 Tage, ist schneller fertig, und ein visueller Editor kann später nachgerüstet werden. - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| W-FORM | Form-basierter Step-Editor — Step-Liste mit Up/Down-Reihenfolge, Formular pro Step-Typ | 2 Tage | -| W-JSON | JSON-Expert-Mode — Toggle zwischen Form und JSON-Editor (Monaco/CodeMirror) | 0.5 Tage | -| W-VALID | Validation — Required-Field-Check, Type-Compatibility, Step-Reihenfolge-Check | 0.5 Tage | -| W-EXPORT | JSON-Export/Import — Workflow als JSON speichern/laden (Versionierung) | 0.5 Tage | -| W-TEMPL | Template-Gallery — vorgefertigte Workflows zum Importieren | 1 Tag | - -### 3.4 Workflow-Execution-Erweiterung - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| W-ENG | Engine-Erweiterung — neue Step-Types in workflow engine.py integrieren | 2 Tage | -| W-CTX | Execution-Context — Daten-Flow zwischen Steps (Variablen, Expressions) | 2 Tage | -| W-RETRY | Retry-Logic — fehlgeschlagene Steps automatisch wiederholen | 1 Tag | -| W-TIME | Timeout-Handling — pro-Step Timeout mit konfigurierbarer Aktion | 0.5 Tage | -| W-LOG | Execution-Log — detailliertes Logging pro Step (Input, Output, Duration, Status) | 1 Tag | - -### 3.5 Trigger-System - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| W-EVT | Event-Trigger — CRM-Event startet Workflow (contact.created, mail.received, etc.) | 1 Tag | -| W-CRON | Cron-Trigger — zeitgesteuerte Ausführung (bestehender scheduler erweitern) | 0.5 Tage | -| W-MAN | Manual-Trigger — Button in UI startet Workflow | 0.5 Tage | -| W-WEB2 | Webhook-Trigger — externe Systeme starten Workflow via HTTP | 1 Tag | -| W-AGT | Agent-Trigger — Agent startet Workflow als Teil seiner Tool-Calls | 1 Tag | - -**Deliverables:** Vollständige Workflow-Plattform mit visuellem Editor, 7+ Step-Types, 8+ Integration-Nodes, Event/Cron/Webhook/Manual-Triggers, Execution-Logging, Template-Gallery. - ---- - -## Phase 4 — Knowledge Management & RAG - -**Dauer:** 6 Wochen -**Ziel:** Komplettes Wissensmanagement — Wissensgraph, Document-RAG, Wiki, automatische Relationship-Extraktion -**Begründung:** GraphRAG, DMS, Unified Search und Agent Memory sind vorhanden. Es fehlen: Document-RAG-Pipeline, automatische Wissensgraph-Extraktion, Wiki-System, Knowledge-UI. - -### 4.1 Document-RAG-Pipeline - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| K-CHUNK | Document-Chunking — DMS-Dokumente in semantische Chunks zerlegen | 1 Tag | -| K-EMB | Chunk-Embedding — pgvector Embeddings pro Chunk (ARQ Background Job) | 1 Tag | -| K-RET | Retrieval-Pipeline — Query → Semantic Search über Chunks → Top-K Results | 1 Tag | -| K-GEN | Generation-Pipeline — Chunks + Query → LLM → Antwort mit Quellenangabe | 1 Tag | -| K-INDEX | Index-Management — Re-Indexierung bei Dokument-Änderung, Versionierung | 1 Tag | -| K-MCP | MCP-Server-Exposure — RAG als MCP-Tool für externe Agenten verfügbar | 0.5 Tage | - -### 4.2 Automatische Wissensgraph-Extraktion - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| K-EXT | LLM-Relationship-Extraktion — analysiert Texte (Mails, Doks, Notes) und extrahiert Beziehungen | 2 Tage | -| K-ENT | Entity-Extraction — erkennt Personen, Firmen, Projekte, Themen in Texten | 1 Tag | -| K-AUTO | Auto-Relationship-Creation — extrahierte Beziehungen in GraphRAG speichern | 1 Tag | -| K-CONF | Confidence-Score — extrahierte Beziehungen mit Confidence, Low-Confidence → Review-Queue | 1 Tag | -| K-EVT | Event-Driven-Extraction — neue Mail/Dokument → ARQ-Job → Extraktion → GraphRAG | 1 Tag | - -### 4.3 Wiki / Knowledge-Base - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| K-WIKI | Wiki-Plugin — Knowledge-Artikel mit Markdown-Editor, Kategorien, Tags | 2 Tage | -| K-VER | Versionierung — Artikel-Historie, Diff-View, Restore | 1 Tag | -| K-LINK | Auto-Linking — Artikel verlinken automatisch auf Entitäten (Contact, Company) | 1 Tag | -| K-SEARCH | Wiki Search Provider — Artikel in Unified Search integrieren | 0.5 Tage | -| K-EMB2 | Wiki-Embedding — Artikel als Chunks in RAG-Pipeline | 0.5 Tage | - -### 4.4 Knowledge-UI - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| K-GRAPH | Wissensgraph-Visualisierung — interaktiver Graph (D3.js / Cytoscape) | 2 Tage | -| K-EDITOR | Wiki-Artikel-Editor — Markdown-Editor mit Live-Preview, Auto-Save | 1 Tag | -| K-BROWSE | Knowledge-Browser — Baumansicht Kategorien, Artikel-Liste, Suche | 1 Tag | -| K-ASK | "Ask Knowledge Base" — Chat-Interface für RAG-Queries mit Quellenangabe | 1 Tag | -| K-REV | Review-Queue — bestätigte/abgelehnte extrahierte Beziehungen | 0.5 Tage | - -**Deliverables:** Document-RAG-Pipeline, automatische Wissensgraph-Extraktion, Wiki-System mit Versionierung, Knowledge-UI mit Graph-Visualisierung und "Ask KB"-Chat. - ---- - -## Phase 5 — Platform Integration & Polish +## Phase C — Core UI abschließen **Dauer:** 4 Wochen -**Ziel:** Alle Systeme integrieren, UX-Polish, Performance, Dokumentation -**Begründung:** Die einzelnen Phasen produzieren funktionierende Komponenten. Phase 5 verbindet sie zu einer kohärenten Plattform. +**Ziel:** Bereits weitgehend vorhandene Frontend-Funktionen verifizieren, fertigstellen und konsistent machen; kein paralleler UI-Neubau. -### 5.1 Cross-System-Integration +**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 | |------|-------------|---------| -| P-AW | Agent → Workflow — Agenten können Workflows als Tools aufrufen | 1 Tag | -| P-WA | Workflow → Agent — Workflows können Agenten als Steps aufrufen (bereits W-AGENT) | 0.5 Tage | -| P-AS | Agent → Search — Agenten nutzen Unified Search als Tool | 0.5 Tage | -| P-AK | Agent → Knowledge — Agenten nutzen RAG-Pipeline für Queries | 0.5 Tage | -| P-KS | Knowledge → Search — Wiki-Artikel in Unified Search | 0.5 Tage | -| P-MCP | MCP-Server — alle Platform-Features als MCP-Tools für externe Systeme | 1 Tag | +| 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-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 | -### 5.2 Dashboard & Analytics - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| P-DASH | Platform-Dashboard — Agent-Status, Workflow-Stats, Search-Metrics, Knowledge-Coverage | 2 Tage | -| P-COST | Cost-Tracking — LLM-Kosten pro Agent/Workflow/User, Budget-Alerts | 1 Tag | -| P-USE | Usage-Analytics — meistgenutzte Features, Search-Queries, Agent-Runs | 1 Tag | - -### 5.3 Performance & Scale - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| P-CACHE | Search-Caching — häufige Queries cachen (Redis) | 1 Tag | -| P-BATCH | Batch-Embedding — mehrere Entities in einem LLM-Call embedden | 0.5 Tage | -| P-QUEUE | ARQ-Queue-Tuning — Prioritäten, Concurrency-Limits, Dead-Letter-Queue | 1 Tag | -| P-IDX | DB-Index-Optimierung — pgvector HNSW-Parameter, FTS-Index-Tuning | 1 Tag | - -### 5.4 Documentation & Onboarding - -| Task | Beschreibung | Aufwand | -|------|-------------|---------| -| P-DOC | Platform-Dokumentation — Architektur, Plugin-Dev-Guide, Agent-Dev-Guide | 2 Tage | -| P-ONB | Platform-Onboarding — Setup-Wizard, Sample-Agenten, Sample-Workflows | 1 Tag | -| P-VID | Feature-Videos — kurze Screencasts für Agent-Builder, Workflow-Editor, Knowledge-Base | 1 Tag | - -**Deliverables:** Vollständig integrierte Plattform mit Dashboard, Cost-Tracking, optimierter Performance, Dokumentation und Onboarding-Material. +**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 und PWA mit reaktiviertem Service Worker. --- -## Abhängigkeitsgraph +## Phase C.5 — Modularer Import/Export -``` -Phase 0 (Foundation) - │ - ├──→ Phase 0.5 (Undo & Restore) ──→ alle Phasen profitieren - │ - ├──→ Phase 0.7 (System-Konsolidierung) ──→ alle Phasen profitieren - │ - ├──→ Phase 1 (Search) ──────────────→ P-AS, P-KS - │ │ - ├──→ Phase 2 (Agents) ──────────────→ P-AW, P-WA, P-AK - │ │ │ - │ └──→ Phase 3 (Workflows) ────→ P-AW (bidirectional) - │ │ - │ └──→ Phase 4 (Knowledge) ──→ P-AK, P-KS - │ │ - │ └──→ Phase 5 (Integration) - └──────────────────────────────────────────────────────┘ +**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 | 1 Tag | +| 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 | 1 Tag | +| 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 | 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 | 2 Tage | +| E-IX-RE | Re-Indexierung: Batch-Reindex Kommando, Delete-Handling, Retry | 1 Tag | +| 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), 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 | 3 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 Error-Message | 1 Tag | +| 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-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 | 2 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-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 | + +**Deliverables Phase F:** ReAct-Agenten auf vorhandener Agentenbasis, kleiner Skill-Baustein, Tool-/Skill-Calling, Permission-Modell (User/Run-as ∩ Agent ∩ Skill ∩ Tool), Standard+Extended Trace, trigger-basierte Proaktivität, UI Control ohne Permission-Bypass, zentraler ApprovalRequest-Kern, Workstream-Ausgabe, Agent UI und 4 Pre-Built Agenten. + +--- + +## 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**. + +**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-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** — 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 | 1.5 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, 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-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, 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.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 | 1.5 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), hier wird die UI gebaut | 1.5 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-Auskunfts-Export + +Der vollständige plattformweite Datenauskunfts-Export wird erst hier gebaut, wenn Core, Communication, Agents, Workflows und Knowledge vorhanden sind. Keine eigene universelle Export-Provider-Architektur nur für diesen Zweck. + +| Task | Beschreibung | Aufwand | +|------|-------------|---------| +| I-DSGVO | **Vollständiger Plattform-Datenauskunfts-Export** — personenbezogene Daten eines Users über Core und aktive Plugins hinweg (u. a. CRM, Mail, Calendar, DMS, Communication/Workstreams, Agents, Workflows, Knowledge, Audit) als strukturierter JSON/ZIP-Export. Sensitive-Data-Regeln zwingend beachten | 2 Tage | + +### 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-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 ``` -**Wichtige Abhängigkeiten:** -- Phase 0.5 (Undo & Restore) ist foundational — alle späteren Phasen profitieren davon -- Phase 2 (Agents) benötigt Phase 1 (Search) für Search-as-Tool -- Phase 3 (Workflows) benötigt Phase 2 (Agents) für Agent-Step -- Phase 4 (Knowledge) benötigt Phase 2 (Agents) für LLM-Extraktion -- Phase 5 (Integration) benötigt alle vorherigen Phasen -- Phase 1 und Phase 2 können teilweise parallel laufen (ab Phase 0.1 Abschluss) +| 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. Keine unnötigen sensiblen Datenkopien | 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. --- -## Technologie-Entscheidungen +## Zielarchitektur im Endstand -| Entscheidung | Wahl | Begründung | -|-------------|------|------------| -| Agent-Loop | LiteLLM `acompletion()` + `tools=` | Bereits im Stack, OpenAI-kompatibel, alle Provider | -| Visueller Editor | React Flow | De-facto-Standard, MIT-Lizenz, gut dokumentiert | -| Graph-Visualisierung | Cytoscape.js | Performance bei großen Graphen, interaktiv | -| Code-Sandbox | Pyodide / QuickJS | Isolierte Ausführung, kein Server-Side-Code-Injection | -| Document-Chunking | LangChain TextSplitter (recursive) | Bewährt, konfigurierbar, Python-native | -| Embedding-Model | text-embedding-3-small (768-dim) | Bereits konfiguriert, kostengünstig | -| Wiki-Editor | TipTap (React) | Markdown + Rich-Text, Auto-Save, kollaborativ erweiterbar | +```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 │ +└──────────────────────────────────────────────────────────┘ +``` + +**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. --- -## Risiken & Mitigation +## Später — Advanced Autonomy/Automation nur bei echtem Bedarf -| Risiko | Wahrscheinlichkeit | Impact | Mitigation | -|--------|-------------------|--------|------------| -| LLM-Kosten explodieren durch autonome Agenten | Mittel | Hoch | Budget-Limits pro Agent (bereits im Manifest), Cost-Tracking, Dry-Run-Mode | -| Agenten führen destruktive Aktionen aus | Mittel | Kritisch | Approval-Pipeline, Reversibility-Check, RBAC pro Tool-Call, Audit-Log | -| Workflow-Editor wird zu komplex | Hoch | Mittel | Inkrementell bauen, Template-Gallery, User-Testing | -| pgvector-Performance bei vielen Embeddings | Mittel | Mittel | HNSW-Parameter-Tuning, Batch-Embedding, Re-Index-Strategie | -| React-Flow-Lizenzänderung | Niedrig | Mittel | MIT-Lizenz ist stabil, Alternative: Drawflow | -| Multi-Agent-Deadlocks | Niedrig | Hoch | Timeout in Coordinator (bereits vorhanden), Deadlock-Detection | -| Mail-Undo verliert Daten auf IMAP-Server | Mittel | Hoch | Soft-Delete zuerst, IMAP-Trash-Mapping, Sync-Conflict-Resolution | -| EntityHistory-Storage wächst unkontrolliert | Mittel | Mittel | Retention-Policy, Monats-Partitionierung, GDPR-Hard-Delete | +### 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. -## Erfolgsmetriken +Geplante Erweiterungsfähigkeiten: -| Metrik | Ziel | Messung | -|--------|------|---------| -| Search-Query-Latenz | < 500ms (P95) | APM / Endpoint-Timing | -| Search-Abdeckung | 100% aller Entitäten | Provider-Count vs Entity-Count | -| Auto-Indexierung-Latenz | < 30s nach Entity-Änderung | ARQ-Job-Timing | -| Search-KI-Nutzbarkeit | MCP + Tool + API | MCP-Tool-Verfügbarkeit | -| Agent-Run-Erfolgsrate | > 85% | AgentRun.status = completed / total | -| Workflow-Execution-Latenz | < 2s pro Step (ohne externe Calls) | Execution-Log | -| RAG-Query-Accuracy | > 80% relevante Results | User-Feedback (Thumbs Up/Down) | -| LLM-Kosten pro Tenant/Monat | < 50€ (Standard-Nutzung) | Cost-Tracking-Dashboard | -| Platform-Aktive-Nutzer | +30% nach 3 Monaten | Analytics | -| Undo/Restore-Erfolgsrate | > 95% | Restore-Operationen erfolgreich / total | -| Mail-Restore-Latenz | < 3s (DB-only), < 10s (mit IMAP-Sync) | Endpoint-Timing | +- **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. + +### 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 --- @@ -1286,29 +1005,19 @@ Phase 0 (Foundation) | Phase | Dauer | Hauptdeliverable | |-------|-------|----------------| -| 0 — Foundation | 4 Wochen | Stabile Frontend-UI, Test-Coverage, Cleanup | -| 0.5 — Undo & Restore | 5 Wochen | Universal Undo/Restore für alle Entitäten, Konsolidierung aller History-Systeme, Plugin-Dev-Guide | -| 0.7 — System-Konsolidierung | 10 Wochen | Attachments, LLM, WebSocket, Redis, Events, File Upload, Import/Export, Error/Custom Fields, Plugin-Specification & Contract, Plugin Public Web Content | -| 0.8 — Frontend-Konsolidierung | 5 Wochen | Standard-Komponenten, Template-System, Plugin-UI-Loading, Code-Bereinigung, Frontend-Regeln | -| 1 — Search | 4 Wochen | Unified Search Platform — vereinheitlichte Suche über alles, KI-nutzbar, Auto-Indexierung | -| 2 — Agents | 6 Wochen | Autonome Agenten mit ReAct-Loop, 4 Pre-Built Agenten | -| 3 — Workflows | 6 Wochen | Visueller Workflow-Editor, n8n-Ersatz | -| 4 — Knowledge | 6 Wochen | Document-RAG, Wissensgraph, Wiki, Knowledge-UI | -| 5 — Integration | 4 Wochen | Integrierte Plattform, Dashboard, Polish | -| **Total** | **50 Wochen** | **LeoPlatform — KI-gesteuerte Business-Plattform** | +| 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 | +| **Total** | **52 Wochen** | **LeoPlatform Endstand-Kern** | --- -*Diese Roadmap basiert auf einer tiefen Code-Analyse des bestehenden LeoCRM-Codebases. Alle Phasen bauen auf vorhandener Infrastruktur auf — keine Architektur-Umbrüche erforderlich.* - -### Undo & Restore — Detail-Analyse - -Das bestehende EntityHistory-System ist nur halb implementiert: -- **EntityHistory Model** existiert mit `snapshot_before` / `snapshot_after` / `changes` -- **restore_from_history()** ist hardcoded auf `entity_type == "contact"` — kein generisches Restore -- **record_history()** wird nur in `contact_service.py` (3x) und `companies.py` (1x) aufgerufen -- **Kein Plugin** (Mail, DMS, Tasks, Calendar, Tags) nutzt record_history -- **Mail** ist besonders schwierig: IMAP-Sync bedeutet dass Löschungen auf dem Mailserver passieren, nicht nur in der DB -- **Undo UI** existiert nicht - -Phase 0.5 adressiert all dies mit einer generischen Restore-Engine, Hook-basierter History-Aufzeichnung für alle Entitäten, Mail-spezifischer IMAP-Trash-Logik, Bulk-Undo und einer Trash-View UI. +*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.*