Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M22-notifications.md
T

28 KiB
Raw Blame History

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
LP-2
LP-8
LP-9
LP-10
LP-12
LP-13
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_id
  • event_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_id
  • device_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_version
  • registered_at, last_seen_at
  • revoked_at (NULL falls aktiv)

NotificationBundle (Anti-Spam-Bündelung)

  • id, tenant_id, recipient_user_id
  • created_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_id
  • weekday (Enum: mo | tu | we | th | fr | sa | su ODER weekend)
  • 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 auf push_token pro 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_count falls 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.admin ODER notifications.admin

Block D — Notification-Center

Zu zeigende Daten pro Notification

  • title als Hauptzeile
  • body als 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_at setzen — 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_group an 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 versendet
  • event_type mit bundle_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)

  1. User loggt sich in Capacitor-App ein (Modul 36)
  2. App fragt OS-Push-Permission ab
  3. Bei Erlaubt: App holt FCM-/APNs-Token, sendet via /api/v1/notifications/mobile-device (Self-Scope, kein API-Key nötig — eingeloggter User)
  4. Server prüft: Token bereits registriert? → Update last_seen_at. Sonst: neue NotificationDevice-Entity
  5. Test-Push optional vom Server, um Token-Validität zu bestätigen

Token-Invalidierungs-Handling

  • Bei Push-Versand-Fehler InvalidToken von 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_requested
  • task.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
  • Status-Tracker: schreibt delivery_status zurü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_status reicht). Ausnahme: Versand-Fehler urgent werden 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.admin ODER notifications.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.write und automation.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.language für Outbound; intern aus User.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