28 KiB
module, title, phase, status, last_updated, session_source, related_lps, spec_style
| module | title | phase | status | last_updated | session_source | related_lps | spec_style | ||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 22 | Notifications | 1 | detail-spec-draft | 2026-05-08 | brainstorming-session-2026-05-07-2206.md |
|
requirements-pur |
Modul 22 — Notifications
Detail-Spec gemäß LP-9. Drei-Kanal-Notification-System (In-App, Email, Mobile-Push) mit Pro-User-Präferenzen, Ruhezeiten, Anti-Spam-Bündelung und Mobile-Device-Registrierung. Behebt Lücke L-17 (Notification-Storm bei Massen-Events). Apple-Compliance für Push-Permission-Flows (LP-8).
Themenblöcke
A. Datenmodell (Notification, Preference, Device, Bundle)
B. Kanäle (In-App, Email, Mobile-Push)
C. Menü-Struktur und Routes
D. Notification-Center (Listen + Detail)
E. Pro-User-Präferenzen
F. Ruhezeiten
G. Anti-Spam-Bündelung
H. Mobile-Device-Registrierung
I. Event-Typen-Katalog
J. Versand-Pipeline
K. Permissions-Anwendung
L. Klartext-Hinweise
M. Phase 2 / spätere Features
Block A — Datenmodell
Notification
id(UUID)tenant_id(NOT NULL, RLS)recipient_user_id(FK auf User, NOT NULL)created_at(Timestamp, indexed)event_type(Enum, siehe Block I)event_subject_type,event_subject_id(FK auf Quelle, z.B. Lead, Deal, Task)actor_user_id(FK auf auslösenden User; NULL bei System/Automation)actor_kind(Enum:user | system | automation | ki_agent | external)title(Pflicht — kurzer Klartext, z.B. „Neuer Lead: Müller GmbH")body(Pflicht — längere Beschreibung, z.B. „Über Form ‚Kontakt SHK' eingegangen. [Lead öffnen]")deeplink(URL — z.B./{tenant}/leads/{leadId})priority(Enum:low | normal | high | urgent)read_at(Timestamp NULL — markiert Read-Status)dismissed_at(Timestamp NULL — User hat manuell weggeklickt)bundle_id(FK auf NotificationBundle; NULL falls einzeln versendet)metadata(JSONB — Event-spezifische Felder)delivery_status(JSONB pro Kanal — siehe unten)
delivery_status (JSONB)
{
"in_app": "delivered",
"email": "skipped:user_preference" | "queued" | "sent" | "bounced" | "failed:smtp_timeout",
"push": "skipped:no_device" | "queued" | "delivered" | "failed:invalid_token"
}
NotificationPreference
id(UUID)tenant_id,user_idevent_type(Enum, siehe Block I)channel_in_app(Boolean — Default abhängig vom Event-Typ)channel_email(Boolean)channel_push(Boolean)priority_threshold(Enum:all | normal_and_above | high_and_above | urgent_only)updated_at
Default-Sets pro Rolle: beim Onboarding wird ein Preference-Set für Default-Rolle geseeded (z.B. Vertriebler bekommt In-App+Push für lead.assigned, Email aus).
NotificationDevice (Mobile-Push)
id,tenant_id,user_iddevice_kind(Enum:ios | android)push_token(Text — APNs-Token oder FCM-Token)device_label(z.B. „iPhone von Max", vom OS oder User benennbar)os_version,app_versionregistered_at,last_seen_atrevoked_at(NULL falls aktiv)
NotificationBundle (Anti-Spam-Bündelung)
id,tenant_id,recipient_user_idcreated_at,closed_at(NULL solange Bundle offen)event_type_group(z.B.lead.created,task.assigned— gleichartige Events werden gebündelt)count(Anzahl gebündelter Events)subject_summary(Textuelle Zusammenfassung der gebündelten Subjects)bundle_window_seconds(Default 300 = 5 Min)
NotificationQuietHours
id,tenant_id,user_idweekday(Enum:mo | tu | we | th | fr | sa | suODERweekend)start_time(TIME)end_time(TIME — über Mitternacht erlaubt)enabled(Boolean)urgent_override(Boolean —urgent-Notifications überschreiben Ruhezeiten)
Indizes
(tenant_id, recipient_user_id, created_at DESC)— Notification-Center-Default(tenant_id, recipient_user_id, read_at)— Unread-Count-Query(tenant_id, user_id, push_token)für Device-Lookup, UNIQUE-Constraint aufpush_tokenpro Tenant
Block B — Kanäle
B.1 — In-App-Notification-Center
- Notification-Icon in Top-Bar mit Unread-Count-Badge
- Klick öffnet Notification-Center (Drawer oder Page — Designer-Wahl)
- Default-Kanal für jede Notification (kann nicht deaktiviert werden — In-App ist die Wahrheit)
- Real-time-Update über Server-Sent-Events oder WebSocket; Fallback auf Polling alle 30 Sek
- Bei Tab-Background: Browser-Tab-Title zeigt Unread-Count
B.2 — Email
- Versand über Tenant-Sending-Domain (Modul 9 Email-Domain mit DKIM)
- Email-Templates aus i18n-Locale-Files (LP-12) mit Tenant-Branding (Logo + Primärfarbe — Modul 31 Phase 1 Light/Dark + Logo)
- Bei Bundle: ein Email pro Bundle mit zusammengefasstem Inhalt
- Bei Urgent-Priority + offline-User: sofortiges Email (siehe Block G)
- Bounce-Handling: bei wiederholtem Bounce → Notification-Email für User pausiert (Klartext im Notification-Center: „Emails an dich kommen aktuell nicht an — bitte Email-Adresse prüfen")
- Standard-Footer: Klartext „Du bekommst diese Email weil X — [Notifications-Settings]"
B.3 — Mobile-Push
- Provider: Novu als Abstraktions-Schicht
- APNs (iOS) und FCM (Android) als Backends
- Push-Payload enthält
title,body,deeplink,priority,bundle_countfalls Bundle - Capacitor-Wrap (Modul 36) registriert Device-Token via
/api/v1/notifications/mobile-device - iOS: Notification-Permission-Flow nach Apple-Compliance (LP-8) — Erst-Use-Teaser-Screen erklärt warum, dann nativer Permission-Dialog
- Android: Permission ab API 33 ähnlicher Flow
- Bei Permission-Denied: Klartext im Settings-Notifications: „Push ist auf diesem Gerät deaktiviert. [Geräte-Einstellungen öffnen]"
- Silent-Push-Capability (Phase 2 — für Hintergrund-Sync der Mobile-App)
Block C — Menü-Struktur und Routes
Routen:
/{tenant}/notifications → Notification-Center
/{tenant}/notifications/:id → Notification-Detail (selten direkt; Deeplink-First)
/{tenant}/settings/notifications → Pro-User-Präferenzen-Übersicht
/{tenant}/settings/notifications/preferences → Event-Typ-Präferenzen-Editor
/{tenant}/settings/notifications/quiet-hours → Ruhezeiten-Editor
/{tenant}/settings/notifications/devices → Mobile-Devices-Liste
/{tenant}/admin/notifications/templates → Email-Template-Anzeige (read-only Phase 1)
/{tenant}/admin/notifications/test → Test-Notification senden (Tenant-Admin-Werkzeug)
Permission-Anforderungen:
/notifications→ eingeloggt (Self-Scope)/settings/notifications/*→ eingeloggt (Self-Scope)/admin/notifications/*→tenant.adminODERnotifications.admin
Block D — Notification-Center
Zu zeigende Daten pro Notification
titleals Hauptzeilebodyals Sekundär-Zeile (gekürzt bei Listen-Anzeige)- Datum/Zeit (relativ < 7 Tage, sonst absolut)
- Actor (Avatar + Name oder Marker für System/Automation/KI)
- Event-Typ-Marker (visuelle Kategorie — Designer-Wahl)
- Read-Status (gelesen/ungelesen visuell unterscheidbar)
- Deeplink-Indikator (Ziel der Aktion)
- Bei Bundle:
count+ Subject-Summary statt Einzel-Anzeige (z.B. „7 neue Leads") - Priority-Marker für
high/urgent
Benötigte UI-Elemente
- Listen-Anzeige (Designer-Wahl: Drawer / Page / Stream)
- Tab- oder Filter-Funktion für „Alle / Ungelesen / Markiert"
- Filter-Komponenten:
- Event-Typ (Multi-Select gruppiert)
- Actor
- Zeitraum
- Priority
- Such-Funktion über
title+body - Pagination (Cursor-basiert, „Mehr laden", 50 pro Page)
- Bulk-Auswahl (Checkboxes)
- Quick-Action-Funktionen pro Eintrag:
- Als gelesen markieren / als ungelesen markieren
- Wegklicken (
dismissed_at) - Klick öffnet Deeplink (markiert automatisch als gelesen)
- Bei Bundle: „Alle anzeigen" expandiert in Einzel-Notifications
Operationen
- Mark-as-read / Mark-as-unread (einzeln + bulk)
- Mark-all-as-read (mit Klartext-Bestätigung bei mehr als 50 ungelesenen)
- Bulk-Clear (
dismissed_atsetzen — Notifications bleiben für Audit-/Replay-Zwecke aber sind nicht mehr im Center sichtbar) - Filter speichern (Phase 2)
- Klick auf Notification → Deeplink + Mark-as-read
Performance-Anforderungen
- Server-side-Filter
- Index siehe Block A
- Unread-Count via Cached-Counter (Redis), invalidiert bei Mark-as-read / neue Notification
- Real-time-Updates über SSE/WebSocket
- Notifications älter als 90 Tage werden ausgeblendet (gelöscht: siehe Phase 2 Auto-Cleanup); Filter „Alle" zeigt aktuelle 90 Tage Default
Klartext-Hinweise
- Leerer Center: „Keine Benachrichtigungen — sobald etwas Wichtiges passiert, erscheint es hier."
- Filter ohne Treffer: „Keine Benachrichtigungen passen zu deinem Filter. [Filter zurücksetzen]"
- Mark-all-as-read mit > 50: „124 Benachrichtigungen als gelesen markieren? [Bestätigen] [Abbrechen]"
- Email-Bounce-Hinweis (siehe B.2)
Block E — Pro-User-Präferenzen
Routen-Spezifikation /settings/notifications/preferences
Zu zeigende Daten
- Liste aller Event-Typen, gruppiert nach Modul (CRM, Leads, Projekte, Aufgaben, Termine, Chat, ...)
- Pro Event-Typ:
- Event-Label (Klartext, z.B. „Mir wird ein Lead zugewiesen")
- Toggle pro Kanal (In-App, Email, Push)
- Priority-Threshold-Selektor (
all | normal+ | high+ | urgent only) - Aktueller Default-Hinweis falls User noch nicht angepasst
Benötigte UI-Elemente
- Sektionierte Anzeige nach Modul
- Pro Event-Typ: 3 Toggles (In-App, Email, Push) + Priority-Selektor
- Search-Funktion über Event-Label
- „Alle Email-Notifications deaktivieren"-Master-Toggle (mit Klartext: betrifft auch zukünftige Event-Typen)
- „Auf Default zurücksetzen"-Funktion pro Sektion
- „Default-Set für meine Rolle anwenden"-Funktion
Operationen
- Toggle pro Kanal pro Event
- Priority-Threshold setzen
- Bulk-Operationen (Master-Toggles, Reset)
- Speichern explizit oder auto-save (Designer-Wahl, technisch beides praktikabel)
Default-Sets
Beim Onboarding seedet das System ein Preference-Set abhängig von der primären Rolle:
- Vertriebler: In-App + Push für Lead/Deal-Events; Email für Daily-Digest (Phase 2)
- Projektleiter: In-App + Push für Projekt-/Task-Events; Email für Termin-Erinnerungen
- Monteur: In-App + Push für Task-Zuweisungen, Plantafel-Änderungen, Acceptance-Anforderungen; Email aus Default
- Büro/Backoffice: Alle Kanäle für Eingang-Events (Lead, Mail, Form); reduziert für interne Events
- GF: Daily-Digest per Email; Push für Eskalationen (
high/urgent) - Marketing: Email für Kampagnen-Status; In-App für Lead-Events
LP-3, AV #3: Defaults sind deklarative Templates, keine Hardcode.
Klartext-Hinweise
- Master-Toggle „Alle Email aus": „Du erhältst keine Email-Notifications mehr — auch nicht für neue Event-Typen, die wir später hinzufügen. Wichtige Sicherheits-Mails (Login, Passwort) bleiben immer aktiv."
- Push deaktiviert auf Geräte-Ebene: Banner „Push ist auf diesem Gerät deaktiviert. Toggles oben sind ohne Wirkung. [Geräte-Einstellungen]"
- Reset auf Default: „Bist du sicher? Deine bisherigen Einstellungen werden verworfen."
Block F — Ruhezeiten
Routen-Spezifikation /settings/notifications/quiet-hours
Zu zeigende Daten
- Liste der konfigurierten Ruhezeiten
- Pro Ruhezeit: Wochentag(e), Start-Zeit, End-Zeit, Toggle aktiv, Urgent-Override-Toggle
Benötigte UI-Elemente
- Anlage-Funktion mit Wochentag-Picker (Multi-Select inkl. Quick-Wahl „Wochentags" / „Wochenende" / „Täglich")
- Time-Picker für Start + End
- Toggle „Auch ‚Urgent'-Notifications zurückhalten" (Default aus — Urgent kommt durch)
- Edit-Funktion pro Eintrag
- Lösch-Funktion
- Master-Toggle „Ruhezeiten aktiv" (für Urlaub aussetzbar)
Default-Sets
- Default-Ruhezeit beim Onboarding für Mobile-Push: 22:00–07:00 täglich + Wochenende ganztägig mit Urgent-Override AUS
- User kann Default annehmen, anpassen oder deaktivieren
Wirkungs-Logik
- Wenn Notification außerhalb Ruhezeit ankommt → normaler Versand
- Wenn Notification innerhalb Ruhezeit:
- In-App: immer geliefert (sichtbar im Center, kein Pop-up/Sound)
- Email: gequeued bis Ruhezeit-Ende — Versand am ersten erlaubten Zeitpunkt (Bundle dabei aktiv)
- Push: gequeued bis Ruhezeit-Ende — Versand mit aktualisiertem Bundle-Count
- Urgent-Override = aus (Default Urgent-aktiv): Urgent-Notification trotz Ruhezeit sofort
- Urgent-Override = aktiv: auch Urgent-Notifications werden zurückgehalten
Klartext-Hinweise
- Bei Anlage: „Während der Ruhezeit bekommst du keine Push und keine Mails — Benachrichtigungen werden gesammelt zugestellt, sobald die Ruhezeit endet. [Urgent-Override]"
- Bei Urgent-Override-AUS-Bestätigung: „Auch dringende Benachrichtigungen kommen erst nach der Ruhezeit an — sicher?"
- Konflikt mehrere Ruhezeiten überlappen: „Diese Ruhezeit überschneidet sich mit ‚X' — beide bleiben aktiv (Vereinigung der Zeitfenster)."
Block G — Anti-Spam-Bündelung (Lücke L-17)
Bündelungs-Regeln
- Bei mehreren Notifications gleichen
event_type_groupan gleichen User innerhalb 5 Minuten (Default, Tenant-Admin-konfigurierbar pro Event-Group):- Kein einzelner Versand pro Push/Email
- Stattdessen: NotificationBundle wird angelegt/erweitert
- In-App: jede Einzel-Notification bleibt einzeln sichtbar (Wahrheit), aber Real-time-Toast/Badge nur einmal
- Push: ein Push pro Bundle mit
count+ Summary - Email: ein Mail pro Bundle nach Bundle-Window-Ende
- Bündelungs-Fenster läuft sliding: bei jedem neuen Event innerhalb 5 Min wird Counter erhöht; nach 5 Min ohne neuen Event wird Bundle geschlossen und ggf. nachgereicht falls Push noch nicht raus war
- Maximaler Bundle-Inhalt: 100 Events; danach neue Bundle-Instanz
Bündelungs-Beispiel
- 23 neue Leads in 4 Min → 1 Push: „23 neue Leads in den letzten 5 Minuten. [Lead-Inbox öffnen]"
- 7 Tasks in 5 Min an Monteur zugewiesen → 1 Push: „7 neue Aufgaben — [Aufgaben öffnen]"
- 50 Chat-Messages in 5 Min im Projekt-Channel → 1 Push: „50 neue Nachrichten in ‚Müller Heizung'"
Bündelungs-Ausschlüsse
priority = urgent→ nie gebündelt, sofort versendetevent_typemitbundle_disabled = true(z.B. Login-Sicherheits-Warnungen, 2FA-Codes-Notifications)- Direkt-Mention im Chat (
@user) → nie gebündelt mit anderen Mentions
Tenant-Admin-Setting
/admin/notifications/templates(Phase 1: read-only Anzeige) zeigt Bundle-Window pro Event-Group- Phase 2: Tenant-Admin kann Bundle-Window pro Event-Group ändern (z.B. längere Bündelung für interne Eskalationen)
Klartext-Hinweise
- Push-Body: „23 neue Leads in den letzten 5 Min — [Inbox öffnen]" statt 23 einzelne Pushes
- Email-Subject: „HiveGrid: 23 neue Leads" statt 23 einzelne Mails
- In Notification-Center bei Bundle-Eintrag: „23 Events gebündelt — [Alle anzeigen]"
Block H — Mobile-Device-Registrierung
Routen-Spezifikation /settings/notifications/devices
Zu zeigende Daten
- Liste aller registrierten Devices des Users
- Pro Device:
device_label,device_kind(iOS/Android),os_version,app_version,registered_at,last_seen_at - Status-Marker:
aktiv/inaktiv > 30 Tage/revoked
Benötigte UI-Elemente
- Listen-Anzeige
- Pro Device: Test-Push-Funktion, Umbenennen, Revoke-Funktion
- Globaler „Alle Devices abmelden"-Button
- Hinweis bei keinem Device: „Noch kein Mobile-Device verbunden — installiere die HiveGrid-App und logge dich ein, um Push-Notifications zu erhalten. [App-Store-Link]"
Operationen
- Test-Push (sendet Klartext-Test: „Test-Push von HiveGrid")
- Device umbenennen
- Device revoken (Push-Token wird entwertet, Eintrag bleibt mit
revoked_at) - Bulk-Revoke
Registrierungs-Flow (aus Mobile-App)
- User loggt sich in Capacitor-App ein (Modul 36)
- App fragt OS-Push-Permission ab
- Bei Erlaubt: App holt FCM-/APNs-Token, sendet via
/api/v1/notifications/mobile-device(Self-Scope, kein API-Key nötig — eingeloggter User) - Server prüft: Token bereits registriert? → Update
last_seen_at. Sonst: neue NotificationDevice-Entity - Test-Push optional vom Server, um Token-Validität zu bestätigen
Token-Invalidierungs-Handling
- Bei Push-Versand-Fehler
InvalidTokenvon APNs/FCM → Device wird automatisch revoked - Bei User-Logout: Device wird revoked
- Bei Tenant-Wechsel: Device bleibt aktiv für aktuellen Tenant (User kann mehrere Tenants haben — Push pro Tenant)
- Bei User-Deaktivierung im Tenant: Device-Beziehung zu diesem Tenant gelöscht, kein Push mehr
Permissions
- Self-Scope: User sieht und verwaltet nur eigene Devices
- Tenant-Admin sieht keine User-Devices anderer User (Privacy)
Klartext-Hinweise
- Device inaktiv > 30 Tage: „Dieses Gerät hat sich seit X Tagen nicht gemeldet. [Revoken]"
- Test-Push fehlgeschlagen: „Push-Test fehlgeschlagen — möglicherweise wurden Push-Berechtigungen am Gerät widerrufen. [Geräte-Einstellungen]"
- Push-Quota erschöpft (extremer Edge-Case): „Versand-Limit erreicht — versuche es in einer Stunde erneut."
Block I — Event-Typen-Katalog
Dies ist ein Auszug. Vollständiger Katalog entsteht modulweise mit Modul-Specs.
Lead-Events (Modul 2)
event_type |
Default In-App | Default Email | Default Push | Bundle-Group |
|---|---|---|---|---|
lead.created |
ja | nein | rolle-abhängig | lead.created |
lead.assigned_to_me |
ja | rolle-abhängig | ja | lead.assigned |
lead.unassigned |
ja | nein | nein | lead.assigned |
lead.responded |
ja | nein | nein | (nie gebündelt) |
lead.spam_marked |
ja | nein | nein | lead.spam |
lead.source_paused (Anomalie) |
ja | ja | ja (urgent) | (nie gebündelt) |
Deal-Events (Modul 3)
deal.assigned_to_me,deal.stage_changed,deal.won,deal.lost,deal.stuck(Eskalation)
Projekt-/Task-Events (Modul 4, 26)
project.assigned_to_me,project.stage_changed,project.acceptance_requestedtask.assigned_to_me,task.due_soon,task.overdue,task.completed_by_other
Termin-Events (Modul 6, 25)
appointment.scheduled,appointment.reminder_24h,appointment.reminder_1h,appointment.cancelled,appointment.rescheduled
Chat-Events (Modul 13)
chat.mention(Direkt-Mention@user),chat.dm_received,chat.thread_reply
Email-/Telefonie-Events (Modul 9, 12)
email.received_personal,email.bounce,call.missed,call.voicemail
Automation-Events (Modul 17)
automation.execution_failed,automation.dry_run_completed,automation.rate_limit_hit
Auth-/Sicherheits-Events (Modul 27)
auth.new_device_login(high),auth.password_changed(high),auth.2fa_disabled(urgent)- Diese sind bundle_disabled und immer-aktiv (kein Opt-Out)
Customer-Portal-Events (Modul 15)
portal.user.commented,portal.user.approved,portal.user.uploaded_file
KWP-/Integration-Events (Modul 19, 33a)
kwp.sync_failed,kwp.schema_drift_detected,integration.disconnected
System/Admin-Events
tenant.frozen,tenant.past_due(urgent),subscription.payment_failed,audit.export_completed
Block J — Versand-Pipeline
Architektur (Stichworte)
- Producer: alle Module rufen
notificationService.send({ recipientUserId, eventType, subject, ... })auf - Resolver: lädt User-Preferences und Quiet-Hours, entscheidet pro Kanal Send/Skip
- Bundle-Manager: prüft offenes Bundle für Recipient + Event-Group, hängt an oder erstellt neu
- Queue: BullMQ (oder gleichwertig — Implementation-Detail) mit Worker pro Kanal
- Senders:
- In-App: schreibt
Notification-Row + sendet SSE-Event - Email: render Template mit i18n + Branding, sendet via Sending-Domain (Modul 9)
- Push: ruft Novu-API mit gerendertem Payload pro aktivem Device
- In-App: schreibt
- Status-Tracker: schreibt
delivery_statuszurück bei Erfolg/Fehler - Retry-Logik: 3x mit Backoff bei transienten Fehlern (SMTP-Timeout, FCM-503); kein Retry bei Permanent-Fehlern (InvalidToken, Hard-Bounce)
- Audit: Versand wird nicht ins Modul-21-Audit geloggt (zu hohe Frequenz; eigenes Versand-Log in
delivery_statusreicht). Ausnahme: Versand-Fehlerurgentwerden auditiert.
EU-Stack (LP-13)
- Email-Versand über EU-SMTP (Mailersend EU oder Resend EU oder selbst-gehostet auf Scaleway)
- Push über Novu (Self-Hosted auf Scaleway oder EU-Cloud); APNs/FCM sind Kanäle, dort unausweichlich aber nur Token + minimaler Payload (kein PII-Datenleck)
- Push-Payload: kein PII außer Subject-Name; Detail nur via Deeplink + App-Login
Failure-Handling
- Email-Hard-Bounce → User-Setting auf Email-aus für 7 Tage + Notification im Center
- Push-InvalidToken → Device revoked, kein Re-Try
- SSE-Disconnect → Polling-Fallback im Client
Block K — Permissions-Anwendung
Permission-IDs
| Permission | Erlaubt |
|---|---|
| (Self-Scope) | Eigenes Notification-Center, eigene Präferenzen, eigene Ruhezeiten, eigene Devices — kein Permission-Bundle nötig |
notifications.admin |
Email-Templates lesen (P1), Test-Notifications senden, Bundle-Settings ändern (P2) |
Bundle-Mapping (Variante 2)
| Bundle | Atomare Permissions |
|---|---|
notifications.none |
(keine — Notifications laufen Self-Scope) |
notifications.admin |
notifications.admin |
Anwendung in Routes
/notifications,/notifications/:id→ eingeloggter User (Self-Scope)/settings/notifications/*→ eingeloggter User/admin/notifications/*→tenant.adminODERnotifications.admin/api/v1/notifications/mobile-device→ eingeloggter User (Token-Reg ist Self-Scope)
Cross-User-Notifications
- User kann nicht direkt Notification an andere User senden — nur über Modul 17 (Automation Send-Notification-Action) oder explizite User-Interaktionen (z.B. Chat-Mention, Task-Zuweisung)
- Send-Notification-Action in Automation Engine erfordert
automation.writeundautomation.run-Permissions auf das Automation-Subject
Klartext-Fehler
- Push registrieren ohne Login: 401 mit „Bitte zuerst einloggen."
- Test-Notification ohne Permission: nicht sichtbar
- Notification eines anderen Users öffnen: 404 (nicht 403, um Existenz nicht zu offenbaren)
Block L — Klartext-Hinweise
Im Notification-Center:
- Leerer Center: „Keine Benachrichtigungen — sobald etwas Wichtiges passiert, erscheint es hier."
- Email-Bounce: „Emails an dich kommen aktuell nicht an — bitte Email-Adresse prüfen. [Profil]"
- Push-Permission-Denied: „Push ist auf diesem Gerät deaktiviert. [Geräte-Einstellungen]"
- Bundle-Eintrag: „23 neue Leads — [Alle anzeigen]"
In Settings:
- Alle Email-aus: „Du bekommst keine Email-Notifications mehr (außer Sicherheit). [Wieder aktivieren]"
- Alle Push-aus: „Du bekommst keine Push-Notifications mehr — Mobile-App-Benachrichtigungen sind komplett aus."
- Ruhezeit-Konflikt: „Diese Ruhezeit überschneidet sich mit ‚X' — Vereinigung der Fenster aktiv."
- Default-Reset: „Deine bisherigen Einstellungen werden auf den Standard für deine Rolle zurückgesetzt — sicher?"
Beim Versand-Fehler:
- „Tenant ‚X' ist im Frozen-Modus — Notifications werden nicht versendet." (interne Log-Meldung, sichtbar in
delivery_status) - „Empfänger-User wurde deaktiviert — Notification wurde nicht gesendet."
Bei Anomalie:
- An Tenant-Admin (urgent, kein Bundle): „Notification-Versand zeigt ungewöhnliches Aufkommen (5x normal). Bitte Automationen prüfen — möglicherweise Loop. [Automation-Studio]"
Bei Push-Token-Revoke:
- „Gerät ‚iPhone von Max' wurde abgemeldet — kein Push mehr an dieses Gerät."
Bei Test-Push-Fehler:
- „Push-Test fehlgeschlagen — möglicherweise wurden Push-Berechtigungen am Gerät widerrufen oder die App ist nicht installiert."
Block M — Phase 2 / spätere Features
- Daily-Digest-Email (statt Einzel-Mails: tägliche Zusammenfassung aller Notifications mit Bundle-Logik über Tag)
- Snooze-Funktion (Notification verbergen für X Stunden, dann wieder im Center)
- WhatsApp als Notification-Kanal (Phase 2 Modul 11)
- Tenant-Admin-konfigurierbare Bundle-Windows pro Event-Group
- Tenant-Admin-konfigurierbare Email-Templates (mit Branding)
- Notification-Schedule-Rules (z.B. „Lead-Notifications nur Mo-Fr 8-18")
- Cross-Device-Read-Sync (Mark-as-read auf Desktop schließt Push-Banner auf Mobile)
- Notification-Anomalie-Detection-Auto-Pause (KI erkennt Notification-Storms, pausiert Quelle, alarmiert Admin)
- Silent-Push für Hintergrund-Sync (Mobile-App syncronisiert Daten ohne sichtbare Notification)
- Notification-Read-Receipts in Chat (Modul 13 spezifisch)
- Custom-Sound-Schemas pro Priority (Mobile)
- Notification-Pinning (User pinnt Wichtiges oben im Center)
- Auto-Cleanup (Notifications älter als 90 Tage hard-gelöscht; Tenant-Admin-konfigurierbar)
- Multi-Language-Email-Templates (User-Sprache in
Contact.languagefür Outbound; intern ausUser.language) - Browser-Notification-Channel (Web-Push-API als 4. Kanal — dort wo User keine Mobile-App hat)
Architektur-Vorschriften (Querschnitt)
- AV #1, LP-10: Klartext-Diagnostik überall (Bounce, Permission-Denied, Bundle-Hinweis, Versand-Fehler)
- AV #5: Self-Scope-Default — User sieht nur eigene Notifications/Devices
- AV #6: Versand-Status in
delivery_status; Sicherheits-relevante Versand-Fehler werden ins Modul-21-Audit geloggt - AV #16: Rate-Limiting + Anomalie-Detection für Notification-Versand (Schutz vor Loop-getriebenen Storms)
- AV #20: KI-Action-Boundary — KI darf Notifications senden nur über Automation-Action mit User-bestätigtem Trigger
- LP-2: Mobile-App ist Push-Konsument (Modul 36), nicht Producer — alle Producer sind Server-side
- LP-8: Apple-Compliance — Permission-Flow mit Pre-Prompt-Erklärung; keine Pricing-/Upgrade-Inhalte in Push
- LP-12: Email-/Push-Templates aus Locale-Files; Phase 1 nur DE
- LP-13: EU-Stack — SMTP über EU-Provider, Push-Provider Novu auf Scaleway
- LP-3, AV #3: Default-Preference-Sets pro Rolle als deklarative Templates
Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 22. Vor Bau: Verifizierung mit Noah (zusammen mit Pflichtenheft-Sweep) und Modul 36 (Mobile-App) für Capacitor-Push-Flow-Detail. Bei Implementierung Novu-Konfiguration, Email-Sending-Domain (Modul 9-Integration) und APNs-/FCM-Credentials-Setup.
Offene Detail-Punkte (nicht-blockierend):
- Konkrete Default-Preference-Sets pro Rolle finalisieren (mit Noah am Geerkens-Use-Case)
- Bundle-Window-Default 5 Min validieren (ggf. event-group-spezifisch anders)
- Email-Template-Set Phase 1 (Welche Templates pflegen wir initial: Lead, Task, Termin, Sicherheit, Auth, Subscription, ...)
- Annahme: kein Notification-Auto-Cleanup in Phase 1 (90 Tage UI-Filter, aber DB-Eintrag bleibt) — Validation mit Noah ob Auto-Hard-Delete gewünscht
- Annahme: Versand-Erfolge nicht ins Modul-21-Audit (zu hohe Frequenz) — nur Sicherheits-relevante Failures
- Push-Provider Novu vs. Direct-APNs/FCM: Novu-Abstraktion ist Defaultwahl (siehe Codebase-Inventory) — bei Bau ggf. Re-Eval
- Browser-Push (Web-Push-API) Phase 1 oder Phase 2: Phase 2 angenommen (Mobile-App-First gemäß LP-2)
Abhängige Module:
- Modul 27 (Auth/Permissions) — Self-Scope,
notifications.admin-Permission - Modul 17 (Automation) —
send-notification-Action - Modul 36 (Mobile-App / Capacitor) — Push-Token-Registrierung, Permission-Flow
- Modul 9 (Email-Inbox) — Sending-Domain für Notification-Mails
- Modul 31 (Branding) — Logo + Primärfarbe für Email-Templates
- Modul 21 (Audit-Log) — Sicherheits-Versand-Failures
- Modul 30 (i18n) — Email-/Push-Template-Strings aus Locale
- Alle Producer-Module (1, 2, 3, 4, 6, 9, 12, 13, 15, 17, 19, 25, 26, 27) — als Notification-Quellen