Benachrichtigungs-Kanäle

Zweck

Benachrichtigungs-Kanäle (NotificationChannel) konfigurieren, wie SpeamCore Nachrichten verschickt. Pro Kanal pflegen Sie Channel-Typ (E-Mail, SMS, ...), einen Provider (z. B. smtp oder graph für E-Mail) und die zugehörigen Credentials. Für Brandschutz-Fachfirmen besonders wichtig: der VdS-Kanal mit Diagnostik-Aktionen für die Notruf-Service-Leitstelle (NSL).

Voraussetzungen

- Berechtigung `create:NotificationChannel`. - Provider-Credentials (z. B. SMTP-Login, Microsoft-Tenant-ID, Twilio-Token). - Für VdS: Identifikationsnummer und Verbindungsparameter zur Leitstelle.

Berechtigungen (CASL)

Action	Subject	Keycloak-Rolle
view	FE_NotificationChannel, NotificationChannel	—
create/update/delete	NotificationChannel	APP_SPEAMCORE_CREATE/UPDATE/DELETE_NOTIFICATION_CHANNEL
view	NotificationChannelCredential (Sub-Liste der Credentials)	APP_SPEAMCORE_VIEW_NOTIFICATION_CHANNEL_CREDENTIAL (SUB-LISTE DER CREDENTIALS)`
view	NotificationChannelActivity (Tab Aktivität)	APP_SPEAMCORE_VIEW_NOTIFICATION_CHANNEL_ACTIVITY (TAB AKTIVITAET)`

Schritt-für-Schritt-Anleitung

Kanal anlegen

1. Benachrichtigungs-Kanäle (/notification-channels) → + Neu.
2. Channel-Typ wählen.
3. Abhaengig vom Channel-Typ erscheinen die zulässigen Provider-Typen.
4. Provider-spezifische Felder pflegen — z. B. für email/smtp: Host, Port, User, Passwort, Absender-E-Mail.
5. Credentials werden im beforeCreate-Hook AES-verschluesselt persistiert.

VdS-Diagnose ausführen

Auf der Detail-Seite stehen drei Buttons:

• Unterstuetzte Satztypen abfragen — POST /:id/query-supported-satztypen (kann ~15 s dauern wegen IK4-Frames).
• Sammel-Status abfragen — POST /:id/query-sammel-status.
• Testmeldung senden — POST /:id/send-testmeldung.

Ergebnisse erscheinen auf dem Tab Kanal-Aktivität mit Zeitstempel und ggf. Fehlermeldung.

Toolbar (Detail-Seite)

Schlanke Toolbar oben rechts:

Icon	Aktion (aria-label)	CASL	Wirkung
←	Zurückgehen	—	Zurück zur Liste.
🏠	Zur Startseite gehen	—	Springt auf das Dashboard / /.
⏮/◀/▶/⏭	Pagination	—	Navigation durch die gefilterte Liste — Massen-Bearbeitung ohne Liste-Sprung.

Globale Floating-Drawer (links)

Wie auf jeder Detail-Seite verfuegbar — siehe Floating-Quickbar:

• KAL. (Mini-Kalender)
• ZEIT (Persoenliche Wochen-Arbeitszeit)
• ARBEIT (Eigene bevorstehende Aufträge)

UI-Elemente

Auswahl: „Channel-Typ"

email, sms, call, whatsapp, telegram, teams, push, vds. Bestimmt die verfuegbaren Provider-Typen.

Auswahl: „Provider-Typ"

Abhaengig von Channel-Typ. Beispiele:

• email → smtp, graph
• sms → twilio
• push → apns, fcm
• vds → vds (proprietaer, IK4-Frames).

Komponente: CredentialField

Provider-spezifische Felder. AES-verschluesselt vor dem Speichern.

Buttons: VdS-Diagnostik

Unterstuetzte Satztypen abfragen, Sammel-Status abfragen, Testmeldung senden. Sichtbar nur bei channelType = vds.

Felder und Eingaben

