teamwallet/docs/superpowers/specs/2026-08-04-notification-center-design.md

# Notification Center (Team-Benachrichtigungen)

Status: approved
Datum: 2026-08-04

## Kontext

TeamWallet protokolliert bereits viele team-relevante Ereignisse (Spieler hinzugefügt/deaktiviert,
Rollenänderung, Einladungslink erstellt/eingelöst) über den globalen `LoggingService` in `LogEntry`
— aber dieses Log ist admin-only, global (kein Team-Bezug, kein `teamId`), und kennt keinen
Lesestatus pro Nutzer. Ein normaler Spieler erfährt aktuell nicht, wenn in seinem Team etwas
passiert (z.B. er selbst deaktiviert wurde oder der Freigabelink rotiert wurde), außer er merkt es
zufällig.

Ziel: Ein Benachrichtigungscenter (Glocke oben rechts im Header mit Ungelesen-Badge und Dropdown),
das aktiven Team-Mitgliedern mit Login relevante Team-Ereignisse anzeigt, mit Sprung zur
betroffenen Stelle und einer Vollansicht-Seite für die Historie.

## Entscheidungen aus dem Brainstorming

- **Abgedeckte Events (v1)**: Spieler hinzugefügt/deaktiviert/reaktiviert, Team-Rolle geändert,
  Freigabelink aktiviert/rotiert, Einladungslink erstellt. Das Einlösen eines Einladungslinks selbst
  löst **keine** eigene Benachrichtigung aus (der Aufruf ist unauthentifiziert, reine
  Token-Validierung, oft nur eine Vorschau ohne tatsächlichen Beitritt) — der tatsächliche Beitritt
  wird stattdessen bereits durch das Event "Spieler hinzugefügt" abgedeckt.
- **Empfänger**: alle aktiven Player eines Teams mit verknüpftem User-Account (analog zur
  Mitgliedschaftsprüfung in `TeamAccessService`), abzüglich des Verursachers — wer eine Aktion selbst
  auslöst, bekommt dafür keine eigene Benachrichtigung.
- **Zustellung**: kein Echtzeit-Push (keine WebSocket/SSE-Infrastruktur im Projekt vorhanden).
  Stattdessen Polling des Ungelesen-Zählers alle 30s, passend zum bestehenden HTTP+Signal-Store-Muster
  des Frontends.
- **Datenmodell**: Fan-out beim Schreiben (`Notification` + eine `NotificationRecipient`-Zeile pro
  Empfänger mit eigenem Lesestatus) statt eines zentralen Events mit Read-Join-Tabelle oder einer
  Erweiterung von `LogEntry` — bei den hier üblichen kleinen Teamgrößen (typischerweise < 30 Spieler)
  ist der Schreib-Overhead irrelevant, die Leseabfragen (Ungelesen zählen, Liste je Nutzer, als
  gelesen markieren) bleiben dafür trivial.
- **Entkopplung**: Domain-Services lösen Business-Logik weiterhin unverändert aus und feuern danach
  nur ein Domain-Event über `@nestjs/event-emitter` (`EventEmitter2`) — ein zentrales
  `NotificationsModule` lauscht auf diese Events und legt die Benachrichtigungen an. Domain-Services
  kennen `NotificationsService` nicht; neue Benachrichtigungstypen erfordern nur einen neuen Listener,
  keine Änderung an bestehenden Services.
- **Klick-Verhalten**: Klick auf eine Benachrichtigung navigiert zur betroffenen Stelle (z.B.
  Mitgliederliste) und markiert sie als gelesen.
- **Vollansicht**: eigene, team-gescopte Seite mit paginierter Historie zusätzlich zum Dropdown
  (letzte 20 Einträge).

## Architektur / Komponenten

### 1. Backend: neues Modul `notifications/`

**Neue Entities** (`notifications/entities/`):

- `Notification`: `id`, `team` (ManyToOne `Team`), `event` (`NOTIFICATION_EVENT`-String-Union, eigene
  Typdatei analog `logging-event.type.ts`), `actorUserId`, `payload` (`text`-Spalte, JSON-serialisiert
  — enthält je Event die Felder für Anzeigetext + Deep-Link, z.B. `{ playerId, playerName }`),
  `createdAt`.
