147 lines
14 KiB
Markdown
147 lines
14 KiB
Markdown
# 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
|
|
- [x] **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
|
|
- [x] **Widgets** aus Sales/Projekte/Tasks/HR/~~KI~~ (entfällt [[AD-26]])/Activity/Comms; **Widget-Registry voll gebaut** (Custom-Widgets/Drag&Drop → v2)
|
|
- [x] **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)
|
|
- [x] 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
|
|
- [x] Konnektor `tenantHasModule('dashboard')` (Dashboard gated)
|
|
- [x] 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.
|