Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/_bmad-output/specs/M22-notifications.md
T

620 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
module: 22
title: Notifications
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-2, LP-8, LP-9, LP-10, LP-12, LP-13]
spec_style: 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