feat(dashboard): Analytics-Dashboard als Gestaltungsvorlage zur Übergabe

UI/UX-Prototyp der Analytics-Dashboards in HiveGrid, fachlich auf einen
SHK-/Handwerksbetrieb zugeschnitten. Ziel ist die Übergabe an die Entwicklung,
nicht der Produktivbetrieb.

Inhalt: sechs Seiten (Übersicht, Finanzen, Aufträge, Kunden, Team, Komponenten),
26 KPIs, neun Chart-Bausteine, Filtersystem mit seitenabhängiger Relevanz und ein
deterministischer Demo-Datensatz (420 Kunden, 1.900 Aufträge, Stichtag 30.07.2026).

Drei Quellen sind zusammengeführt: die fachliche Planung mit dem Branchenpartner
(Januar 2026), die Subframe-Komponentenbibliothek aus dem HiveGrid-Pitch und
IBM Carbon Data Visualization für die Diagrammregeln. Herkunft und bewusste
Abweichungen stehen in docs/HERKUNFT.md.

Dokumentation: README, HANDOVER (was echte Logik braucht), docs/DESIGN-SYSTEM,
KPI-KATALOG, DATENMODELL, NAVIGATION, HERKUNFT, ZIELSYSTEM (Einbauort in
HiveGrid Cloud) und LEITPLANKEN (welche Cloud-Screens als Vorbild taugen).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QPeZNwSeU7qG3RRCwaxEZX
This commit is contained in:
dejanandClaude Opus 5 committed 2026-08-29 17:25:20 +02:00
commit b8bf987d0e
250 files changed
+33153

No files matched your search

