Notification Contract¶

Diese Seite beschreibt den gemeinsamen Notification-Vertrag zwischen Backend, Web und Mobile. Sie ist die Referenz für Inbox-Daten, Mutationen und die serverseitig gespeicherten Notification-Preferences.

Zielbild¶

Die Notification-Inbox ist serverseitig die Quelle der Wahrheit.
Web und Mobile verwenden denselben API-Vertrag für list, read, read all, delete und clear.
Lokale Caches dienen nur als kurzfristiger Fallback für Offline-/Hydrationsfälle, nicht als eigenständige Inbox.
Notification-Preferences werden über /api/user/settings serverseitig gespeichert.

Inbox DTO¶

Ein einzelner Notification-Eintrag wird clientseitig auf diese Form normalisiert:

type NotificationRecord = {
  id: string
  title: string
  body?: string
  date: string
  tone: 'info' | 'success' | 'warning' | 'error'
  read: boolean
}

Regeln:

id muss stabil und eindeutig sein.
title ist Pflicht.
date wird als ISO-Zeitstempel geführt.
tone ist auf info | success | warning | error begrenzt.
read beschreibt ausschließlich den serverseitigen Inbox-Zustand.

Inbox Endpunkte¶

Die Clients sprechen primär diese Endpunkte an:

GET /api/notifications
POST /api/notifications/:id/read
POST /api/notifications/read-all
DELETE /api/notifications/:id
DELETE /api/notifications

Kompatibilitäts-Fallbacks sind clientseitig weiterhin erlaubt:

PATCH /api/notifications/:id/read
PATCH /api/notifications/read-all
POST /api/notifications/:id/delete
POST /api/notifications/clear

Die Fallbacks existieren nur, damit ältere oder leicht driftende Deployments nicht sofort brechen. Die kanonische Richtung bleibt der primäre Satz oben.

Producer-Regeln¶

Neue Notifications entstehen nur über die Backend-Service-Schicht, nicht aus lokalen Placeholder-Daten.

Aktuell angeschlossene Producer umfassen unter anderem:

Billing / Stripe / Keygen
Mitgliederaktionen
Scheduler / Event-Erinnerungen
Reports
Duell- und Challenge-bezogene Ereignisse

Client-Verhalten¶

Web¶

Die Glocke und der Toaster trennen serverseitige Inbox und lokale UI-Feedbacks.
Gelöschte Inbox-Einträge dürfen nicht aus localStorage wieder auftauchen.
Der aktuelle Stand wird nach read, read all, delete und clear wieder gegen die API abgeglichen.

Mobile¶

Mobile nutzt dieselben Inbox-Mutationen wie Web.
SecureStore dient nur als Cache für den zuletzt bekannten Serverstand.
Beim App-Resume und bei explizitem Refresh wird die Inbox erneut vom Backend geladen.

Notification Preferences¶

Notification-Preferences liegen unter /api/user/settings.

Kanonische Struktur:

type NotificationPreferences = {
  version: 1
  email: {
    enabled: boolean
    events: boolean
    invites: boolean
    categories: {
      training: boolean
      competition: boolean
      board: boolean
      youth: boolean
      club: boolean
    }
  }
  push: {
    enabled: boolean
    sound: boolean
  }
  summary: {
    mode: 'off' | 'daily' | 'weekly' | 'monthly'
    time: string | null
  }
  dnd: {
    enabled: boolean
    from: string | null
    to: string | null
  }
  reminders: {
    minutes15: boolean
    hour1: boolean
    hours24: boolean
    viaEmail: boolean
    viaPush: boolean
  }
  updates: {
    acceptDecline: boolean
    edits: boolean
    cancel: boolean
  }
}

Übergangsregel:

notifications.* ist die serverseitige Wahrheit.
Flache Root-Felder wie emailEnabled, categories, updates, pushEnabled werden nur noch als Legacy-Kompatibilitäts-Mirror behandelt.
Neue Clients sollen ausschließlich den kanonischen Block schreiben.

Verifikation¶

Der Track gilt erst dann als stabil, wenn diese Pfade abgesichert sind:

Backend-Build läuft durch.
Web-Build läuft durch.
Mobile-Typecheck läuft durch.
Mobile-Notification-Smoke deckt load, read, read all, delete, clear und Refresh-Verhalten ab.