feat(roadmap): systematisches Error-Handling in Roadmap integriert

- Querschnitt-Regel: Error-Handling-Konvention (verbindlich) hinzugefügt
- Phase B.13: Error-Handling-Infrastruktur (B-ERR-FMT, B-ERR-CAT, B-ERR-WS, B-ERR-PROP, B-ERR-TEST)
- Phase B.7: Plugin-Guide Kapitel 22 (Error-Handling) ergänzt
- Phase C: C-ERR-BOUNDARY (Frontend Error Boundaries)
- Phase C.5: C5-JOB Partial-Failure-Semantik
- Phase D: D-BULK Partial-Failure-Semantik
- Phase E: E-IX-EVT Index-Fehler-Handling (Retry, DLQ, Konsistenz-Check)
- Phase F: F-LOOP LLM-Fehlerstrategie (Rate-Limit, Failover, Timeout), F-ERR ErrorCategory
- Deliverables Phase B/C/F aktualisiert
- +5.5 Tage Aufwand verteilt über 52 Wochen

PLATFORM_ROADMAP.md

@@ -73,6 +73,18 @@ Betroffen: Password Hashes, SMTP/IMAP Credentials, API Keys, OAuth Tokens, Sessi
 
 Lösung: Zentrale Exclude-/Sensitive-Field-Konvention. Verbindlich, getestet, keine riesige Security-Engine.
 
+### Error-Handling-Konvention (verbindlich)
+
+Error Handling ist **keine nachträgliche Schicht**, sondern wird direkt an den jeweiligen Systemgrenzen konsistent umgesetzt: LLM-Client, Agent-Loop, Workflow-Engine, WebSocket, Search/Indexing, Plugin-Routes, Batch-Operationen und Frontend.
+
+**Grundregeln:**
+- **Einheitliches Error-Response-Format** für die gesamte API: `{code, detail, field, trace_id, retryable}`. Keine Ad-hoc-`HTTPException` ohne strukturierten Code.
+- **Error-Kategorisierung**: `TRANSIENT` (retryable: Timeout, Rate-Limit, Connection), `PERMANENT` (non-retryable: Validation, Permission, NotFound), `PARTIAL` (teilweise erfolgreich: Batch, Bulk, Multi-Step). Jeder Fehler trägt seine Kategorie, damit Workflow-Retry, Agent-Recovery und Frontend-UX entscheiden können.
+- **Error-Propagation-Kette**: Plugin/Service → Core → API → Frontend → User. Technische Details (Tracebacks, interne Pfade) werden nur geloggt/monitoriert; dem User wird eine verständliche Nachricht mit `trace_id` zur Nachverfolgung gezeigt.
+- **Frontend Error Boundaries**: Jede Plugin-Seite, MiniApp und kritische Komponente wird von einer ErrorBoundary umschlossen. Ein fehlerhaftes Plugin darf nicht die ganze App crashen.
+- **Partial-Failure-Semantik**: Batch-Operationen (Import, Bulk-Restore, Re-Index, Agent Multi-Step) melden `partial_success` mit klarem Fehler-Report, was committed ist und was fehlgeschlagen ist. Kein stummes Versagen, kein inkonsistenter Zustand.
+- **Bestehende Resilience-Patterns nutzen**: CircuitBreaker, `retry_db`, Outbox DLQ/Replay und Plugin-Error-Isolation sind vorhanden und werden konsequent angewendet — keine zweite Error-Engine.
+
 ### Privacy / DSGVO / EU AI Act by Design (verbindlich)
 
 Compliance wird **nicht** als nachträgliche Parallelarchitektur gebaut. Datenschutz-, Transparenz-, Human-Oversight- und Nachweisfunktionen werden direkt an den bereits vorhandenen technischen Grenzen umgesetzt: Entity/Field-Metadaten, `AIProvider`, LLM-Client, Outbox, SearchProvider, AgentRun, WorkflowRun, ApprovalRequest, Audit und Communication.
@@ -363,6 +375,7 @@ Gemeinsame Helpers statt großer BaseWebSocketManager. Spezialisierte Manager bl
 19. **Frontend** — wie Plugin Frontend-Komponenten erstellt (Standard-Komponenten nutzen, Manifest deklarieren, Theme respektieren, i18n nutzen, ErrorBoundary), inklusive Delivery-Vertrag: volle React-Komponenten deployment-time/bundled; runtime MiniApps schema-/registry-basiert
 20. **Privacy/AI Compliance** — wie Plugin Datenklassen/AI-Exposure deklariert, AI-Use-Cases beschreibt, Human-Oversight/Transparency nutzt und abgeleitete Daten bei Correction/Erasure nachzieht; High-Risk-Spezialpflichten bleiben beim konkreten Vertical/Use-Case
 21. **Test-Strategie** — wie Plugin Tests schreibt (Backend: pytest, Frontend: Vitest, E2E: Playwright), was getestet werden muss
