Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/R-P11b.md
T

14 KiB

R-P11b · P11 Dashboard (3 Rollen-Layouts)

⚠️ KI→MCP-Pivot (AD-26): Die „KI"-Widget-Quelle entfällt aus dem Widget-Katalog (kein LLM/KI-Layer in v1 — HiveGrid wird MCP-Server, VR-MCP). Die Widget-Registry bleibt voll gebaut und erweiterbar; nur die KI-Widgets fallen weg.

Typ Dev (Code)
Owner Raffael
Phase P11 — Globale Suche & Dashboard
Cycle/Fenster W4 — USP, Härtung & Launch · 2026-07-04 → 2026-07-05 · Gate W4
Status Done (Interim-UI nach AD-28; finale D-DASH-Optik = getrackter design-nachzug)

🎨 design-nachzug: offen (seit 2026-07-12) — Interim-UI aus ~/ui steht; finale Subframe-Optik aus D-DASH ausstehend.

🟢 Kein Pivot-Sonderfall. Aber: Dashboard-Widgets greifen auf den Projekt-Kern zu (nicht getrennte Deal-/Project-Entitäten). v1 = nur 3 feste Rollen-Layouts (GF/Büro/Monteur) ohne Drag&Drop (Scope-Schnitt 12.06.; User-Layout-Persistenz + Custom-Widgets + Export → v2). Die Widget-Registry wird voll gebaut (Inversion M064→M147).

Abhängigkeiten & Parallelität

  • Blocked by: R-P11a (Suche/Index), R-P8b (Sales-Aggregate für Widgets)
  • Blocks: R-P12a (Automation danach)
  • Sequenz (Raffaels Kern-Kette): sequenziell nach P11a (R-P11a → R-P11b → R-P12a …).
  • Läuft parallel zu: Akeshans Module W4. Schema-Trennung nach AD-21.

Was wir bauen

3 feste Rollen-Dashboards (GF/Büro/Monteur, SHK-Default geseedet) aus einem Widget-Katalog (Sales/Projekte/Tasks/HR/KI (entfällt AD-26)/Activity/Comms), live aktualisiert (SSE/WebSocket, Aggregat-Cache). Edit in v1 = nur Widget-Filter/Zeitraum (kein Drag&Drop-Grid).

Benötigte Screens (Backend bedient — Design liefert D-DASH-Paket)