- `NotificationRecipient`: `id`, `notification` (ManyToOne `Notification`, `onDelete: 'CASCADE'`),
  `userId`, `read` (boolean, default `false`), `readAt` (nullable `Date`). Index auf
  `(userId, read, createdAt via notification)` bzw. praktisch auf `(userId, notificationId)` und
  zusätzlich ein Index auf `notification.team` + `userId` für die gefilterte Team-Ansicht.

**Domain-Events** (`notifications/events/`): reine Datenklassen, ein File pro Event-Familie —
`player-active-changed.event.ts`, `player-role-changed.event.ts`, `player-created.event.ts`,
`share-link-changed.event.ts`, `invite-link-created.event.ts`. Jede trägt mindestens `teamId`,
`actorUserId`, event-spezifische IDs/Namen für Text und Deep-Link.

**Emit-Punkte** (jeweils ein zusätzlicher `this.eventEmitter.emit(...)`-Aufruf **nach** erfolgreichem
Abschluss der bestehenden Logik, ohne deren Ablauf/Transaktion zu verändern):

- `team-members.service.ts` `setActive()` — nach `return this.dataSource.transaction(...)` erfolgreich
  resolved hat (Emit außerhalb des Transaktions-Callbacks, damit bei Rollback nie ein Event feuert).
- `team-members.service.ts` `setTeamRole()` — analog.
- `teams.service.ts` Player-Erstellung (Stelle, die aktuell `player_creation` loggt) — analog.
- `public-team-access.service.ts` `setEnabled()` / `rotate()` — hier gibt es aktuell **keine**
  Transaktion (nur `repository.save()`), Emit direkt nach erfolgreichem `save()`. Zusätzlich werden
  hier neue `LOGEVENT`-Werte `public_access_enabled`, `public_access_rotated` ergänzt (bisher fehlt an
  dieser Stelle jegliches Logging) und ein `LoggingService.info()`-Aufruf ergänzt, analog zu den
  anderen Services.
- `auth.service.ts` `createTeamInvite()` — nach dem bestehenden `logger.info(...)`-Aufruf, mit dem
  echten `actorUserId`-Parameter der Methode (nicht dem im bestehenden Log hart codierten `userId: 0`
  — dieser bestehende Log-Aufruf selbst bleibt unverändert, das Event nutzt aber den korrekten Actor).

**`NotificationsListener`** (`notifications/notifications.listener.ts`): ein `@OnEvent(...)`-Handler
pro Event-Typ, baut Anzeigetext + Deep-Link-Payload und ruft `NotificationsService.create(...)` auf.
Fehler im Handler werden abgefangen und via `LoggingService.error()` protokolliert statt propagiert —
ein Fehler beim Anlegen der Benachrichtigung darf die bereits committete Business-Aktion nicht
nachträglich als fehlgeschlagen erscheinen lassen.

**`NotificationsService`**:

- `create(teamId, event, actorUserId, payload)` — ermittelt Empfänger über dasselbe Query-Muster wie
  `TeamAccessService`/`PublicTeamAccessService` (aktive `Player` mit `user.id IS NOT NULL` für das
  Team, `actorUserId` ausgeschlossen), legt `Notification` + `NotificationRecipient`-Zeilen an.
- `listForUser(userId, teamId, cursor, limit)` — für Dropdown und Vollansicht.
- `getUnreadCount(userId, teamId)`.
- `markRead(recipientId, userId)` — prüft Eigentümerschaft der Recipient-Zeile.
- `markAllRead(userId, teamId)`.

**`NotificationsController`** (`version: '1'`, `AuthGuard('jwt')` + `TeamAccessService.assertMember`):

- `GET teams/:teamId/notifications?cursor=&limit=`
- `GET teams/:teamId/notifications/unread-count`
- `PATCH teams/:teamId/notifications/:id/read`
- `PATCH teams/:teamId/notifications/read-all`

