Zum Inhalt

🔔 Push-Alert-Service – Overview

Ziel

Der Push-Alert-Service ermöglicht der Plattform, Benutzer proaktiv per Push-Nachricht zu informieren – direkt im Browser oder auf dem Smartphone, ohne dass die PWA geöffnet sein muss.

Zwei Betriebsmodi:

  1. Automatische Alerts – ausgelöst durch definierte Bedingungen in anderen Services (z. B. fehlende Mittagsbestellung, Trading-Ereignis), periodisch vom Scheduler geprüft
  2. Manuelle Alerts / Reminder – der Benutzer legt selbst Zeitpunkt und Inhalt fest

Zurückgebaut (2026-07-13): Ein dritter Modus, "Interne Sofort-Alerts" (PA-006/PA-007), wurde für die Sticky-Notification-Integration des Trade Optimizers gebaut, hat sich aber als nicht praktikabel erwiesen (Chrome für Android ignoriert requireInteraction). Beide REQs sind jetzt obsolete. Push/Alert für Trading wandert perspektivisch in eine eigene native App.

Kernfunktionen

  • Registrierung und Verwaltung von Push-Subscriptions (Web Push/VAPID für den Web-Touchpoint, FCM für die Trading Companion App)
  • Konfiguration von Alert-Regeln (automatisch & manuell)
  • Versand von Push-Nachrichten über beide Kanäle, je Empfänger-Subscription automatisch geroutet
  • Verwaltung des Alert-Verlaufs (gesendete Nachrichten, Status)
  • Plattform-API für andere Services, um Alerts auszulösen

Plattform-Integration

Komponente Beschreibung
Backend Integriert in bestehenden Backend-Container (kein eigener Container)
Frontend Service Worker + Push API Subscription in der bestehenden PWA
Datenbank Neue Tabellen im bestehenden PostgreSQL (schema: public)
Scheduler APScheduler im Backend prüft Bedingungen und löst automatische Alerts aus
Auth Nutzt bestehende Plattform-Auth (AUTH-001, USER-001)

Architektur

Browser (PWA)
  └── Service Worker registriert Push Subscription
  └── Subscription (endpoint, keys) → POST /api/alerts/subscription
         ↓
Backend (FastAPI)
  ├── /api/alerts/subscription  – Abo verwalten
  ├── /api/alerts/rules         – Alert-Regeln CRUD
  ├── /api/alerts/history       – Versandhistorie
  └── Scheduler (APScheduler)
        ├── Automatische Checks (stündlich / ereignisbasiert)
        └── Manuelle Reminder (zum konfigurierten Zeitpunkt)
         ↓
pywebpush (VAPID)
  └── Push-Nachricht → Browser Push Service (FCM / Mozilla / ...)
         ↓
Browser empfängt Nachricht (auch wenn PWA geschlossen)

Datenmodell

push_subscriptions

Feld Typ Beschreibung
id serial PK
user_id int FK Zugeordneter Benutzer
subscription_type enum [web_push, fcm] Kanaltyp, seit PA-001 v1.1
endpoint text, nullable Browser Push Endpoint URL – nur bei subscription_type=web_push
p256dh text, nullable Public Key (verschlüsselt) – nur bei subscription_type=web_push
auth text, nullable Auth Secret – nur bei subscription_type=web_push
fcm_token text, nullable FCM-Token – nur bei subscription_type=fcm, seit PA-001 v1.1
user_agent text Browser-/Geräte-Info (optional)
active bool Abo aktiv
created_at timestamptz

alert_rules

Feld Typ Beschreibung
id serial PK
user_id int FK Eigentümer
type enum automatic / manual
service varchar Auslösender Service (z. B. lunch, trading)
trigger_key varchar Bezeichner der Bedingung (z. B. missing_order)
title varchar Titel der Push-Nachricht
body text Inhalt der Push-Nachricht
url varchar Ziel-URL beim Klick (optional)
schedule_at timestamptz Zeitpunkt für manuelle Alerts (null = automatisch)
active bool Regel aktiv
created_at timestamptz

