Benachrichtigungs-System (Notification-Cluster)

Zweck

Das Benachrichtigungs-System in SpeamCore ist als Cluster aus sechs zusammenhaengenden Routen aufgebaut. Jede Route hat eine klare Zuständigkeit; zusammen ergeben sie eine Pipeline von „Etwas passiert" bis „Empfaenger hat die Nachricht erhalten".

Architektur-Ueberblick

Die sechs Routen

Route	Zweck
/notification-event-types	Definition der Event-Typen (z. B. „Störung", „Wartung faellig", „Beleg überfällig").
/notification-events	Stream der konkret ausgeloesten Events.
/notification-channels	Konfiguration der Versand-Kanäle mit Provider und Credentials.
/notification-subscriptions	Wer empfaengt welche Events über welchen Kanal?
/notification-templates	Inhaltsvorlagen pro Event-Typ × Kanal × Sprache.
/notification-logs	Audit-Log mit Retry-Aktion.

Lifecycle einer Benachrichtigung

1. Event entsteht im System (z. B. Auftrag wird auf finished gesetzt) — NotificationEvent mit Verweis auf einen NotificationEventType.
2. Subscription-Matching: Alle aktiven NotificationSubscription-Einträge werden auf den Event-Typ geprüft. Match: passender Event-Typ + (optional) eventTypeOption + (optional) speamboxId.
3. Template-Resolution: Pro Match wird eine NotificationTemplate ausgewaehlt — bevorzugt mit konkretem Event-Typ + Kanal + passender Sprache, sonst Fallback auf generische Vorlagen.
4. Versand: NotificationChannel ruft seinen Provider auf (SMTP, Graph, Twilio, VdS, ...) und sendet die gerenderte Nachricht.
5. Logging: Versuch, Erfolg oder Fehler werden im NotificationLog festgehalten. Bei failed ist eine Retry-Aktion verfuegbar.

Channel-Typen

Channel-Typ	Beispiel-Provider	Branchen-Relevanz
email	smtp, graph (Microsoft 365)	hoch — Beleg- und Auftrags-Notifications
sms	twilio	hoch — kritische Alarme
call	provider-spezifisch	Notruf-Eskalation
whatsapp	provider-spezifisch	informelle Kommunikation
telegram / teams	jeweils provider-spezifisch	interne Teams
push	apns (iOS), fcm (Android)	mobile Aussendienst-Apps
vds	vds (proprietaer)	Notruf-Service-Leitstelle (NSL) — IK4-Frames-Protokoll für Brandmeldeanlagen

Berechtigungen

Pro Sub-Bereich des Clusters gelten eigene Subjects (NotificationChannel, NotificationSubscription, NotificationTemplate etc.). Für eine vollständige Notification-Administration sind alle Bereiche notwendig — typischerweise eine eigene Admin-Rolle mit create/update/delete auf allen Notification-Subjects.

Drift-Risiken

1. Subscription mit veraltetem Channel-/EventType-Verweis → Template-Resolution faellt auf Defaults zurück.
2. Plaintext-Secrets in Debug-Logs bei Channel-Credential-Speicherung.
3. Async-Cache-Invalidation in Template-Service — kurze Race-Window beim Bearbeiten.
4. VdS-Counter und Lock-Holder werden bei Channel-Löschen nicht zurückgesetzt.

Hinweis für KIera

Wenn ein Anwender fragt: „Warum bekomme ich keine Benachrichtigung?" — prüfen Sie in dieser Reihenfolge: 1. Existiert eine **Subscription** für den Anwender und das Event? 2. Ist die Subscription `active`? 3. Ist der zugewiesene **Channel** `active` und der `connectionStatus = connected`? 4. Existiert eine passende **Template** für (`eventType`, `channel`, Sprache)? 5. Prüfen Sie das **NotificationLog** — gibt es einen Eintrag mit `status = failed`? Wenn ja, `failureReason` lesen.

Verknuepfungen

• Benachrichtigungs-Kanaele
• Benachrichtigungs-Abonnements
• Benachrichtigungs-Vorlagen
• Benachrichtigungs-Log

Versionshinweise

• 2026-04-29: Initiale Veroeffentlichung als Querschnitts-Konzept für den Notification-Cluster.