**Retention**: `NotificationRetentionScheduler`, `@Cron(CronExpression.EVERY_DAY_AT_5AM)` (zeitlich
versetzt zu `LogRetentionScheduler` um 4 Uhr), löscht `Notification`-Zeilen älter als
`app.logRetentionDays` (gleiche Config wiederverwendet, kein neuer Config-Wert nötig) —
`NotificationRecipient` fällt per `onDelete: 'CASCADE'` automatisch mit weg. Gleiches
Fehlerbehandlung-Muster wie `LogRetentionScheduler` (try/catch, `logger.info`/`logger.error` mit
`log_retention_cleanup_run`-artigen neuen Events `notification_retention_cleanup_run`/`_fail`).

**Neue Dependency**: `@nestjs/event-emitter`, registriert via `EventEmitterModule.forRoot()` in
`app.module.ts` (neben dem bestehenden `ScheduleModule.forRoot()`).

**Registrierung**: `NotificationsModule` in `src/app.module.ts` ergänzen (analog
`CashboxExportModule`), exportiert `NotificationsService`/`EventEmitter2`-Nutzung für die
Domain-Services (bzw. Domain-Services importieren direkt `EventEmitterModule`/`EventEmitter2` aus
`@nestjs/event-emitter`, kein Import von `NotificationsModule` nötig — das ist der Kern der
Entkopplung).

**Migration**: eine neue TypeORM-Migration in `src/database/migrations` für `notification` und
`notification_recipient` inkl. der oben genannten Indizes.

**Neue `LOGEVENT`-Werte** in `logging-event.type.ts`: `public_access_enabled`,
`public_access_rotated`, `notification_retention_cleanup_run`, `notification_retention_cleanup_run_fail`.

### 2. Frontend

**Bell im Header** (`core/layout/shell/shell.html`/`shell.ts`): `mat-icon-button` mit
`notifications`-Icon, `matBadge` für den Ungelesen-Zähler (ausgeblendet bei 0), positioniert links
neben dem bestehenden Team-Switcher in der `shell-header`-Toolbar, `[matMenuTriggerFor]="notificationMenu"`
— gleiches `MatMenuModule`-Pattern wie der bestehende Team-Switcher.

**Dropdown** (`mat-menu`): Liste der letzten 20 Benachrichtigungen (Icon je Event-Typ, Text, relative
Zeit via Angular `DatePipe`/eigenes Pipe), "Alle als gelesen markieren"-Button oben, "Alle
anzeigen"-Link unten zur Vollansicht-Seite. Klick auf einen Eintrag: `markRead()` + Router-Navigation
zum Deep-Link (z.B. `/team/:teamId/members` mit Query-Param oder Fragment zum Hervorheben des
betroffenen Spielers, je nach Event-Typ auch andere Zielrouten wie die Team-Einstellungen für
Freigabelink-Events).

**Vollansicht-Seite** (`features/notifications/notifications.ts/html`, Route
`/team/:teamId/notifications`): einfache paginierte Liste (kein ag-grid nötig, da kein
Admin-Filterbedarf wie bei der Logs-Seite), gleiche Klick-Navigation wie im Dropdown.

**State**: neuer `NotificationsStore` (Signal-Service im Team-Kontext, analog `MyTeamsStore`) hält
`notifications`- und `unreadCount`-Signals. Pollt `unread-count` alle 30s via `interval()` +
`switchMap`, solange ein Team aktiv ist; die volle Liste wird nur bei Dropdown-Öffnen bzw.
Seitenaufruf der Vollansicht geladen (kein Dauer-Polling der ganzen Liste).

**Neues Model** (`models/notification.model.ts`): `NotificationEvent`-Union (Frontend-seitiges
Gegenstück zu `NOTIFICATION_EVENT`), `NotificationDto`, mit Mapping-Funktion Event-Typ → Icon/Text/
Zielroute (zentral an einer Stelle, damit neue Event-Typen nicht über die Komponente verstreut
behandelt werden müssen).

## Fehlerbehandlung