+22. **Error-Handling** — wie Plugin Errors werfen (`ApiError` mit `code`, `category`, `retryable`), Error-Propagation-Kette (Plugin → Core → API → Frontend → User), `trace_id`-Korrelation, Frontend-ErrorBoundary-Pflicht für Plugin-Seiten/MiniApps, Partial-Failure-Semantik bei Batch-Operationen, keine Tracebacks an User
 
 ### B.8 Rate-Limiting Konsistenz
 
@@ -440,7 +453,19 @@ Das bisher separate Notification-System und das Communication-/Message-System we
 | 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 + AI/Data Exposure Policy, AIProvider-Compliance-Metadaten, konsistente Lifecycle-Hooks + relevante Domain-Outbox-Events, gemeinsamer Trigger-Kern sowie vollständige Notification→Message-Konsolidierung.
+### B.13 Error-Handling-Infrastruktur
+
+Bestehende Resilience-Patterns (CircuitBreaker, `retry_db`, Outbox DLQ/Replay, Plugin-Error-Isolation) werden konsolidiert und um die fehlenden systematischen Bausteine ergänzt. Keine zweite Error-Engine, sondern ein einheitlicher Rahmen auf bestehenden Mustern.
+
+| Task | Beschreibung | Aufwand |
+|------|-------------|---------|
+| B-ERR-FMT | **Einheitliches Error-Response-Format** — `{code, detail, field, trace_id, retryable}` für die gesamte API. Bestehende `error_codes.py` (6 Codes) erweitern, `ApiError` als Standard-Exception, FastAPI Exception-Handler der alle Errors im einheitlichen Format zurückgibt. `trace_id` korreliert mit Request-Logging | 1 Tag |
+| B-ERR-CAT | **Error-Kategorisierung** — `ErrorCategory.TRANSIENT` (retryable: Timeout, Rate-Limit, Connection), `PERMANENT` (non-retryable: Validation, Permission, NotFound), `PARTIAL` (teilweise erfolgreich: Batch, Bulk, Multi-Step). Jeder `ApiError` trägt seine Kategorie; Workflow-Retry, Agent-Recovery und Frontend-UX nutzen diese | 0.5 Tage |
+| B-ERR-WS | **WebSocket Error-Handling** — strukturierte Error-Messages an WS-Clients, Reconnect-Hints, Dead-Message-Queue für nicht-verarbeitbare Messages. In B-WS Helpers integriert | 0.5 Tage |
+| B-ERR-PROP | **Error-Propagation-Konvention** — Plugin/Service → Core → API → Frontend → User. Technische Details (Tracebacks, interne Pfade) nur geloggt/monitoriert; dem User verständliche Nachricht mit `trace_id`. Im Plugin-Dev-Guide (B-PLUGIN-GUIDE) als Kapitel 22 dokumentieren | 0.5 Tage |
+| B-ERR-TEST | Tests: Error-Response-Format, Kategorisierung, WS-Error-Handling, Error-Propagation | 1 Tag |
+
+**Deliverables Phase B:** Zentraler LLM Client, zentraler Redis Pool, gemeinsamer File Storage, WebSocket Helpers, Event-System dokumentiert, Schema Authority definiert, schlanker Plugin-Guide, MiniApp-Contribution-Wiring, klarer Plugin-Frontend-Vertrag, gezieltes Rate-Limiting, Sensitive Data Boundary + AI/Data Exposure Policy, AIProvider-Compliance-Metadaten, konsistente Lifecycle-Hooks + relevante Domain-Outbox-Events, gemeinsamer Trigger-Kern, vollständige Notification→Message-Konsolidierung sowie systematische Error-Handling-Infrastruktur (einheitliches Response-Format, Error-Kategorisierung, WS-Error-Handling, Error-Propagation-Konvention).
 
 ---
 
@@ -473,10 +498,11 @@ Das bisher separate Notification-System und das Communication-/Message-System we
 | C-A11Y | Accessibility ergänzen — sr-only Texte, ARIA-Live-Regions | 1 Tag |
 | C-PWA | **PWA behalten und Service Worker sauber reaktivieren** — kontrollierte Cache-Strategie für App-Shell und statische Assets, sauberes Update-/Cache-Invalidierungsverhalten. API-, Auth-, Tenant- und Permission-sensitive Daten nicht pauschal cachen. Keine Offline-Sync-/Offline-ERP-Architektur | 0.5 Tage |
 | C-FE-CLEAN | Frontend bereinigen: neue/geänderte Dateien sauber (keine any, keine inline styles wo vermeidbar). Bestehende nur bei Fehler/Security/Inkonsistenz | fortlaufend |