+147
View File
@@ -0,0 +1,147 @@
# KPI-Katalog
Jede Kennzahl mit Definition, Berechnung und Fundstelle im Code.
Alle Funktionen liegen in `features/dashboard/data/calculations.ts`.
**Zwei Zeitbezüge sind zu unterscheiden:**
- **zeitraumbezogen** — reagiert auf die Zeitraum-Umschaltung (Umsatz, neue Kunden)
- **stichtagsbezogen** — gilt zum heutigen Tag, unabhängig vom Zeitraum
(offene Forderungen, aktive Aufträge, Auslastung des Bestands)
Das ist Absicht: „Offene Forderungen der letzten 7 Tage" wäre keine sinnvolle
Zahl.
In der Oberfläche steht der Zeitbezug in der **Fußzeile jeder KPI-Karte**
(„im gewählten Zeitraum" / „zum Stichtag" / „über alle Zeiträume"). Karten mit
Vorperiodenvergleich zeigen dort stattdessen den Trend — die Anatomie bleibt
gleich, damit die Reihe eine gemeinsame Grundlinie hat. Diagrammkarten, die
den Zeitraumfilter ignorieren, sagen es im Untertitel.
---
## Übersicht
| KPI | Definition | Bezug | Funktion |
|---|---|---|---|
| Umsatz (Zahlungseingang) | Summe bezahlter Ausgangsrechnungen, gezählt am Zahlungsdatum | Zeitraum | `umsatz()` |
| Trend Umsatz | Vergleich mit dem gleich langen Zeitraum davor | Zeitraum | `umsatzVorperiode()` + `berechneTrend()` |
| Offene Forderungen | Summe aller nicht bezahlten Ausgangsrechnungen | Stichtag | `offenePosten().gesamt` |
| Aktive Aufträge | Vorgänge im Status „beauftragt" oder „in Arbeit" | Stichtag | `aktiveAuftraege()` |
| Ø Auslastung Monteure | Mittel der produktiven Stunden je verfügbarer Stunde | Zeitraum | `teamKennzahlen()` |
| Neue Kunden | Kundendatensätze mit Anlagedatum im Zeitraum | Zeitraum | `neueKunden()` |
| Abschlussquote | Gewonnene Aufträge im Angebotsgeschäft, bezogen auf alle Angebote | Stichtag | `abschlussquote()` |
| Deckungsbeitrag | Nach Auftragswert gewichtete Marge abgeschlossener Aufträge | Zeitraum | `marge()` |
**Umsatzentwicklung** (`umsatzVerlauf()`) bildet zusätzlich den
Vorjahreszeitraum ab: Jede Zahlung wird um zwölf Monate verschoben in denselben
Zeitraster einsortiert. Die Auflösung wechselt automatisch — bis 30 Tage
tageweise, darüber monatsweise.
---
## Finanzen
| KPI | Definition | Bezug | Funktion |
|---|---|---|---|
| Umsatz (bezahlt) | wie oben | Zeitraum | `umsatz()` |
| Offene Forderungen | Status „gestellt" oder „überfällig" | Stichtag | `offenePosten()` |
| Überfällig | Nur Status „überfällig" (Zahlungsziel deutlich überschritten) | Stichtag | `offenePosten().ueberfaellig*` |
| Ø Zahlungsdauer | Mittel aus Rechnungsdatum bis Zahlungseingang | Zeitraum | `zahlungsdauer()` |
| Deckungsbeitrag | siehe oben | Zeitraum | `marge()` |
| Forderungen nach Alter | Buckets ab Fälligkeit: 0–30 / 31–60 / 61–90 / > 90 Tage | Stichtag | `offenePosten().nachAlter` |
| Rechnungsvolumen nach Status | Betragssumme je Rechnungsstatus | Stichtag | `rechnungenNachStatus()` |
| Umsatz nach Gewerk | Bezahlte Rechnungen, zugeordnet über den Auftrag | Zeitraum | `umsatzNachGewerk()` |
| Top-Kunden | Kunden nach bezahltem Gesamtumsatz | gesamt | `topKunden()` |
Die Altersstruktur ist die wichtigste Karte der Seite: Ab etwa 60 Tagen sinkt
die Einbringungsquote erfahrungsgemäß deutlich. Die Balken sind deshalb von
grün nach rot eingefärbt.
---
## Aufträge
| KPI | Definition | Bezug | Funktion |
|---|---|---|---|
| Neue Aufträge | Vorgänge mit Anlagedatum im Zeitraum | Zeitraum | `auftraegeImZeitraum()` |
| Aktive Aufträge | „beauftragt" oder „in Arbeit" | Stichtag | `aktiveAuftraege()` |
| Auftragsbestand | Summe der Werte aktiver Aufträge | Stichtag | abgeleitet |
| Über Termin | Beauftragt oder in Arbeit und Fälligkeit überschritten | Stichtag | `ueberfaelligeAuftraege()` |
| Abschlussquote | siehe Übersicht | Stichtag | `abschlussquote()` |
| Ø Durchlaufzeit | Anlagedatum bis Abschluss, nur abgeschlossene Vorgänge | Stichtag | `durchlaufzeit()` |
| Vertriebstrichter | Vorgänge je erreichter Stufe | Stichtag | `vertriebsTrichter()` |
| Förderquote BAFA/KfW | Anteil **förderfähiger** Aufträge mit beantragter oder bewilligter Förderung | Stichtag | `foerderQuote()` |
**Zum Trichter:** Er zeigt ausschließlich das **Angebotsgeschäft** — Vorhaben
ab etwa 6.000 €, für die schriftlich angeboten wird (Feld `ueberAngebot`).
Wartung, Notdienst und E-Check gehen ohne Angebot direkt in die Ausführung;
zählte man sie mit, würde der Trichter unten breiter als oben.
Verlorene Vorgänge zählen bis zu der Stufe, auf der sie abgesprungen sind
(Feld `verlorenAb`). Ohne diese Unterscheidung wären die oberen Stufen
systematisch zu klein und die Übergangsquoten wertlos.
**Zur Abschlussquote:** gleiche Bezugsgröße wie der Trichter. Sie entspricht
deshalb exakt der Übergangsquote von „Angebot" auf „Beauftragt" — im
Demo-Datensatz rund 38 %.
**Zur Förderquote:** Bezugsgröße sind nur förderfähige Leistungen (Wärmepumpe,
PV-Anlage, Batteriespeicher, Lüftungsanlage). Über alle Aufträge gerechnet läge
sie im einstelligen Bereich und wäre wertlos — eine Badsanierung war nie
förderfähig.
---
## Kunden
| KPI | Definition | Bezug | Funktion |
|---|---|---|---|
| Kunden gesamt | Alle Kundendatensätze | Stichtag | — |
| Neue Kunden | Anlagedatum im Zeitraum | Zeitraum | `neueKunden()` |
| Wiederkehrende Kunden | Anteil mit mehr als einem Auftrag | Stichtag | `wiederkehrquote()` |
| Ø Kundenwert | Bezahlter Umsatz je Kunde mit mindestens einem Auftrag | gesamt | abgeleitet |
| Reaktivierbar | Kunden mit Historie, über 12 Monate ohne Auftrag | Stichtag | `inaktiveKunden()` |
| Kunden nach Quelle / Typ / Region | Verteilungen | Stichtag | `kundenNach()` |
| Auffällige Zahlungsmoral | Ø Zahlungsdauer über 30 Tage | Stichtag | `zahlungsauffaellig()` |
Empfehlung und Bestandskunden zusammen zeigen, wie stark der Betrieb ohne
Werbebudget wächst — im Handwerk die aussagekräftigste Quellenkennzahl.
---
## Team
| KPI | Definition | Bezug | Funktion |
|---|---|---|---|
| Im Einsatz | Gewerblich Beschäftigte mit Status „aktiv" | Stichtag | — |
| Ø Auslastung | Produktive Stunden / verfügbare Stunden (aus Wochenstunden hochgerechnet) | Zeitraum | `teamKennzahlen()` |
| Produktivquote | Auftragsbezogene Stunden / erfasste Stunden | Zeitraum | abgeleitet |
| Erfasste Stunden | Summe aller Zeiteinträge | Zeitraum | abgeleitet |
| Abwesenheit | Stunden für Urlaub, Krankheit, Fortbildung | Zeitraum | abgeleitet |
| Abgeschlossene Aufträge je Mitarbeiter | Anzahl im Zeitraum abgeschlossener Aufträge | Zeitraum | `teamKennzahlen()` |
| Auftragswert je Mitarbeiter | Summe der Werte dieser Aufträge | Zeitraum | `teamKennzahlen()` |
**Auslastungsschwellen** (in `AuslastungsBalken.tsx`, betrieblich festzulegen):
| Bereich | Bedeutung |
|---|---|
| < 70 % | Luft frei — Kapazität ungenutzt |
| 70–95 % | Zielkorridor |
| > 95 % | Ausgebucht — Terminrisiko |
Der Auftragswert je Mitarbeiter ist ausdrücklich **kein Leistungsvergleich**:
Ein Wärmepumpen-Auftrag ist um ein Vielfaches größer als eine Wartung. Der
Hinweis steht als Tooltip an der Karte.
---
## Bewusst nicht enthalten
| Kennzahl | Grund |
|---|---|
| Live-Aktualisierung | Für die Gestaltungsabstimmung ohne Nutzen |
| CSV-/Excel-Export | Reine Umsetzungsfrage, kein Gestaltungsthema |
| Drilldown auf Einzeldatensätze | Der Absprung in die bestehenden Listen genügt |
| E-Mail-Marketing-Kennzahlen | Eigenes Modul (siehe Planungsordner 04) |
| Workflow-Kennzahlen | Eigenes Modul |