Zum Inhalt

Eine neue KPI aufnehmen

How-to · Stand: 2026-09-22

Eine KPI aufzunehmen heißt: Das Portal liefert einen neuen kpi_key, und der Service bekommt eine Regel dafür. Die Reihenfolge ist bewusst entkoppelt — beides kann unabhängig deployed werden.

1. Entscheiden: Händler- oder Servicefall-KPI?

  • Händler-KPI (scope='supplier'): beschreibt Verhalten über Zeit, wird periodisch per kpi-message geliefert und gespeichert. Beispiel: Korrektur-Quote.
  • Servicefall-KPI (scope='service'): beschreibt den Einzelfall, kommt im evaluation-request-Payload mit. Beispiel: Verschleißkosten des Falls.

2. Portal-Seite: Wert liefern

  • Händler-KPI: Berechnung im Monolith implementieren und den Key in die kpi-message-KPI-Liste aufnehmen (Konvention: snake_case, Prozentwerte als 5.0, nicht 0.05).
  • Servicefall-KPI: Key in die KPI-Liste des evaluation-request aufnehmen.

Das Portal darf den neuen Key liefern, bevor der Service eine Regel hat: Unbekannte Keys werden gespeichert (Händler-Scope) bzw. ignoriert — nichts bricht.

3. Service-Seite: Regel anlegen

Dauerhafte Aufnahme über den Seeder (empfohlen, siehe KPI-Grenzwerte anpassen, Weg 1) oder ad-hoc:

php artisan kpi:rule:add "*" neue_kpi --scope=supplier --operator=">=" --risky=10 --critical=20

--risky = Kritisch-Grenze, --critical = Riskant-Grenze. Ein Band weglassen = Grenze weglassen (z. B. nur --critical für eine KPI ohne Warnstufe).

4. Wichtig: Regel = Pflicht-KPI

Sobald die Regel existiert, ist die KPI Pflicht für jede Bewertung ihres Scopes: Fehlt der Wert (kein gespeicherter Händler-Wert bzw. nicht im Payload), ist das Ergebnis incomplete. Deshalb:

  • Händler-KPI: Regel erst aktivieren, wenn das Portal den Wert für alle aktiven Händler mindestens einmal geliefert hat — sonst werden deren Bewertungen ab sofort incomplete.
  • Servicefall-KPI: Regel erst aktivieren, wenn alle Request-Publisher den Key mitsenden.

5. Doku nachziehen

Neue Zeile in reference/kpis-und-grenzwerte.md (Tabelle + ggf. Wertkonvention) und in der Tabelle in api/app/Modules/KpiEvaluation/README.md ergänzen.