+| C-ERR-BOUNDARY | **Frontend Error Boundaries** — ErrorBoundary-Komponente + Plugin-ErrorBoundary-Wrapper. Jede Plugin-Seite, MiniApp und kritische Komponente wird von einer ErrorBoundary umschlossen. Ein fehlerhaftes Plugin darf nicht die ganze App crashen. Fallback-UI mit `trace_id` und „Neu laden"-Button | 1 Tag |
 | C-FE-TEST | Fehlende Frontend-Tests ergänzen: Vitest für neue Komponenten, API-Client-Tests, Hook-Tests | 3 Tage |
 | C-DOC | `docs/ui-design-guidelines.md` aktualisieren | 1 Tag |
 
-**Deliverables Phase C:** Stabile Navigation, Workspace-UI, Settings-Seite, Agentenverwaltung-Seite, TopBar Message/Notification UI auf dem zentralen Message-System, Tags, Custom Fields, Saved Filters, Dedup, Print, Onboarding, Theme-Basis, Accessibility und PWA mit reaktiviertem Service Worker.
+**Deliverables Phase C:** Stabile Navigation, Workspace-UI, Settings-Seite, Agentenverwaltung-Seite, TopBar Message/Notification UI auf dem zentralen Message-System, Tags, Custom Fields, Saved Filters, Dedup, Print, Onboarding, Theme-Basis, Accessibility, PWA mit reaktiviertem Service Worker und Frontend Error Boundaries.
 
 ---
 
@@ -491,7 +517,7 @@ Das bisher separate Notification-System und das Communication-/Message-System we
 |------|-------------|---------|
 | 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-JOB | **Background Processing** — große Imports/Exports über vorhandenes ARQ, Fortschritt/Status; keine neue Job-Infrastruktur. **Partial-Failure-Semantik**: bei Teilausfällen `partial_success` Status mit klarem Fehler-Report (welche Zeilen/Records committed, welche fehlgeschlagen), kein stummes Versagen, kein inkonsistenter Zustand | 1.5 Tage |
 | C5-CONTACT | **Contact Import/Export** — erster vollständiger fachlicher Handler auf gemeinsamer Basis | 1 Tag |
 | C5-COMPANY | **Company Import/Export** — zweiter fachlicher Handler, beweist Wiederverwendbarkeit ohne Universalmodell | 1 Tag |
 | C5-UI | **Modulare Import/Export UI** — fachmodulspezifisch nutzbare Mapping-/Preview-Komponenten | 2 Tage |
