Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,619 @@
---
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