# 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 |