0 Fork 0

Files

T

dejanandClaude Opus 5 cdf9066076 docs(scope): Analytics und Dashboard als zwei Features festhalten

Klarstellung aus der Abstimmung: Der Prototyp wurde bisher als 'das Dashboard'
bezeichnet, tatsächlich sind es zwei Features mit unterschiedlichem Zweck.

Analytics beantwortet 'warum ist das so' — mehrerer Seiten, seitenübergreifender
Zeitraum- und Dimensionsfilter, fachlich geschnitten. Das Dashboard beantwortet
'wie ist meine Lage' — Begrüßungsbildschirm, rollenbezogen, Widgets. Es zeigt die
wichtigsten Charts aus Analytics, ist aber nicht darauf beschränkt: HR-Anträge
('2 neue Anträge'), Aufgaben und Termine gehören ebenfalls dorthin.

Die Software sieht das bereits vor. DashboardWidgetDomain kennt 'hr',
DashboardWidgetKind kennt 'list', und der Designer-Brief P11 nennt HR-Anträge
wörtlich im Büro-Dashboard. Neu ist nicht der Scope der Software, sondern das
Verhältnis zu diesem Prototyp.

Drei Stellen bekommen dadurch einen anderen Zuschnitt: die Seite 'Übersicht'
überschneidet sich mit dem Dashboard, der Handlungsbedarf ist eher ein
Dashboard-Element, und Charts brauchen als Widgets einen eigenen Zeitraum, weil
das Dashboard keinen globalen Filter hat.

Sechs offene Punkte sind in docs/SCOPE-ANALYTICS-DASHBOARD.md Abschnitt 5
festgehalten. Nichts davon ist entschieden, am Code ist nichts geändert.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QPeZNwSeU7qG3RRCwaxEZX

2026-08-29 19:51:55 +02:00

6.8 KiB

Raw Blame History

Übergabe an die Entwicklung

Vor dem Einbau lesen: docs/SCOPE-ANALYTICS-DASHBOARD.md. Der Zuschnitt zwischen Analytics und Dashboard ist noch offen und betrifft die Übersichtsseite und den Handlungsbedarf.

Dieser Prototyp liefert Gestaltung und Interaktion, nicht die Anbindung. Was echt ist, was Attrappe ist und was beim Einbau zu tun bleibt:

1. Was fertig ist und übernommen werden kann

Bereich	Datei(en)	Zustand
Kennzahlen-Berechnung	`features/dashboard/data/calculations.ts`	Reine Funktionen über typisierten Eingangsdaten — direkt übernehmbar
Chart-Theme	`features/dashboard/utils/chartTheme.ts`	Carbon-Tokens, Palette, Achsen-Props, Margins
Formatierung	`features/dashboard/utils/formatters.ts`	Deutsche Zahlen-, Währungs- und Datumsformate
Chart-Komponenten	`features/dashboard/components/charts/`	Vollständig, mit Leerzuständen und Tooltips
Karten & Tabellen	`features/dashboard/components/cards/`, `tables/`	Vollständig
Filtersystem	`features/dashboard/context/FilterContext.tsx`, `data/filtering.ts`	State und Relevanzlogik fertig
Seitenaufbau	`features/dashboard/pages/`	Reine Komponenten `({ vm })` — kein Store-Zugriff, direkt übernehmbar
View-Model-Builder	`features/dashboard/view-models/*.vm.ts`	Reine Funktionen `(daten, filter) → VMState<…>`; im Loader wiederverwendbar
Seitenzustände	`components/layout/SeitenZustand.tsx`	idle · loading · empty · error ausgestaltet

2. Was echte Logik braucht

2.1 Datenquelle austauschen

Alles hängt an einer Stelle: features/dashboard/data/seed.ts exportiert DATENSATZ vom Typ Datensatz. Diesen Export durch echte Daten ersetzen — Loader, Server-Query oder Service, je nach Architektur. Alle Berechnungen und Komponenten arbeiten unverändert weiter.

Feldzuordnung zu den HiveGrid-Entities steht in docs/DATENMODELL.md.

Achtung Zeitbezug: features/dashboard/utils/dateUtils.ts definiert HEUTE als festen Stichtag (30.07.2026), damit der Prototyp reproduzierbar bleibt. Beim Einbau durch new Date() ersetzen — die Konstante wird an elf Stellen verwendet, alle über den Import.

2.2 Filter serverseitig anwenden

Aktuell wird komplett clientseitig gefiltert (data/filtering.ts). Bei echten Datenmengen gehört das in die Query. Der State im FilterContext lässt sich dafür in URL-Parameter serialisieren; die Relevanzlogik (FILTER_RELEVANZ) bleibt clientseitig, weil sie nur die Anzeige steuert.

2.3 Aktionen ohne Wirkung

Diese Elemente lösen bewusst nur einen Hinweis-Toast aus:

