15 – Notifications & Realtime

Reifegrad: 🟢 produktiv · Schicht: src/lib/notifications*.ts, src/lib/realtime-events.ts, src/lib/events.ts, src/lib/domain-events-bridge.ts, src/app/api/notifications/*, src/app/api/realtime/*, Tabelle notifications

Zweck

Nutzer in Echtzeit über relevante Ereignisse informieren (In-App-Benachrichtigungen) und UI-Ansichten (Plantafel, Listen, Urlaub) live aktualisieren – kanalübergreifend für Web- und Agent-Writes.

Persistente Benachrichtigungen

• Tabelle notifications: user_id, company_id, type, title, message, link_url, created_at, read_at.
• Erzeugung: emitNotification(...) (src/lib/notifications.ts) – schreibt in die DB und published das Event über Redis Pub/Sub an die Realtime-Bridge.
• Formatierung: src/lib/notifications-format.ts (mit Unit-Test notifications-format.test.ts).

Endpoint	Funktion
GET /api/notifications	Benachrichtigungen des Users
POST /api/notifications/mark-read	als gelesen markieren
POST /api/notifications/clear	leeren
GET /api/notifications/stream	SSE-Stream (Push)

Realtime-Bridge (Redis Pub/Sub → SSE)

src/lib/events.ts (notificationsEmitter) + src/lib/realtime-events.ts bilden eine provider-neutrale Event-Bridge. Da App und Agent denselben Domain-Layer nutzen, lösen Agent-Writes dieselben Realtime-Updates aus wie API-Writes (siehe adr-0002-shared-domain-layer).

Event-Typen (RealtimeStreamEvent):

Typ	Auslöser
notification	emitNotification
domain:changed	publishDomainEvent aus @work7/domain (CRUD auf Geschäftsobjekten)
leave:changed	Urlaubs-Workflow (siehe 07-urlaub-abwesenheit)
calendar:google / calendar:microsoft	Kalender-Webhooks (siehe 13-integrationen-google-microsoft-storage)

• src/lib/domain-events-bridge.ts verbindet @work7/domain-Events mit dem Emitter (emitDomainChanged).
• parseRealtimeStreamMessage / RealtimeStreamEvent typisieren die Wire-Messages.
• Streams: /api/realtime/* und /api/notifications/stream (Server-Sent Events).
• Tests: src/lib/realtime-events.test.ts, src/lib/notifications-format.test.ts.

Datenfluss

Weitere Benachrichtigungskanäle

• E-Mail: Microsoft Graph über no-reply@work7.net (Einladungen, Angebots-/Rechnungs-/ Rapportversand, Passwort-Reset).
• WhatsApp: ausgehende Nachrichten über den Agent / D360Client (siehe 11-whatsapp-agent).
• Termin-Benachrichtigungen: persistente Queue appointment_notifications (email/whatsapp/ics, siehe 06-termine-kalender-plantafel).

Bekannte Befunde / offene Punkte

• SSE skaliert pro Prozess; bei mehreren App-Replicas erfolgt der Fan-out über Redis Pub/Sub – korrekt, aber Verbindungslimits/Heartbeat im Auge behalten.
• notifications hat keine harte Aufbewahrungslogik (außer clear durch den Nutzer).

Verwandte Notes

• 07-urlaub-abwesenheit · 06-termine-kalender-plantafel · 11-whatsapp-agent
• 13-integrationen-google-microsoft-storage · adr-0002-shared-domain-layer