Dashboard/docs/DATENMODELL.md

Datenmodell

Definiert in features/dashboard/data/types.ts, erzeugt in data/seed.ts. Die Struktur ist bewusst nah an den HiveGrid-Entities gehalten, damit beim Einbau nur die Datenquelle getauscht werden muss.

---

Zuordnung zu HiveGrid

Prototyp	HiveGrid-Entity	Verfügbar	Anmerkung
Rechnung	Rechnung (Sub-Entity am Projekt)	v1	Status dort entwurf/gestellt/bezahlt/storniert — kein ueberfaellig. Überfälligkeit wird aus faellig_am gegen heute abgeleitet, nicht als Status geführt
Auftrag	Projekt in einer Pipeline mit typ_hint = auftrag	v1	„Auftrag" ist nach AD-20 keine eigene Entität, sondern eine Pipeline-View auf den Projekt-Kern. Wert = auftragsvolumen, Status = stage_id und damit pipeline-intern
Kunde	Kontakt mit kontakt_status = kunde	v1	„Kunde" ist ein Status am Kontakt, keine Entität. Kontakt ist der Oberbegriff (Privatperson/Organisation); die Verknüpfung zum Projekt läuft über ProjektKontakt mit Rolle auftraggeber
Mitarbeiter	TenantUser + User	v1
Zeiteintrag	—	v2	Zeiterfassung steht im v2-Backlog. Damit hat die gesamte Team-Seite in v1 keine Datenquelle — siehe unten

Die Begriffe des Prototyps sind SHK-Fachsprache, nicht das Datenmodell der Software. „Auftrag" und „Kunde" existieren dort nicht als Entitäten. Das ist kein Fehler des Prototyps — der Betrieb spricht so, und die Oberfläche soll so sprechen. Beim Einbau ist es aber eine Übersetzungsleistung und keine Eins-zu-eins-Zuordnung.

Die Team-Seite hat in v1 keine Datenquelle

Auslastung, Produktivquote, erfasste Stunden und Abwesenheiten beruhen alle auf Zeiteintrag. Zeiterfassung steht im ENTITY-MODEL ausdrücklich im v2-Backlog. Drei Wege:

1. Team-Seite als v2 einplanen und in v1 nicht ausliefern;
2. Stunden aus einem Drittsystem anbinden (der Betrieb erfasst sie ohnehin irgendwo) — dann ist es eine Integrationsfrage, keine Modellfrage;
3. Zeiterfassung nach v1 ziehen — die größte Entscheidung von den dreien.

Das ist eine Produktentscheidung, keine Gestaltungsfrage. Sie gehört vor den Einbau geklärt, weil sie eine von fünf Seiten betrifft.

Felder, die es so noch nicht gibt und beim Einbau ergänzt werden müssen:

Feld	Wo	Wofür
gewerk	Auftrag, Mitarbeiter	Alle Gewerke-Auswertungen und der Gewerk-Filter
margeProzent	Auftrag	Deckungsbeitrag
foerderung / foerderbetrag	Auftrag	Förderquote BAFA/KfW
verlorenAb	Auftrag	Ehrlicher Vertriebstrichter (siehe unten)
ueberAngebot	Auftrag	Trennt Angebotsgeschäft von Direktaufträgen
wochenstunden	Mitarbeiter	Auslastungsberechnung
zahlungsmoralTage	Kunde	Auffällige Zahlungsmoral (auch aus Rechnungen ableitbar)

---

Statuswerte

Auftrag: anfrage → aufmass → angebot → beauftragt → in_arbeit → abgeschlossen, dazu verloren als Endzustand.

verlorenAb hält fest, welche Stufe ein verlorener Vorgang zuletzt erreicht hat. Ohne dieses Feld müsste der Trichter raten und würde die oberen Stufen systematisch zu klein zeigen.

ueberAngebot trennt das Angebotsgeschäft (ab etwa 6.000 €) von Aufträgen, die direkt beauftragt werden — Wartung, Notdienst, E-Check. Trichter und Abschlussquote beziehen sich ausschließlich auf das Angebotsgeschäft.

Rechnung: entwurf · gestellt · bezahlt · ueberfaellig.

---

Gewerke und Leistungsarten

Gewerk	Leistungsarten
Heizung	Wärmepumpe, Gastherme, Heizkörper, Wartung
Sanitär	Bad-Sanierung, Rohrleitungen, Armaturen, Notdienst
Klima & Lüftung	Splitgerät, Lüftungsanlage, Kanalreinigung, Wartung
Photovoltaik	PV-Anlage, Batteriespeicher, Wallbox, Wartung
Elektro	Elektroinstallation, Zählerschrank, Smart Home, E-Check

Förderfähig (BAFA/KfW) sind Wärmepumpe, PV-Anlage, Batteriespeicher und Lüftungsanlage.

---

Der Demo-Datensatz

Erzeugt mit festem Seed (mulberry32, Seed 20260730) — die Zahlen bleiben über Reloads und Screenshots identisch. Bezugsdatum ist der 30.07.2026 (HEUTE in utils/dateUtils.ts).

Fiktiver Betrieb: Meister Krause GmbH, Raum Rhein-Main, 24 Beschäftigte (3 Meister, 14 Monteure, 3 Auszubildende, 4 Büro).

Größe	Wert
Kunden	420
Aufträge (24 Monate)	1.900
Rechnungen	~1.270
Zeiteinträge (12 Wochen)	~1.500
Jahresumsatz	~2,4 Mio. €
Offene Forderungen	~230 T€
Abschlussquote (Angebotsgeschäft)	~38 %
Ø Auslastung	~73 %

Eingebaute Effekte, damit die Charts nicht künstlich flach aussehen:

• Saisonalität — Heizung und Lüftung ziehen von September bis Februar an, der Hochsommer ist schwächer (SAISON_INDEX)
• Wachstum — rund 12 % gegenüber dem Vorjahr
• Größenabhängige Abschlussquote — Wartung und Notdienst werden fast immer ausgeführt, große Anlagen dagegen verglichen und häufiger verloren
• Zahlungsverhalten — die Mehrheit zahlt nahe am Zahlungsziel (21 Tage), ein kleiner Rest wird zum Mahnfall; Forderungen älter als sieben Monate sind eingebracht oder ausgebucht und stehen nicht mehr in der offenen Liste
• Förderanträge — nur bei Vorgängen der letzten rund 100 Tage offen; ein Bescheid dauert Wochen, nicht Jahre

Diese Effekte sind fachlich begründet, nicht kosmetisch: Ein gleichverteilter Zufallsdatensatz erzeugt Charts, an denen sich keine Gestaltung prüfen lässt.