620 lines
28 KiB
Markdown
620 lines
28 KiB
Markdown
---
|
||
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
|