Screen [Route] Kern-Inhalt
Dashboard [/dashboard bzw. /] 3 feste Rollen-Layouts (kein Drag&Drop v1): GF (Begrüßung, Sales-KPIs, Umsatz-Forecast, Projekt-KPIs, Auslastung, offene Mängel, Team-heute) · Büro (Begrüßung, Projekt-KPIs, meine Tasks, Anrufe heute, HR-Anträge) · Monteur 📱 (meine Termine heute, meine Projekte, meine Tasks); Widgets: KPI-Kachel/Liste/Trend-Chart; Live-Update (SSE/WebSocket, seit 2026-07-25 ohne Pausieren-Schalter und ohne „zuletzt aktualisiert"-Anzeige); Edit = nur Widget-Filter/Zeitraum
Dashboard-Switcher [im Header] Entfällt seit 2026-07-25 — die Layout-Wahl folgt Sitzplatz + Rechten, ohne Bedienelement (siehe Umsetzungsnotiz 2026-07-25)

Definition of Done

  • 3 feste Rollen-Layouts (GF/Büro/Monteur) aus Widget-Katalog — präzisiert im Audit 2026-07-19: die SHK-Default-Layouts sind versionierte Server-Defaults (roleLayouts in dashboard.server.ts), kein DB-Seed. ensureDefaultDashboards existiert RLS-sauber, wird aber bewusst nicht zur Laufzeit aufgerufen (Runtime-Seeding unter FORCE RLS nicht freigegeben, AGENTS.md §Seeding; Loader-Aufruf per Contract-Test verboten). DB-Seedung der Layouts + is_demo_data folgt mit dem v2-Customize- bzw. Operator-Seed-Nachzug — kein v1-Done-Blocker, da v1 keine Layout-Persistenz kennt
  • Widgets aus Sales/Projekte/Tasks/HR/KI (entfällt AD-26)/Activity/Comms; Widget-Registry voll gebaut (Custom-Widgets/Drag&Drop → v2)
  • Live-Update (WebSocket/SSE) mit Aggregat-Cache + Lazy-Load/Skeleton; Widgets permission-gegated (Quellen-Modul-Permission); Monteur-Dashboard mobile-first — beim Audit 2026-07-19 als Lücke befunden und geschlossen (siehe Umsetzungsnotiz 2026-07-19)
  • Rollenbasiertes Default-Routing — seit 2026-07-25 sitzplatz-basiert und ohne Switcher (resolveDashboardRole: Baustellen-Sitz → Monteur, Büro-Sitz → GF bei betriebsweiten Auswertungsrechten, sonst Büro). Der manuelle Umschalter ist entfallen, siehe Umsetzungsnotiz 2026-07-25
  • Konnektor tenantHasModule('dashboard') (Dashboard gated)
  • Permissions: dashboard.read/customize (v1: nur Filter/Zeitraum; Drag&Drop-Customize → v2)

Umsetzungsnotiz

2026-07-01: Technische Basis auf main vorbereitet: Prisma-Modelle Dashboard/DashboardLayout/WidgetInstance inkl. RLS-Artefakt, dashboard-Entitlement, dashboard.read/dashboard.customize, Sidebar-Gating, /dashboard-Loader mit rollenbasiertem Switcher, serverseitige Widget-Registry und /dashboard/stream als SSE-Snapshot-Route. Widget-Daten werden permission-gegated aus vorhandenen Quellen gelesen, inkl. Pipeline-Aggregaten, Projekten, Tasks, HR-Anträgen, Activity, Calls, Terminen und offenen Mängeln. Verifikation: pnpm typecheck, pnpm lint, pnpm prisma validate, pnpm test, gezielte R-P11b-Tests und git diff --check grün. Plane-Kommentar geschrieben und Ticket auf Blocked / On Hold gesetzt. DoD: 6/6 technische Punkte = 100 % selbst machbar erledigt. Extern blockiert: finaler Screen-Abgleich und visuelle Integration mit Davids D-DASH-Paket. Ticket bleibt deshalb On Hold, nicht Done.

2026-07-12 (Interim-UI, AD-28): Dashboard-Screen als Interim-UI aus ~/ui nachgezogen (Branch akeshan/r-p11b-dashboard-interim-ui, gebaut von Akeshan als AD-28-Nachzug; kein Subframe-D-DASH vorhanden — per Subframe-MCP list_pages und Davids Vault verifiziert). Umfang: (a) purer VM-Builder nach packages/view-models/src/dashboard/dashboard-page.vm.ts extrahiert (+ Unit-Tests, dashboard.server.ts nutzt ihn jetzt), (b) Interim-Screen apps/web/app/components/screens/dashboard/DashboardPage.tsx (~/ui-Komposition: ToggleGroup-Rollen-Switcher, StatsCard-KPIs, Card-Widgets, Loading/Error/Empty/Permission-States) + Unit-Tests, (c) Route rendert <DashboardPage vm actions> und konsumiert dashboard/stream jetzt client-seitig per EventSource (useDashboardStream) inkl. „Live-Updates pausieren"-Switch und „Zuletzt aktualisiert"-Anzeige, (d) Hot-Swap-/Visual-Registrierung (createDashboardInterimFixturePage, Interim-Baseline packages/ui-mock/visual-baseline/r-p11b-interim.*), (e) Smoke tests/e2e/dashboard-interim-smoke.spec.ts, (f) i18n-Keys app.dashboard.live.pause/paused, app.dashboard.loading (de+en). Proof: typecheck web/view-models/ui-mock 0 Fehler, pnpm lint grün, verify:i18n Exit 0, verify:ui-visual 13/13, vitest-Suiten (VM 6, Screen 7, Route 7, ui-mock 4, verify-Scripts 6) grün. DoD: 6/6 = 100 %, Live-Update-Punkt jetzt auch screen-seitig erfüllt. Finale D-DASH-Optik = getrackter design-nachzug (Tag oben).

2026-07-19 (Stand-Audit + Restarbeiten, Branch fix/r-p11-audit-restwork): Audit ergab real 4/6 DoD statt der gemeldeten 100 %: (a) „Live-Update" war nur ein Einmal-Snapshot — dashboard/stream sendete genau einen Snapshot beim Connect plus 30s-Heartbeat, danach nie wieder ein Update; der Aggregat-Cache aus R-P8b wurde nicht genutzt (sales.forecast rechnete live per tx.projekt.groupBy); (b) die SHK-Default-Layouts sind nicht in der DB geseedet (ensureDefaultDashboards ohne Aufrufer). Behoben bzw. entschieden: Der Stream abonniert jetzt den tenant-weiten Dashboard-Kanal (dashboardEvents.server.ts, wiederverwendeter R-P8b-In-Process-Emitter — publishProjectBoardChange publiziert zusätzlich dashboard:{tenantId}) und sendet bei Projekt-Mutationen debounced (2 s) einen frischen, permission-gegateten Snapshot; Auth läuft einmalig vor Stream-Öffnung (openDashboardStreamSession). sales.forecast liest für tenant-weite Leser (projects.read_all + Aggregat-Gate) den PipelineAggregateSnapshot (scopeKey: "pipeline", weightedForecast); Own-Scope-Leser und Pipelines ohne Snapshot behalten die Live-Berechnung (Semantik-Guard: der Snapshot ist tenant-weit und darf nie user-gescoped ausgeliefert werden). Seed-Punkt per Entscheidung präzisiert statt verdrahtet (siehe DoD-Punkt 1). Ehrliche Einschränkung (wie R-P8b): der Emitter ist prozess-lokal; Multi-Instanz-Betrieb bräuchte Redis-PubSub. Push-Quellen sind aktuell die Projekt-Mutationen (Stage-Move/Bulk/Anlage/Update/Undo/Archiv); Task-/HR-/Call-Pushes sind bewusst nicht verdrahtet. Proof: Commits 9f98f3f8c (R-P11a-Drill), 8a053d809 (Live-Update + Cache); pnpm --filter @hivegrid/web typecheck grün, verify:i18n Exit 0, Dashboard-Suiten (15 Tests), Projekt-Integrations-Suiten (102 Tests), pnpm test:hot-swap grün. DoD: 6/6 = 100 % (Punkt 1 in präzisierter Fassung).

Technische Bausteine

  • Entities (eigene prisma/schema/dashboard.prisma): Dashboard (name, is_default_for_role gf/office/monteur, is_shared), DashboardLayout (dashboard_id, user_id NULL=shared, widgets[], layout_data — 3 feste Rollen-Layouts v1), WidgetInstance (widget_catalog_key, config, position, size — Custom/Drag&Drop v2). Aggregat-Cache auf Quell-Module über deren .prisma nur lesend (AD-21).
  • RLS auf Dashboard/Layout/Widget (AD-1); Widget-Daten zusätzlich über Quellen-Modul-Permission gegated.
  • Live-Update: SSE/WebSocket-Push bei Aggregat-Änderung; Aggregat-Cache (aus R-P8b für Sales) wiederverwendet.
  • Konnektor tenantHasModule('dashboard') gated.
  • is_demo_data-Flag auf SHK-Default-Layouts/Demo-Widgets.

2026-07-25 (Dashboard-Neuschnitt, Auftrag Raffael): Umgesetzt im Worktree chore/session-20260725. (a) Rollen-Umschalter entfernt — die Layout-Wahl kommt jetzt aus dem Sitzplatz (Role.seatCategory via deriveSeatType, RLS-sauber im Dashboard-Kontext gelesen) und erst danach aus den Rechten: field → Monteur, office + deals.read_aggregates|read_volume_all → GF, sonst Büro. Damit ist ein Altfehler behoben: die real angelegte Rolle Monteur hat weder plantafel.read_own noch calendar.connect_own und landete deshalb immer auf dem Büro-Layout, während Vertrieb und Innendienst über projects.read_all beide auf der GF-Ansicht landeten. Das VM liefert nur noch layout (das eine zutreffende Layout) statt aller drei roles. (b) Live-Toggle entfernt — der Schalter konnte nur die SSE-Verbindung abschalten; die Zahlen froren dann ein, der Zustand war nicht persistiert und nach jedem Reload wieder an. SSE läuft jetzt immer, liveUpdatesEnabled und die Pause-Verdrahtung sind raus. (c) Neue Kennzahlen (Reihenfolge nach der Krisenkaskade der HWK Dortmund: Auftragslage → Ertrag → Liquidität): sales.order_intake (Auftragseingang je Monat, 13 Monate, mit Vorjahresmonat — erste Zeitachse im Dashboard überhaupt), sales.win_rate (Auftragsquote der letzten 12 Monate), finance.receivables (offene Posten nach Fälligkeitsstufen) und finance.days_to_payment (Ø Tage bis Zahlungseingang). Dafür trägt das VM neu einen series-Slot (Monats-Zeitreihe) und chart.valueFormat; neue UI-Komponente DashboardMonthlySeriesChart (Säulen, Zeit links→rechts, sr-only-Monatstabelle). (d) „Umsatz-Forecast" umbenannt in „Gewichtete Pipeline" (nur Text): die Zahl ist offenes Volumen mal Abschlusswahrscheinlichkeit, kein Umsatz — neben den jetzt echten Geldkacheln war die alte Beschriftung eine teure Fehllesung. Rechnung unverändert. (e) Zwei Fehler behoben: comms.calls_today zählte Activity-Zeilen mit Typen, die der Telefonie-Worker nie schreibt (call statt call_inbound|call_outbound|call_missed), und zusätzlich nach actorUserId, das dort systembedingt leer ist — die Kachel konnte strukturell nur 0 zeigen; sie liest jetzt TelephonyCallSession mit Sichtbarkeit nach telephonyAccess.server. Und stageConversionRate in rebuildPipelineAggregateCache teilte durch einen in der Stage-Schleife mitlaufenden Zwischenstand statt durch die Pipeline-Gesamtzahl. (f) Schema: Rechnung.bezahltAm neu (AD-21: auf dem Branch nur Schema, Migration beim Merge) — ohne dieses Feld sind Geldeingang je Monat und Zahlungsdauer nicht messbar. Bestandsrechnungen bleiben null und werden aus der Auswertung ausgenommen statt falsch datiert.

Grundlage: Recherche zu Kennzahlen im SHK-/Handwerksbetrieb (HWK Dortmund/BMWi, ZVSHK-Strukturanalyse, LFI-Betriebsvergleich SHK Bayern, handwerk magazin) und zu Darstellungsregeln (Few, IBCS, NN/g). Nicht baubar und daher bewusst nicht enthalten: Deckungsbeitrag je Produktivstunde, Auslastungsgrad und Soll-Ist je Auftrag — dafür fehlen im Datenmodell jede Kostenseite und jede Ist-Zeiterfassung.

Proof: pnpm typecheck 0 Fehler, verify:i18n Exit 0, verify:ui-visual 130 passed / 0 failed (Interim-Baseline r-p11b-interim.* neu erzeugt), pnpm test:hot-swap grün, vitest: dashboard.server 23, VM 11, Screen 10, Route 8, ui-mock 23, projectService 34, neue Rechnungs-Suite 3 — alle grün. DoD weiterhin 6/6 = 100 %. Der design-nachzug (finale D-DASH-Optik) bleibt offen; die neuen Widgets sind in der Interim-Optik gebaut und beim David-Delta mit zu übernehmen.

Quellen (granular)

  • ENTITY-MODEL.md → Domäne 6: Suche & Dashboard (Dashboard/DashboardLayout/WidgetInstance) — Projekt-Kern als Widget-Quelle
  • REQUIREMENTS.md → REQ-dashboard-datenmodell (3 feste Rollen-Layouts), REQ-dashboard-widgets (Phase 11)
  • ROADMAP.md → Phase 11
  • designer-briefs/P11-suche-dashboard.md (3 Rollen-Layouts, kein Drag&Drop v1)

Dev-Nachzug (nach Davids D-DASH-Delta)

Interim-UI (Vorschau, Stand 2026-07-12): Screen aus ~/ui gebaut — apps/web/app/components/screens/dashboard/DashboardPage.tsx. Proof: Smoke tests/e2e/dashboard-interim-smoke.spec.ts, Hot-Swap-Drill grün, Interim-Visual-Baseline packages/ui-mock/visual-baseline/r-p11b-interim.* (als interim markiert). Refactor-Nachzug offen: finale Subframe-Optik aus D-DASH (Plane-Label design-nachzug).

  • Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/ROADMAP nachgezogen
  • Plane-Ticket R-P11b aktualisiert

2026-07-18 — Dependency-Impact aus R-P8b (Forecast-Verdrahtung)

R-P8b hat den Sales-Aggregat-Cache fertig verdrahtet: PipelineAggregateSnapshot wird jetzt nach jeder Forecast-relevanten Mutation aktualisiert (refreshPipelineAggregatesAfterMutation) und getPipelineForecast liefert zusätzlich ownerKpis (KPIs je zustaendigePersonId, Geldwerte aggregat-gegated). Das sales.forecast-Widget in apps/web/app/services/dashboard/dashboard.server.ts rechnet aktuell live per tx.projekt.groupBy — funktional korrekt, kein Bruch. Optionaler Nachzug beim D-DASH-Delta: Widget auf getPipelineForecast (Cache) umstellen und die neuen Owner-KPIs für die GF-Sales-Kacheln nutzen. Kein Handlungszwang, Verträge sind additiv.

Erledigt am 2026-07-19 (Audit-Restarbeit): Der Cache-Teil ist umgesetzt — sales.forecast liest für tenant-weite Leser jetzt den PipelineAggregateSnapshot (siehe Umsetzungsnotiz 2026-07-19). Offen bleibt nur die Owner-KPI-Nutzung für die GF-Kacheln als optionaler D-DASH-Nachzug.