MABEA/arbeitskacheln/18_notifications.md

# Epic 18 — Notifications & Eskalation

Details zu NOTIF-001 … NOTIF-003. NOTIF-001/002 vollständig umgesetzt, NOTIF-003 ergänzt
am 2026-09-09 aus Open-Source-Vergleich (Shelf.nu), noch offen/ungeplant. Übernommen aus
`arbeitskarten/05_benachrichtigungen.md`
und `arbeitskarten/12_eskalation.md` (Karte 05+12) — beide Karten hatten kein Gegenstück im
ursprünglichen 16-Epic-Backlog, obwohl Karte 12 bereits vollständig implementiert ist.

---

## NOTIF-001 — Benachrichtigung bei neuem Fehlbestand

- **Ziel:** Verantwortlicher erfährt zeitnah von neuem Fehlbestand, ohne aktiv nachschauen
  zu müssen.
- **Beschreibung:** Zwei Kanäle: Dashboard-Anzeige (Portal) und E-Mail. Kein Push/App in V1.
- **Benutzerwert:** Kein Fehlbestand geht unbemerkt unter.
- **Abhängigkeiten:** INV-006, FOUND-002
- **Datenmodell:** keins zusätzlich (E-Mail-Versand ist zustandslos, triggert bei
  Statuswechsel "offen")
- **Backend:** E-Mail-Versand-Komponente, Trigger bei Fehlbestand-Entstehung
- **Frontend:** Dashboard-Kachel (Pflichtbestandteil)
- **Mobile:** Dashboard-Ansicht
- **QR-Code/Seriennummer/Inventarnummer:** nein
- **Akte:** nein direkt
- **Rechte:** Verantwortliche erhalten Benachrichtigung für ihre Zuständigkeit
- **Audit:** Versand nicht zwingend geloggt (kein fachlicher Vorgang, nur Benachrichtigung)
- **Akzeptanzkriterien:** neuer Fehlbestand löst E-Mail an zuständigen Verantwortlichen aus
  und erscheint im Dashboard.
- **Tests:** Trigger-Test (Fehlbestand-Entstehung → E-Mail-Mock aufgerufen).
- **DoD:** deckt sich 1:1 mit MABEA — bereits vollständig umgesetzt und produktiv
  (`app/services/benachrichtigung.py`, ausgelöst in `kontrolle/erfassung.py` und
  `geraet_instanz.py` bei jeder Fehlbestand-Entstehung, Test in `test_email.py`).

## NOTIF-002 — Eskalation lange offener Fehlbestände

- **Ziel:** Automatische Eskalation, wenn ein Fehlbestand zu lange offen bleibt.
- **Beschreibung:** Zwei Stufen — Erinnerung an Materialverantwortliche nach X Tagen,
  Eskalation an Leitungsverantwortliche/Administration nach Y Tagen. Zeitschwellen
  konfigurierbar, nicht fix im Code.
- **Benutzerwert:** Verschleppte Fehlbestände werden nicht endlos ignoriert.
- **Abhängigkeiten:** INV-006, NOTIF-001
- **Datenmodell:** `eskalation_konfiguration` (Singleton-Zeile, Zeitschwellen je Stufe),
  Tracking-Zeitstempel je Stufe an `fehlbestand` (verhindert Mehrfachversand)
- **Backend:** `app/services/eskalation.py` (zweistufige Logik), `GET/PUT
  /api/v1/eskalation/konfiguration` (admin-editierbar), `POST /api/v1/eskalation/pruefen`
  (admin-only, Prüflauf anstoßen)
- **Frontend:** Admin-UI zur Konfiguration + manueller "Jetzt prüfen"-Trigger
- **Mobile:** nein
- **QR-Code/Seriennummer/Inventarnummer:** nein
- **Akte:** nein direkt
- **Rechte:** Konfiguration/manueller Prüflauf: Administrator
- **Audit:** Eskalationsversand nachvollziehbar über Tracking-Zeitstempel
- **Akzeptanzkriterien:** Fehlbestand über Schwelle X löst Erinnerung aus, über Schwelle Y
  Eskalation, kein Mehrfachversand derselben Stufe.
- **Tests:** Schwellenwert-Tests (genau an der Grenze), Mehrfachversand-Schutz-Test.
- **DoD:** deckt sich 1:1 mit MABEA — bereits vollständig umgesetzt und produktiv.
  **Scheduling (Cron) ist Betriebsaufgabe**, kein eigener Scheduler-Prozess im Code — auf
  dem Zielserver per systemd-Timer (`mabea-eskalation.timer`), der den Prüf-Endpunkt
  periodisch aufruft.

## NOTIF-003 — Proaktive Wartungsfälligkeits-Benachrichtigung (P2, neu)

- **Ziel:** Verantwortlicher erfährt von bald fälliger/überfälliger Wartung, ohne aktiv
  `GET /objekte/{id}/faellige-wartungen` (MAINT-002) abfragen zu müssen.
- **Beschreibung:** Gleiches Muster wie NOTIF-001 (Dashboard + E-Mail), aber Trigger ist
  Wartungsfälligkeit statt Fehlbestand. MAINT-002 berechnet die Fälligkeit bereits —
  hier fehlt nur die proaktive Zustellung.
- **Benutzerwert:** Wartungstermine werden nicht verpasst, weil niemand aktiv nachschaut.
- **Abhängigkeiten:** MAINT-002, NOTIF-001 (identisches Versandmuster wiederverwenden)
- **Datenmodell:** kein neues zusätzlich zu MAINT-002; ggf. Tracking-Zeitstempel analog
  NOTIF-002 zur Mehrfachversand-Vermeidung
- **Backend:** periodischer Prüflauf (systemd-Timer analog NOTIF-002), nutzt bestehende
  Fälligkeitsberechnung
- **Frontend:** Dashboard-Kachel „Fällige Wartungen" (falls nicht bereits vorhanden)
- **Mobile:** Dashboard-Ansicht
- **QR-Code/Seriennummer/Inventarnummer:** nein
- **Akte:** nein direkt
- **Rechte:** Materialverantwortliche der jeweiligen Zuständigkeit
- **Audit:** Versand nicht zwingend geloggt (wie NOTIF-001)
- **Akzeptanzkriterien:** fällige Wartung löst einmalig E-Mail+Dashboard-Eintrag aus,
  kein Mehrfachversand für dieselbe Fälligkeit.
- **Tests:** Trigger-Test analog NOTIF-001, Mehrfachversand-Schutz-Test analog NOTIF-002.
- **DoD:** offen. **Referenz (Open-Source-Vergleich 2026-09-09):** Shelf.nu nennt dies
  „Schedule alerts for maintenance, calibration, warranty expiry" — bestätigt den
  Bedarf als verbreitetes Muster, MABEA-Umsetzung folgt dem eigenen NOTIF-001/002-Stil.

---

**MABEA-Ist-Stand-Abgleich (korrigiert 2026-09-06):** NOTIF-001 und NOTIF-002 sind
BEIDE vollständig umgesetzt und produktiv. Die zuvor hier dokumentierte Lücke bei
NOTIF-001 war veraltet — E-Mail-Versand bei Fehlbestand-Entstehung existiert bereits
seit Sprint 6 (`app/services/benachrichtigung.py`). Diese Epic-Datei existierte bislang
nicht — reine Nachdokumentation, keine offene Lücke mehr.

## Referenzen
Alte Arbeitskarten (übernommen, Karten-Dateien gelöscht): Karte 05 Benachrichtigungen,
Karte 12 Eskalation offener Fehlbestände.