@@ -540,7 +566,7 @@ Hook-basiert: `do_action('entity.after_create/after_update/after_delete')` → `
 | 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-BULK | **Bulk-Restore** — Multi-Select im Trash ruft für jedes ausgewählte Objekt denselben vorhandenen Restore-Service mit Tenant-/Permission-Checks auf. Keine Batch-History-, Transaktionsgruppen- oder eigene Bulk-Undo-Architektur. **Partial-Failure-Semantik**: bei Teilausfällen `partial_success` mit Fehler-Report (welche Objekte restored, welche fehlgeschlagen), kein stummes Versagen | 1.5 Tage |
 | D-RET | Retention-Policy — EntityHistory älter als 90 Tage archivieren. GDPR-Hard-Delete | 0.5 Tage |
 | D-TEST | Tests: Restore funktioniert, Snapshots korrekt, Sensitive Fields ausgeschlossen, Mail-IMAP-Trash | 2 Tage |
 | D-DOC | `docs/test-strategy.md`, `docs/security_kernel.md` aktualisieren | 1 Tag |
@@ -595,7 +621,7 @@ Die spezifischen Suchen bleiben für gute Fach-UX erhalten, laufen technisch abe
 | 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-EVT | Auto-Indexierung: Mutation → Outbox → Worker → Index aktualisieren. Ein Weg, nicht Hook + EventBus parallel. **Index-Fehler-Handling**: bei Embedding-LLM-Fehlern, pgvector-Errors oder Timeouts → Retry über Outbox-DLQ, Dead-Letter bei permanentem Fehler, Index-Konsistenz-Check. Kein stummes Fehlschlagen von Suchergebnissen | 2.5 Tage |
 | E-IX-RE | Re-Indexierung: Batch-Reindex Kommando, Delete-Handling, Retry | 1 Tag |
 | E-DATA-LIFE | **Derived-Data Lifecycle für Search/Vector** — Correction/Delete/Erasure-Signal aktualisiert oder entfernt FTS-/Search-Dokumente und Embeddings reproduzierbar; Rebuild aus authoritative Quelle möglich. Retention-/Legal-Hold-Entscheidung bleibt fachlich konfiguriert | 1.5 Tage |
 | E-K-MAIL | Mail-spezifische Suche behalten, interne ILIKE-Logik aber auf `MailSearchProvider`/Unified Search Core umstellen | 1 Tag |
@@ -644,11 +670,11 @@ Kein vollständiger interner Chain-of-Thought; der Extended Trace ist ein expliz
 
 | Task | Beschreibung | Aufwand |
 |------|-------------|---------|
-| F-LOOP | `agent_loop.py` — ReAct-Loop mit LiteLLM `acompletion()` + `tools=` über zentralen LLM Client. Multi-Step-Reasoning, Tool-Call-Parsing, Error-Recovery, Graceful-Stop, Streaming — komplexer als ein einzelner LLM-Call | 5 Tage |
+| F-LOOP | `agent_loop.py` — ReAct-Loop mit LiteLLM `acompletion()` + `tools=` über zentralen LLM Client. Multi-Step-Reasoning, Tool-Call-Parsing, Error-Recovery, Graceful-Stop, Streaming — komplexer als ein einzelner LLM-Call. **LLM-Fehlerstrategie**: Provider-Rate-Limit → Backoff+Retry; Provider-Timeout → Graceful-Stop mit Fehlermeldung; Provider-Ausfall → Failover auf konfigurierten Backup-Provider; Max-Retries → Run beenden mit Fehler-Trace | 5.5 Tage |
 | F-CALL | Tool-Call-Parser — extrahiert function_calls, ruft ToolRegistry auf | 1 Tag |
 | F-CTX | Context-Builder — System-Prompt, Agent-Definition, relevanter User-/Tenant-Kontext, relevantes Memory, freigegebene Skills und Tool-Schemas. Zusätzliche API-/Domain-Dokumentation nur gezielt/on-demand; keine pauschale Vollinjektion der CRM-API-Spec | 2 Tage |
 | F-MAX | Max-Steps-Limit + Graceful-Stop | 0.5 Tage |
-| F-ERR | Error-Handling: Tool-Fehler → LLM bekommt Error-Message | 1 Tag |
+| F-ERR | Error-Handling: Tool-Fehler → LLM bekommt strukturierte Error-Message mit `ErrorCategory` (TRANSIENT/PERMANENT/PARTIAL). Transient → LLM kann entscheiden zu retry-en; Permanent → LLM muss Strategie ändern; Partial → LLM bekommt Teilerfolg-Report. Keine rohen Tracebacks an LLM | 1.5 Tage |
 | F-STR | SSE-Streaming mit **Standard- und Extended-Trace-Modus**: Status, Tool-Calls/-Results, Fortschritt, Kosten, Fehler, finale Antwort; optional zusätzlich strukturierte kurze Entscheidungsbegründungen/Zwischenzusammenfassungen | 1 Tag |
 | F-DEF | Bestehende AgentDefinition CRUD/API/Versionierung verifizieren und nur fehlende Felder/Contracts für Runtime, Skills, Trigger und Limits ergänzen | 1 Tag |
 | F-AIUSE | **AI Use-Case Metadata** — für relevante Agent-/AI-Funktionen `intended_purpose`, Owner, Datenklassen, zugelassene Provider/Modelle, zulässige Aktionen, Oversight-Policy und konfigurierbare Risikoklasse erfassen. Kein juristischer Auto-Klassifizierer | 1 Tag |
@@ -680,7 +706,7 @@ Kein vollständiger interner Chain-of-Thought; der Extended Trace ist ein expliz
 | 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), AI-Use-Case-/Transparency-Metadaten, Provider/Data-Policy-Enforcement, Standard+Extended Trace, trigger-basierte Proaktivität, UI Control ohne Permission-Bypass, zentraler ApprovalRequest-Kern + Human-Oversight-Record, Workstream-Ausgabe, Agent UI und 4 Pre-Built Agenten.
+**Deliverables Phase F:** ReAct-Agenten auf vorhandener Agentenbasis, kleiner Skill-Baustein, Tool-/Skill-Calling, Permission-Modell (User/Run-as ∩ Agent ∩ Skill ∩ Tool), AI-Use-Case-/Transparency-Metadaten, Provider/Data-Policy-Enforcement, Standard+Extended Trace, LLM-Fehlerstrategie (Rate-Limit-Backoff, Provider-Failover, Timeout-Graceful-Stop), strukturiertes Tool-Error-Handling mit ErrorCategory, trigger-basierte Proaktivität, UI Control ohne Permission-Bypass, zentraler ApprovalRequest-Kern + Human-Oversight-Record, Workstream-Ausgabe, Agent UI und 4 Pre-Built Agenten.
 
 ---