Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M20-dashboard.md
T

10 KiB
Raw Blame History

module, title, phase, status, last_updated, session_source, related_lps, spec_style
module title phase status last_updated session_source related_lps spec_style
20 Dashboard / Reporting 1 detail-spec-draft 2026-05-08 brainstorming-session-2026-05-07-2206.md
LP-2
LP-3
LP-9
LP-10
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