Add activity push notifications and registration patches

2026-09-15 08:31:45 +02:00
parent 7c801dfddd
commit 55174684af
38 changed files with 1096 additions and 42 deletions
@@ -0,0 +1,31 @@
+# Push Notifications
+
+## Umfang und Einstellungen
+
+Automatische Android-Pushs gibt es für neue Freundschaftsanfragen, Direktnachrichten und Veranstaltungseinladungen. Allgemeine Konzertänderungen und Kommentare lösen keine Pushs aus. Manuelle Firebase-Kampagnen sind getrennt und beachten die MetalCircle-Einstellungen nicht.
+
+`PUSH_ENABLED=false` ist der Standard. Erst nach [Firebase-Einrichtung](Firebase.md) wird der Versand aktiviert; während er deaktiviert ist, entstehen keine Versandaufträge für historische Aktivitäten.
+
+Im eigenen Profil lassen sich die drei Kategorien getrennt einstellen. Die Einstellungen gelten für alle angemeldeten Android-Geräte des Kontos; Android muss zusätzlich Benachrichtigungen erlauben. Ausschalten verwirft ausstehende Meldungen dieser Kategorie. Die zuletzt bei Anmeldung, Geräteanmeldung oder Sprachwechsel gewählte Sprache wird pro Konto in `notification_preferences.language` gespeichert. Der einzelne Sprachbutton bietet jeweils die andere Sprache DE/EN an.
+
+Pushs enthalten generische Texte, etwa „Neue Nachricht – Du hast eine neue Nachricht.“ Namen, Nachrichtentext und Veranstaltungstitel werden nicht auf den Sperrbildschirm übertragen. Android erhält eine zufällige Versandkennung und die Bindung an die aktuelle Sitzung. Im Vordergrund zeigt die WebView einen Hinweis zum Öffnen an; im Hintergrund übernimmt Android die Systembenachrichtigung.
+
+Beim Antippen prüft die App die Sitzung. `/notifications/{id}` prüft erneut Empfänger, Sitzung und Berechtigung und leitet zur Unterhaltung, Anfrage oder Veranstaltung weiter. Bereits gelesene Nachrichten, erledigte Anfragen, entfernte Einladungen oder blockierte Kontakte führen zur Übersicht.
+
+## Versand und Fehlerfälle
+
+Aktivität und Versandauftrag werden in derselben PostgreSQL-Transaktion gespeichert. Ein Hintergrund-Thread im FastAPI-Prozess verarbeitet `push_notifications`; ein zusätzlicher Broker oder Container ist nicht nötig. Mehrere Prozesse reservieren Aufträge über Zeilensperren und `SKIP LOCKED`.
+
+Aufträge entstehen nur für aktuell registrierte Geräte. Sie enthalten Geräte-/Session-Referenzen und einen Token-Fingerabdruck, keine Klartext-Tokens oder Nachrichteninhalte. Vor Versand werden Kategorie, Blockierungen, offener/ungelesener Zustand, Berechtigungen, Token und Sitzung geprüft. Geräte-/Session-Sperren koordinieren den Versand mit Logout und Tokenänderungen. Logout löscht Zuordnungen und Aufträge über Fremdschlüssel.
+
+Firebase Admin SDK 7.1.0 sendet über FCM. Vorübergehende Fehler und Konfigurationsfehler erhalten maximal drei Wiederholungen nach 60, 120 und 240 Sekunden. Nach vier Versuchen wird der Auftrag als fehlgeschlagen markiert. Nicht registrierte Tokens werden entfernt; Projekt-/Authentifizierungsfehler löschen keine Geräte. Logs enthalten nur feste Fehlerkategorien.
+
+Aufträge verfallen nach einer Stunde; FCM erhält fünf Minuten Gültigkeit. Der laufende Worker bereinigt Metadaten nach sieben Tagen (keine Bereinigung, solange er deaktiviert ist). Bei einem Prozessabbruch nach Firebase-Annahme und vor DB-Commit sind Doppelzustellungen nicht vollständig auszuschließen; die stabile Android-Kennung ersetzt Wiederholungen im Benachrichtigungsbereich.
+
+Bereits zugestellte Meldungen lassen sich serverseitig nicht zurückrufen. Die App leert eigene Benachrichtigungen beim Sitzungswechsel; generische Texte und Zielprüfung schützen zusätzlich. Ein kleiner Zeitraum zwischen letzter Berechtigungsprüfung und Netzwerkzustellung bleibt technisch bestehen.
+
+## Tests
+
+Automatisierte Tests nutzen isolierte lokale PostgreSQL-Schemas und simuliertes Firebase; sie senden keine echten Pushs. Nach der Zugangseinrichtung mit zwei Testkonten prüfen: Anfrage A → B, Freundschaft annehmen und Nachricht senden, private Veranstaltung mit Einladung für B; Vordergrund/Hintergrund, Antippen, EN/DE, Kategorien, Blockierung, entfernte Einladung sowie Logout/Benutzerwechsel. Keine Produktionsaktivitäten dafür verwenden.
+
+Ein [fertiger ChatGPT-Prompt](Firebase-Setup-Prompt.md) begleitet die Einrichtung.