Feldname	Pflicht	Datentyp	Wirkung beim Ausfuellen	Voraussetzung
name	nein	String	Anzeige in Auswahllisten und Reports.	—
channelType	nein	Auswahl (8 Werte)	Bestimmt Provider-Optionen und Credential-Felder. Wechsel loescht Provider-Auswahl.	—
providerType	nein	Auswahl (dynamisch)	Bestimmt Credential-Felder; AES-Verschluesselung im Hook.	passender Channel-Typ.
status	nein	active/inactive	active aktiviert den Versand-Listener. inactive pausiert ohne Configs zu löschen.	—
loggingEnabled	nein	Boolean (Switch)	Bei true: Versand-Audit landet in NotificationLog.	—
sendGpsCoordinates	nein	Boolean (Switch)	Nur bei channelType = vds: GPS-Koordinaten der SpeamBox werden in der NSL-Meldung mitgesendet.	VdS-Provider, GPS-Daten verfuegbar.
connectionStatus	—	Read-only String	Echtzeit-Status (connected, error, pending).	—
lastConnectedAt	—	Read-only DateTime	Zeitstempel des letzten erfolgreichen Verbindungs-Checks.	—
lastErrorMessage	—	Read-only TEXT	Letzte Fehlermeldung (Channel-spezifisch).	—
vdsEventCounter	—	Read-only Integer	Fortlaufender Counter aller VdS-Events. Wird beim Löschen nicht zurückgesetzt — orphaned Counter möglich.	—
vdsLockHolder	—	Read-only String	Aktueller Lock-Halter für VdS-Verbindung (Single-Connection-Schutz).	—

CRUD-Pattern (Standard)

Diese Sub-Route folgt dem Standard-CRUD-Pattern:

• + Neu öffnet ein Modal mit Eingabemaske oder erstellt direkt einen leeren Datensatz und navigiert auf den Detail.
• Detail-Seite verwendet Auto-Save: jede Änderung schreibt sofort via PATCH in das BE.
• Löschen ist Soft-Delete (paranoid) — Datensaetze sind in der Datenbank weiter vorhanden, aber gefiltert.

Spezielles Verhalten dieser Sub-Route ist im jeweiligen Notification-Cluster dokumentiert: siehe Notification-System Konzept.

Wiederverwendbare Konzepte

• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• NotificationTemplate — notificationChannelId referenziert den Kanal.
• NotificationSubscription — verbindet Empfaenger mit Kanal und Event-Typ.
• NotificationLog — Versand-Audit pro Channel.
• NotificationChannelCredential — verschluesselte Credentials (Sub-Liste).
• NotificationChannelActivity — Audit-Log für VdS-Events und Verbindungs-Änderungen.

Häufige Fehler und Lösungen

Fehler	Lösung
Versand schlaegt fehl mit „auth_error"	Credentials veraltet oder rotiert — Credential im Channel aktualisieren.
VdS-Diagnostik hängt 15 s	Normal — IK4-Frames-Prüfung dauert. Nicht abbrechen.
vdsEventCounter springt nach Channel-Löschen	Persistente Counter werden nicht zurückgesetzt. Bewusst — für Forensik.
connectionStatus = error	lastErrorMessage prüfen. Typisch: Firewall, Token-Ablauf, falsche Tenant-ID.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/notification-channels	Liste	view NotificationChannel
POST	/api/notification-channels	Anlegen	create NotificationChannel
PATCH	/api/notification-channels/:id	Ändern	update NotificationChannel
DELETE	/api/notification-channels/:id	Soft-Delete	delete NotificationChannel
POST	/api/notification-channels/:id/query-supported-satztypen	VdS — IK4-Prüfung (~15 s)	update NotificationChannel
POST	/api/notification-channels/:id/query-sammel-status	VdS — Sammel-Status	update NotificationChannel
POST	/api/notification-channels/:id/send-testmeldung	VdS — Testmeldung	update NotificationChannel

Native Push an die mobile App (Juni 2026)

Neben den hier konfigurierten Kanälen verschickt SpeamCore native Push-Benachrichtigungen an die mobile App der Mitarbeiter. Dieser Weg braucht keine Kanal-Konfiguration:

• Geräte-Registrierung: Die App registriert beim Login das Push-Handle des Geräts (POST /api/device-tokens, Entfernen via DELETE /api/device-tokens/:token). Ein installations-stabiler deviceId dedupliziert über Token-Wechsel hinweg. Push-Handles sind Credentials und werden serverseitig gehalten (nicht im Client sichtbar).
• Auslöser: u. a. wenn die KI einen Support-Chat an einen Mitarbeiter übergibt (Handoff) oder eine neue Konversation ohne KI startet — die verfügbaren Mitarbeiter erhalten dann einen nativen Push.
• Master-Fallback: Hat ein Mandant keinen eigenen Push-Kanal, werden die Pushes über die zentrale SpeamCore-Master-Plattform zugestellt (eine app-weite APNS-/FCM-Anbindung), pro Mitarbeiter + Plattform dedupliziert.

Versionshinweise

• 2026-06-30: Abschnitt Native Push an die mobile App ergänzt — Geräte-Token-Registrierung (/device-tokens), Push bei Chat-Handoff / No-AI-Konversation, Master-Fallback bei fehlendem lokalem Push-Kanal. Verifiziert an deviceToken.model.ts, deviceToken.router.ts, masterPush.service.ts.
• 2026-04-29: Initiale Veroeffentlichung mit FE-Tiefen-Standard inklusive VdS-Diagnostik.