- Notification-Erstellung schlägt fehl → wird im `NotificationsListener` abgefangen und geloggt,
  bricht die ursprüngliche (bereits erfolgreich abgeschlossene) Aktion nicht nachträglich ab.
- `markRead`/`markAllRead` auf fremde bzw. nicht existente Recipient-Zeile → `NotFoundException`
  bzw. stiller No-Op bei `markAllRead` (nichts zu markieren ist kein Fehlerfall).
- Polling-Request schlägt fehl (Netzwerk) → Store behält den letzten bekannten Zählerstand, kein
  Fehler-Toast (nicht kritisch genug für eine Nutzerunterbrechung).

## Testing

**Backend**:

- `notifications.service.spec.ts` — Empfänger-Ermittlung (aktive Player mit User, Actor
  ausgeschlossen), Fan-out-Erstellung, `listForUser`/`getUnreadCount`-Filterung nach `teamId`+`userId`,
  `markRead`-Eigentümerprüfung, `markAllRead`.
- `notifications.listener.spec.ts` — pro Event-Typ: korrekter Aufruf von
  `NotificationsService.create` mit erwartetem Payload; Fehler im Service wird abgefangen und geloggt,
  nicht weitergeworfen.
- Bestehende Specs von `team-members.service.ts`, `public-team-access.service.ts`, `auth.service.ts`
  um Assertions ergänzt, dass das jeweilige Domain-Event nach erfolgreichem Abschluss emittiert wird
  (gemockter `EventEmitter2`), und bei Rollback/Fehler **nicht** emittiert wird.
- `notification-retention.scheduler.spec.ts` — analog `log-retention.scheduler.spec.ts`.
- `notifications.http.spec.ts` — Auth/Team-Membership erforderlich, Pagination, `read`/`read-all`.

**Frontend**:

- `notifications-store.spec.ts` — Polling-Intervall, Unread-Count-Update, Laden der Liste.
- `notifications-api.spec.ts` — korrekte HTTP-Calls.
- Bell/Dropdown-Komponenten-Spec — Badge-Anzeige bei >0, Klick markiert gelesen + navigiert,
  "Alle als gelesen"-Button.
- Vollansicht-Seiten-Spec — Pagination, Klick-Navigation.

## Bewusst nicht enthalten (YAGNI)

- Kein Echtzeit-Push (WebSocket/SSE) — Polling reicht für den Anwendungsfall und vermeidet neue
  Infrastruktur.
- Keine Benachrichtigung beim reinen Einlösen/Validieren eines Einladungslinks (unauthentifiziert,
  kein verlässlicher Actor, oft nur Vorschau ohne Beitritt).
- Keine Benachrichtigungseinstellungen pro Nutzer (z.B. E-Mail-Digest, Stummschalten einzelner
  Event-Typen) — alle aktiven Mitglieder mit Login sehen alle abgedeckten Events.
- Keine rollenbasierte Einschränkung der Empfänger (z.B. "nur Manager") — alle aktiven Mitglieder mit
  Login.
- Keine Browser-Push-Benachrichtigungen (Service Worker/Web Push) außerhalb der App.

## Verifikation

- **Backend-Unit-Tests**: siehe oben, alle grün, `nest build` sauber.
- **Frontend-Unit-Tests**: siehe oben, alle grün, `tsc --noEmit` + `ng build` sauber.
- **Manuell**: Backend + Frontend lokal starten, mit zwei Test-Usern im selben Team: User A
  deaktiviert einen Spieler, User B (nicht der deaktivierte Spieler selbst, aber Mitglied) sieht die
  Badge-Zahl nach kurzer Zeit (Polling) hochgehen, öffnet das Dropdown, sieht den Eintrag, klickt
  darauf → Navigation zur Mitgliederliste + Eintrag als gelesen markiert, Badge sinkt. Gleiches
  stichprobenartig für Rollenänderung, Freigabelink-Rotation und Einladungslink-Erstellung
  durchspielen. Vollansicht-Seite aufrufen und Pagination über mehrere erzeugte Einträge prüfen.