alert_history

Feld Typ Beschreibung
id serial PK
rule_id int FK Zugehörige Regel (null bei ad-hoc/Sofort-Versand)
user_id int FK Empfänger
trigger_key varchar Bezeichner der Bedingung (z. B. missing_order)
tag varchar, nullable ⚠️ Ungenutzt seit Rückbau von PA-006/PA-007 (2026-07-13); war für Sofort-Alerts vorgesehen
sent_at timestamptz Versandzeitpunkt
status varchar sent / failed / skipped
error text Fehlerdetails (bei failed)

Technischer Stack

Schicht Technologie
Push-Versand pywebpush (VAPID) für web_push, Firebase Admin SDK für fcm (seit PA-001 v1.1)
Scheduling APScheduler (im bestehenden Backend)
Frontend Service Worker API + Push Manager (Web Standard) für web_push
Native App Firebase Cloud Messaging SDK (Trading Companion App, siehe APP-003)
DB PostgreSQL (bestehende Instanz)
Auth JWT (bestehende Plattform-Auth)

VAPID-Konfiguration

VAPID erfordert ein Schlüsselpaar (einmalig generiert):

# Einmalig auf dem Server ausführen:
python3 -c "from py_vapid import Vapid; v = Vapid(); v.generate_keys(); print(v.private_key, v.public_key)"

Die Schlüssel werden als Umgebungsvariablen konfiguriert:

Variable Beschreibung
VAPID_PRIVATE_KEY Privater VAPID-Schlüssel (Base64)
VAPID_PUBLIC_KEY Öffentlicher VAPID-Schlüssel (Base64, an Frontend übermittelt)
VAPID_SUBJECT Kontakt-URL oder mailto (z. B. mailto:admin@example.com)

FCM-Konfiguration (seit PA-001 v1.1)

Erfordert ein Firebase-Projekt und ein Service-Account-Credential:

Variable Beschreibung
FIREBASE_SERVICE_ACCOUNT_JSON Pfad zum oder Inline-Inhalt des Service-Account-Credentials

Genutzt ausschließlich vom Firebase Admin SDK beim Versand an subscription_type=fcm-Empfänger (Trading Companion App). Der Web-Touchpoint ist davon nicht betroffen.

Automatische Alert-Trigger

Service Trigger-Key Beschreibung Prüfintervall
lunch missing_order Kein Eintrag für Account in 2+ Wochen täglich 07:00
trading data_stale Data Layer hat seit >2h keine neuen Daten stündlich
system service_down Health-Check eines Services schlägt fehl alle 15 min

Weitere Trigger können ohne Plattformänderung registriert werden.

Abgrenzung

In Scope Out of Scope
Web Push über VAPID Native App Push (APNs / FCM direkt)
PWA-Subscription im Browser E-Mail-Benachrichtigungen
Automatische + manuelle Alerts Trading-Signale / Handelsempfehlungen
Alert-Verlauf (lesbar) Komplexes Alerting-System mit Eskalation

Changelog

Version Datum Änderungen
1.3 2026-07-13 FCM als zweiter Zustellkanal ergänzt (PA-001 v1.1), ausgelöst durch die Trading Companion App (APP-003). push_subscriptions um subscription_type und fcm_token erweitert; Firebase Admin SDK im Technischen Stack ergänzt. Web-Push/VAPID bleibt für den Web-Touchpoint unverändert.
1.2 2026-07-13 PA-006/PA-007 (Interne Sofort-Alerts) zurückgebaut – in der Praxis nicht praktikabel für den Trading-Anwendungsfall. Betriebsmodi wieder auf zwei reduziert; tag-Feld bleibt in alert_history, aber ungenutzt.
1.1 2026-07-08 Dritter Betriebsmodus ergänzt: Interne Sofort-Alerts (PA-006/PA-007), ausgelöst per Service-API durch andere Plattform-Services (erste Anwendung: Trade Optimizer, Sticky Notification für vorbereitete Orders). alert_history um Feld tag erweitert.
1.0 2026-06-25 Initiale Version