Element	Wo	Erwartetes Verhalten
Export (Seitenkopf)	`components/layout/PageHeader.tsx`	PDF-/CSV-Export der Ansicht
Teilen	`components/layout/PageHeader.tsx`	Link mit eingefrorenen Filtern
Aktualisieren	`components/layout/PageHeader.tsx`	Daten neu laden
„Als Bild exportieren"	`components/cards/ChartCard.tsx`	PNG-Export des Charts
Einträge in „Handlungsbedarf"	`components/cards/AlertList.tsx`	Absprung in die jeweilige Arbeitsliste — die Handlung je Zeile (`aktion`) beschreibt, was dort passieren soll
Tabellenzeilen	`components/tables/DataTable.tsx`	Absprung auf den Datensatz
Suche und Glocke (Kopfzeile)	`components/layout/AppShell.tsx`	Attrappe, gehört zur bestehenden Shell

2.4 Was funktioniert und erhalten bleiben sollte

Zeitraum-Umschaltung rechnet alle Kennzahlen und Charts neu, inklusive Trendvergleich zur Vorperiode
Mehrfachfilter (Gewerk, Status, Quelle, Region, Mitarbeiter) mit entfernbaren Chips
Seitenabhängige Filterrelevanz — irrelevante Filter werden gar nicht erst angeboten
Widgets ausblenden über das ⋯-Menü jeder Karte, Wiedereinblenden über die Filterleiste, persistiert
Tabellen sortieren, durchsuchen, blättern
Hover auf Balken, Ringsegmenten, Trichterstufen und Verlaufspunkten
Legenden im Ring heben beim Klick das jeweilige Segment hervor
Tastaturbedienung: sichtbarer Fokus auf allen interaktiven Elementen, Escape schließt Dropdown und Karten-Menü

Persistiert wird in localStorage unter hivegrid.analytics.*. In der echten Software gehört das an das Benutzerprofil.

3. Bewusste Entscheidungen

Recharts statt der Subframe-Chart-Komponenten. Die Subframe-Wrapper (ui/components/AreaChart etc.) geben zu wenig Kontrolle über Achsen, Tooltips und Ringproportionen, um die Carbon-Regeln umzusetzen. Die übrige Oberfläche nutzt weiterhin die Subframe-Bibliothek und deren Design-Tokens.

Deterministische Dummy-Daten. Fester Seed statt Math.random(): Die Zahlen bleiben über Reloads und Screenshots identisch, sonst ist keine Abstimmung über konkrete Werte möglich.

Team-Seite enthalten, obwohl die Planung sie für v2 vorgesehen hatte. Auslastung ist im Handwerk die Kennzahl, nach der disponiert wird — ohne sie fehlt dem Dashboard der Bezug zum Tagesgeschäft.

Kein Dark Mode. Die Carbon-Palette ist hier im Light Theme hinterlegt. Ein Dark Theme braucht die zweite Palettenvariante (in @carbon/charts enthalten) und eigene Kontrastprüfung — bewusst nicht angefangen, statt es halb zu machen.

4. Empfohlene Reihenfolge beim Einbau

data/types.ts gegen die echten Entity-Typen abgleichen
data/seed.ts durch die echte Datenquelle ersetzen
HEUTE in utils/dateUtils.ts auf new Date() umstellen
view-models/index.ts gegen @hivegrid/view-models tauschen — der Vertrag (VMState) ist wortgleich, es ist ein Import-Wechsel
Eine Seite vollständig durchziehen (Übersicht): Loader ruft baueUebersichtVM(), die Route rendert <UebersichtSeite vm={…} />. Der Container unter routes/ entfällt dabei, die Seite bleibt unverändert. Dabei zeigt sich, welche Felder in den echten Daten fehlen
Texte auf i18n-Keys ziehen, data-ui-id ergänzen, mobile:-Verhalten nachrüsten (siehe docs/LEITPLANKEN.md)
Filter serverseitig nachziehen, sobald die Datenmengen es erfordern
Export, Absprünge und Persistenz am Benutzerprofil ergänzen

5. Offene Punkte für die Fachabstimmung

Auslastung rechnet produktive Stunden gegen Vertragsstunden. Ob Rüst- und Fahrzeiten als produktiv zählen, ist eine betriebliche Festlegung — die Schwellen (70 % / 95 %) stehen in components/charts/AuslastungsBalken.tsx.
Umsatz ist hier Zahlungseingang, nicht Rechnungsstellung. Für die betriebswirtschaftliche Auswertung kann die andere Definition gewünscht sein; beide Varianten sind aus denselben Daten berechenbar.
Deckungsbeitrag basiert auf einer geschätzten Marge je Auftrag. Ob echte Kostendaten vorliegen, ist offen.
Förderquote BAFA/KfW ist als eigener Block angelegt, weil sie im Wärmepumpengeschäft entscheidend ist. Sie braucht ein Feld am Auftrag.

6.8 KiB Raw Blame History