--- module: 20 title: Dashboard / Reporting phase: 1 status: detail-spec-draft last_updated: 2026-05-08 session_source: brainstorming-session-2026-05-07-2206.md related_lps: [LP-2, LP-3, LP-9, LP-10] spec_style: requirements-pur --- # Modul 20 — Dashboard / Reporting > **Detail-Spec gemäß LP-9.** Aggregierte KPIs aus allen anderen Modulen. Pro Rolle konfigurierbar. ## Themenblöcke ``` A. Datenmodell (Dashboard, DashboardLayout, Widget, WidgetInstance) B. Menü-Struktur und Routes C. Widget-Katalog (verfügbare Widget-Typen + Datenquellen) D. Dashboard-Layout (User-Customizing) E. Default-Layouts pro Rolle F. Permissions-Anwendung G. Performance & Realtime-Updates ``` --- ## Block A — Datenmodell ``` Dashboard — Dashboard-Definition pro Tenant (mehrere möglich) DashboardLayout — User-spezifisches Layout pro Dashboard WidgetCatalog — Plattform-weite Widget-Definitionen (Code-Registry, nicht DB) WidgetInstance — konkrete Widget-Anwendung in einem Layout ``` ### Dashboard - `id`, `tenant_id`, `name`, `description` - `is_default_for_role` (optional Enum: `gf | sales_lead | sales_rep | pl | office | marketing | monteur`) - `is_shared` (Boolean — gemeinsames Tenant-Dashboard vs. nur User-spezifisch) - `created_by_user_id`, `archived_at` ### DashboardLayout - `id`, `tenant_id`, `dashboard_id`, `user_id` (NULL bei `is_shared=true`) - `widgets[]` (JSON-Array von WidgetInstance-IDs mit Position + Größe) - `layout_data` (JSON — Grid-Position pro Widget) - `updated_at` **Logik:** - Pro User pro Dashboard ein Layout (User passt individuell an) - Falls Dashboard `is_shared=true`: ein gemeinsames Layout, von Tenant-Admin verwaltet ### WidgetInstance - `id`, `tenant_id`, `widget_catalog_key` - `config` (JSON — Widget-spezifische Konfiguration: Filter, Zeitraum, Anzeige-Optionen) - `position`, `size` ### WidgetCatalog (Code-Registry) Plattform-weit definierte Widget-Typen: - Schlüssel + Default-Config-Schema - Render-Komponente - Datenquelle (welche Module / welche Permissions) - Erweiterbar pro Modul --- ## Block B — Menü-Struktur und Routes ``` /{tenant}/ → Default-Dashboard (nach Login) /{tenant}/dashboard → expliziter Dashboard-Pfad /{tenant}/dashboard/:id → Spezifisches Dashboard (bei Multi-Dashboard-Tenants) /{tenant}/dashboard/:id/edit → Layout-Edit-Modus /{tenant}/admin/dashboards → Tenant-Dashboard-Verwaltung /{tenant}/admin/dashboards/:id → Editor für shared Dashboard ``` **Default-Routing-Logik:** 1. User hat persönliches Layout für ein Dashboard → das wird gezeigt 2. Sonst: Dashboard mit `is_default_for_role` matchend zur User-Rolle 3. Sonst: Tenant-Default-Dashboard (shared) 4. User-Switcher (oben in Dashboard-View): zeigt verfügbare Dashboards --- ## Block C — Widget-Katalog ### Sales (M3) | Widget-Key | Daten | Permission | |---|---|---| | `sales.pipeline_kpis` | Anzahl Deals × Stage, Aggregat-Volumen | `deals.read_aggregates` | | `sales.deal_trend` | Anzahl/Volumen über Zeitraum | `deals.read_aggregates` | | `sales.revenue_forecast` | Forecast (Volumen × Wahrscheinlichkeit) | `deals.read_aggregates` | | `sales.salesperson_performance` | Pro Vertriebler: Deals, Volumen, Won-Rate, Aktivitäts-KPIs | `deals.read_aggregates` | | `sales.lost_reasons` | Lost-Reason-Verteilung | `deals.read_aggregates` | | `sales.stage_conversion` | Conversion-Rate pro Stage-Übergang | `deals.read_aggregates` | | `sales.my_open_deals` | Eigene aktive Deals als Liste | `deals.read_own` | ### Projects (M4) | Widget-Key | Daten | Permission | |---|---|---| | `projects.pipeline_kpis` | Anzahl Projects × Stage, Volumen | `projects.read_aggregates` | | `projects.project_overview` | Status-Verteilung | `projects.read_aggregates` | | `projects.utilization` | MA-Auslastung | `plantafel.read_all` + `projects.read_aggregates` | | `projects.open_defects` | Offene Mängel aus Acceptance | `projects.read_all` | | `projects.my_active_projects` | Eigene aktive Projekte | `projects.read_own_member` | ### Tasks (M26) | Widget-Key | Daten | Permission | |---|---|---| | `tasks.my_tasks` | Eigene offene Tasks (heute/Woche/überfällig) | `tasks.read_own` | | `tasks.team_completion` | Team-Task-Completion-Rate | `tasks.read_all` | ### Activity (M1) | Widget-Key | Daten | Permission | |---|---|---| | `activity.my_recent` | Eigene letzte Activities | `crm.read_*` | | `activity.team_recent` | Team-Activities chronologisch | `crm.read_all` | ### Communication (M9, M12) | Widget-Key | Daten | Permission | |---|---|---| | `comms.unread_emails` | Anzahl ungelesene Mails | `email.read_*` | | `comms.calls_today` | Anzahl Anrufe heute | `telephony.read_*` | ### Greetings & Status | Widget-Key | Daten | Permission | |---|---|---| | `general.greeting` | „Guten Morgen, Noah!" + Wetter optional | (alle) | | `general.kwp_status` | KWP-Sync-Status, letzte Sync | `tenant.admin` | | `general.tenant_health` | Subscription-Status, Usage-Anzeige | `tenant.admin` | ### HR (M14) | Widget-Key | Daten | Permission | |---|---|---| | `hr.team_today` | Wer ist heute da / Urlaub / krank | `hr.read_*` | | `hr.pending_requests` | Offene Genehmigungs-Anträge | `hr.approve_*` | ### AI (M18) | Widget-Key | Daten | Permission | |---|---|---| | `ai.suggestions` | KI-Vorschläge basierend auf Tenant-Kontext | `ai.read` | --- ## Block D — Dashboard-Layout (User-Customizing) ### Edit-Modus (`/{tenant}/dashboard/:id/edit`) **Benötigte UI-Elemente:** - Grid-Layout-Komponente (Drag-&-Drop + Resize) - Widget-Catalog-Picker (gegated nach User-Permissions) - Pro Widget-Instance: Konfigurations-Funktion (Widget-spezifisch) - Funktionen: Widget hinzufügen / verschieben / resizen / löschen - Save-Funktion - Reset-Funktion (zurück zum Role-Default) **Operationen:** - Widget hinzufügen aus Catalog - Position + Größe ändern - Widget-Config editieren - Widget entfernen - Dashboard duplizieren (als Vorlage für anderen Dashboard) - Dashboard löschen **Klartext-Hinweise:** - Widget ohne Permission im Catalog ausgegraut: *„Hierfür benötigst du erweiterte Berechtigungen"* - Layout-Reset: Bestätigungs-Dialog *„Dein angepasstes Layout wird durch das Standard-Layout deiner Rolle ersetzt."* --- ## Block E — Default-Layouts pro Rolle (SHK-Template) Beim Tenant-Anlegen werden 7 Role-Default-Dashboards geseedet (`is_default_for_role` gesetzt, `is_shared=true`). Alle Default-Dashboards sind **deklarativ als Branchen-Template** gespeichert (LP-3 + AV #3). ### GF-Dashboard `general.greeting`, `sales.pipeline_kpis`, `sales.revenue_forecast` (3-Monats), `sales.salesperson_performance`, `projects.pipeline_kpis`, `projects.utilization`, `projects.open_defects`, `general.kwp_status`, `general.tenant_health`, `hr.team_today` ### Vertriebsleiter-Dashboard `general.greeting`, `sales.pipeline_kpis`, `sales.deal_trend` (Monats-Trend), `sales.salesperson_performance`, `sales.lost_reasons`, `sales.stage_conversion`, `tasks.team_completion` ### Vertriebler-Dashboard `general.greeting`, `sales.my_open_deals`, `tasks.my_tasks`, `comms.unread_emails`, `comms.calls_today`, `activity.my_recent` ### Projektleiter / Bauleiter-Dashboard `general.greeting`, `projects.my_active_projects`, `projects.open_defects` (eigene), `projects.utilization` (eigenes Team), `tasks.my_tasks`, `hr.team_today` ### Büro / Backoffice-Dashboard `general.greeting`, `projects.pipeline_kpis`, `tasks.my_tasks`, `comms.unread_emails`, `hr.pending_requests`, `general.kwp_status` ### Marketing-Dashboard `general.greeting`, `sales.deal_trend`, `sales.lost_reasons`, `sales.stage_conversion` ### Monteur-Dashboard (Mobile-First, LP-2) *„Meine Termine heute"* (eigene ScheduleEntries), *„Meine aktiven Projekte"*, *„Meine Tasks"*, optional KI-Walkthrough-Hinweise --- ## Block F — Permissions | Permission | Erlaubt | |---|---| | `dashboard.read` | Default-Dashboard sehen | | `dashboard.customize` | Eigenes Layout anpassen | | `dashboard.create` | Neues persönliches Dashboard anlegen | | `dashboard.share` | Dashboard als shared markieren | | `dashboard.admin` | Tenant-Admin-Verwaltung (Default-Layouts pro Rolle, shared Dashboards) | ### Bundle-Mapping | Bundle | Atomare Permissions | |---|---| | `dashboard.basic` | `dashboard.read` + `dashboard.customize` | | `dashboard.power` | obigen + `dashboard.create` | | `dashboard.admin` | alle | ### Default-Rollen-Zuweisung | Rolle | Permission | |---|---| | GF | `dashboard.admin` | | Vertriebsleiter / PL / Büro | `dashboard.power` | | Vertriebler / Marketing / Monteur | `dashboard.basic` | ### Widget-Sichtbarkeit - Pro Widget gilt die Permission des Quellen-Moduls (z.B. `sales.pipeline_kpis` braucht `deals.read_aggregates`) - User ohne Permission sieht das Widget nicht im Catalog (Permissions-aware-Default) - Bei Rollen-Wechsel mit verlorenen Widget-Permissions: Widgets werden ausgeblendet mit Klartext im Edit-Modus --- ## Block G — Performance & Realtime-Updates ### Caching-Strategie - Pro Widget-Instance Cache mit TTL (Default 60 Sek, Widget-spezifisch konfigurierbar) - Cache-Schlüssel: `tenant_id + widget_key + config_hash + user_id` - Cache-Invalidierung bei relevanten Änderungen ### Realtime-Updates - WebSocket-Push an aktive Dashboard-Sessions bei wichtigen Änderungen (Deal-Won, neuer Lead, Mängel-Acceptance) - Subtle-Animation bei Update (Designer-Detail) - Opt-Out-Option pro User: *„Live-Updates pausieren"* ### Lazy Loading - Widgets werden lazily geladen (nur sichtbare im Viewport) - Skeleton-State first-render ### Aggregat-Berechnung - Server-side, nicht client-side - Bei großen Datasets: Pre-Calculated-Aggregat-Tables, asynchron via Cron erneuert - Klartext bei veralteten Aggregaten: *„Daten zuletzt aktualisiert vor X Minuten"* --- ## Architektur-Vorschriften (Querschnitt) - **LP-2:** Monteur-Dashboard ist mobile-first - **LP-3, AV #3:** Default-Dashboards sind deklaratives Branchen-Template - **AV #5:** Permissions-aware-Default — Widgets gegated nach Quellen-Modul-Permissions - **AV #6:** Audit-Trail für Layout-Änderungen (wer hat shared Dashboard geändert) --- ## Detail-Spec-Status: DRAFT Modul 20 komplett spec'd. **Offene Detail-Punkte:** - Konkrete Widget-Konfigurations-Schemas pro Widget-Typ (Implementierungs-Detail) - Grid-Layout-Library-Wahl (Boilerplate-Entscheidung, z.B. react-grid-layout) - WebSocket-Strategie (gemeinsam mit M13 Chat) - KI-Widget-Verhalten konkretisieren (M18-Spec-Kontext) - Konkrete Aggregat-Cache-Invalidierungs-Strategie