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