Files
Sternsinger/CMBNet/docs/FCM_ARCHITEKTUR.md
T

256 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# FCM-Aufwachsignale für mobile PWA-Clients
## Zweck
Mobile Webviews sollen gezielt aus dem Hintergrund geholt werden, damit sie
ihre WebSocket-Verbindung erneuern, die persistente Broker-Queue leeren und –
bei aktivierter Positionsübertragung – mindestens ein Positionsupdate senden.
Google Firebase Cloud Messaging (FCM) transportiert dabei **nur ein Signal**.
Chat-Nachrichten, Positionsdaten, Mandanten, Rollen und URLs der Anwendung
bleiben ausschließlich in der WebSocket-Kommunikation bzw. in der Datenbank.
Das Signal besteht aus einem Data-Payload mit den Feldern `type` und `reason`
(z. B. `queue`, `offline`, `manual`). Diese Metadaten dienen nur der
Protokollierung und der Entscheidung, ob ein sichtbarer Hinweis sinnvoll ist.
Sie sind kein Anwendungsinhalt.
## Beteiligte Komponenten
| Komponente | Aufgabe |
| --- | --- |
| `cmbnet/ws/broker.py` | Erkennt nicht zustellbare Nachrichten, trennt Verbindungen ohne Lebenszeichen und fordert ein Wake-Signal an. |
| `cmbnet/ws/heartbeat.py` | Sendet Code-1-Pings und prüft, ob Clients noch antworten. |
| `cmbnet/ws/push.py` | Periodischer Worker für den Offline-Timeout. |
| `cmbnet/services/fcm_service.py` | Firebase-Admin-Initialisierung und FCM-Versand. |
| `cmbnet/api/push.py` | Token-Registrierung, Abmeldung und manueller Wake-Button. |
| `static/js/sw.js` | Empfängt das FCM-Signal, weckt ein Fenster und zeigt ggf. eine Benachrichtigung. |
| `static/js/views/mobile.js` | Registriert das Token, verbindet den WebSocket neu und sendet die Position. |
| `templates/dispatcher*.html` | Radar-Button zum manuellen Wecken. |
## Ablauf
1. Die mobile PWA fordert nach Erlaubnis für Benachrichtigungen ein
FCM-Token an. Das Token wird über `POST /<tenant>/api/push/register`
zusammen mit Client-ID, Client-Typ und der Einstellung
`auto_position` gespeichert.
2. Der Broker puffert eine Nachricht für einen getrennten mobilen Client
wie bisher in `ws_client_queue`.
3. Zusätzlich prüft er, ob ein gültiges FCM-Token vorliegt und ob der Client
als getrennt gilt. Wenn ja, sendet er ein FCM-Aufwachsignal.
4. Der Service Worker wird durch FCM geweckt. Er kann selbst keine
WebSocket-Verbindung betreiben. Deshalb übergibt er den Impuls per
`postMessage` an ein bereits geöffnetes PWA-Fenster.
5. Die PWA baut den WebSocket neu auf. Der Broker liefert die Queue und die
Late Entries aus. Neue Nachrichten lösen wie bisher den In-App-Dialog aus.
6. Bei aktivierter automatischer Positionsübertragung sendet die PWA
mindestens eine Position. Zuerst wird eine frische Geolocation angefordert;
schlägt das im Hintergrund fehl, wird die letzte bekannte Position
verwendet.
7. Der Service Worker wartet über einen `MessageChannel` bis zu 20 Sekunden
auf die Bestätigung der PWA. Erst danach beendet er den Push-Event. Ist
kein Fenster erreichbar, zeigt er eine allgemeine Benachrichtigung an.
8. Ein Klick auf diese Benachrichtigung öffnet `/<prefix>/wake`. Die Route
leitet anhand der bestehenden Session in die passende mobile View. FCM
selbst enthält keine Mandanten- oder Rollen-URL.
## Trigger
### Gequeuete Nachricht
Sobald eine Nachricht mit Code `>= 99` für einen mobilen Client eingereiht
oder direkt an ihn gesendet wird, versucht der Broker ein FCM-Signal. Das gilt
bewusst auch dann, wenn der Client laut Broker noch als verbunden gilt: Auf
iOS bleibt dieser Status oft veraltet, obwohl der WebSocket nicht mehr
erreichbar ist. Mehrere Nachrichten innerhalb des Queue-Cooldowns lösen nur
ein Signal aus. Mit `CMBNET_FCM_WAKE_CONNECTED_CLIENTS=0` lässt sich das
zusätzliche Wecken verbundener Clients abschalten.
### Offline-Erkennung
Ein Client gilt nur dann als offline, wenn der Broker seine WebSocket-
Verbindung als beendet markiert hat (`ws_clients.disconnected_at`). Dafür gibt
es drei Wege:
1. Ein sauber geschlossener Socket wird in der WS-Route unmittelbar erkannt.
2. Die mobile View schließt ihren Socket beim Wechsel in den Hintergrund
(`visibilitychange`) bzw. beim Verlassen der Seite (`pagehide`). Damit ist
sie sofort offline, ohne auf einen Timeout warten zu müssen. Beim
Sichtbarwerden verbindet sie sich neu und frischt ihr FCM-Token auf.
3. Halb offene Verbindungen, bei denen das Gerät einschläft, ohne FIN/RST zu
senden, werden vom Heartbeat nach
`CMBNET_WS_CLIENT_OFFLINE_TIMEOUT_SECONDS` (Default 180) ohne Lebenszeichen
geschlossen. Als Lebenszeichen zählt ein Code-2-Pong oder jede andere
eingehende WebSocket-Nachricht des Clients.
4. Jeder WSGI-Worker hinterlässt ein Lebenszeichen in `ws_workers`. Clients
eines nicht mehr laufenden Workers – etwa nach einem Neustart – werden
automatisch als getrennt markiert. Das verhindert dauerhaft „verbundene“
Karteileichen in der Datenbank.
Ohne Schritt 3 und 4 blieben schlafende Geräte bzw. Clients aus einem alten
Prozess dauerhaft als „verbunden“ markiert und würden nie als Wake-Kandidaten
erscheinen. `ws_clients`-Einträge mit gültigem FCM-Token werden beim normalen
Client-Aufräumen nicht entfernt; das Token hat eine eigene, großzügigere
Aufbewahrungsfrist.
### Offline-Timeout
Ein periodischer Worker prüft getrennte Clients. Nach
`CMBNET_FCM_OFFLINE_WAKE_MINUTES` (Default 5 Minuten) wird ein Signal gesendet,
auch wenn keine Nachricht in der Queue liegt. Damit erhält die Gruppen-View
die Gelegenheit, ein Positionsupdate zu senden. Für die Gruppen-View gilt das
nur, wenn `auto_position` aktiviert ist; Dispatcher-Mobil-Clients werden
ebenfalls berücksichtigt, haben aber keine automatische Positionsübertragung.
### Manuell
Der Radar-Button im Desktop-Dispatcher und im mobilen Dispatcher ruft
`POST /<tenant>/api/push/wake` auf. Der mobile Dispatcher schränkt den Aufruf
auf die aktuell ausgewählte Gruppe ein, sofern eine Gruppe gewählt ist. Der
Desktop-Dispatcher weckt alle mobilen Clients mit gültigem Token – auch
solche, die der Broker noch als verbunden führt. Ein ausdrücklicher Klick
sendet immer; die Drosselung über `last_wake_at` gilt nur für automatische
Nachrichten-Wakes. So blockiert ein kurz zuvor automatisch versuchtes Signal
den Button nicht.
## Client-Typen
Nur diese Werte sind zugelassen:
- `group_view` für Accounts der Rolle `Gruppe`
- `dispatcher_mobile` für Accounts der Rolle `Dispatcher` oder `Administrator`
Der Typ wird beim Code-0-Handshake vom Client mitgesendet und serverseitig
gegen die Session-Rolle geprüft. Ohne gültigen Typ werden keine FCM-Tokens
angenommen und keine Wake-Signale versendet. Der Observer-View und der
Desktop-Dispatcher erhalten keine FCM-Behandlung.
## Datenbank
`ws_clients` wurde ergänzt um:
- `client_type`: Client-Typ für das FCM-Routing
- `last_wake_at`, `last_wake_reason`: Drosselung und Nachvollziehbarkeit
Neue Tabelle `ws_workers`:
- Lebenszeichen je WSGI-Worker (`started_at`, `heartbeat_at`)
- dient der Erkennung verwaister Clients nach einem Worker-Neustart
Neue Tabelle `ws_push_tokens`:
- ein FCM-Token ist projektweit eindeutig
- Zuordnung zu Mandant, Account, Client-ID und Client-Typ
- `auto_position` für die periodische Positionsweckung
- `invalid` für von FCM abgelehnte Tokens
Die Registrierung wird bei einem Reload mit neuer Client-ID auf die neue
Client-ID verschoben. Nach einer Token-Rotation wird das alte Token derselben
Webview entfernt. Verwaiste Tokens werden mit einer eigenen Frist aufgeräumt;
der zugehörige `ws_clients`-Eintrag bleibt so lange erhalten. Die
Client-Queues werden weiterhin nach der kürzeren Queue-Frist bereinigt.
Für die Kandidatenauswahl ist das Token maßgeblich, nicht ein vorhandener
`ws_clients`-Eintrag. Fehlt der Eintrag – etwa weil sich die PWA registriert
hat, bevor die WebSocket-Verbindung stand – legt `upsert_push_token` einen
Platzhalter an und der Wake-Worker findet das Token trotzdem. Beim
Programmstart werden fehlende Einträge für bereits registrierte Tokens
nachgetragen. Dadurch kann die Anzeige „registriert: X“ nicht mehr bei
„keine Clients gefunden“ stehen, solange die Tokens gültig sind.
Der manuelle Wake-Endpunkt prüft zusätzlich die tatsächliche Sendefähigkeit
des Servers (`firebase-admin` installiert, Service-Account gültig). Fehlt
etwas, liefert er HTTP 503 mit einer konkreten Fehlermeldung statt der
irreführenden Meldung „keine Clients gefunden“. Die Oberfläche zeigt diesen
Fehler direkt an.
## Mehrere Worker
Jeder WSGI-Worker besitzt einen eigenen Push-Worker. Die Kandidatenauswahl
erfolgt deshalb in einer SQLite-Transaktion (`BEGIN IMMEDIATE`). Der erste
Worker reserviert die Clients über `last_wake_at`; alle anderen sehen sie in
diesem Lauf nicht mehr. Der eigentliche FCM-Versand findet nach dem Commit
statt. Das verhindert doppelte Signale bei mehreren Gunicorn-Workern.
## Konfiguration
Alle Werte sind optional; ohne `CMBNET_FCM_ENABLED=1` bleibt FCM vollständig
inaktiv:
| Variable | Default | Bedeutung |
| --- | --- | --- |
| `CMBNET_FCM_ENABLED` | `0` | FCM aktivieren |
| `CMBNET_FCM_SERVICE_ACCOUNT_FILE` | – | Pfad zum Service-Account-JSON |
| `CMBNET_FCM_SERVICE_ACCOUNT_JSON` | – | Service Account als JSON-String |
| `CMBNET_FCM_PROJECT_ID` | aus Credentials | Firebase-Projekt |
| `CMBNET_FCM_WEB_API_KEY` | – | Öffentlicher Web-API-Key |
| `CMBNET_FCM_WEB_AUTH_DOMAIN` | `<projekt>.firebaseapp.com` | Auth-Domain |
| `CMBNET_FCM_WEB_PROJECT_ID` | `CMBNET_FCM_PROJECT_ID` | Web-Projekt-ID |
| `CMBNET_FCM_WEB_STORAGE_BUCKET` | `<projekt>.appspot.com` | Storage-Bucket |
| `CMBNET_FCM_WEB_MESSAGING_SENDER_ID` | – | Sender-ID |
| `CMBNET_FCM_WEB_APP_ID` | – | Firebase-Web-App-ID |
| `CMBNET_FCM_VAPID_KEY` | – | Web-Push-Zertifikat |
| `CMBNET_FCM_WEB_SDK_VERSION` | `10.14.1` | Firebase-JS-Version |
| `CMBNET_FCM_OFFLINE_WAKE_MINUTES` | `5` | Offline-Timeout |
| `CMBNET_FCM_QUEUE_WAKE_COOLDOWN_SECONDS` | `60` | Cooldown je Queue-Wake |
| `CMBNET_FCM_SIGNAL_TTL_SECONDS` | `600` | FCM-TTL |
| `CMBNET_FCM_WAKE_CONNECTED_CLIENTS` | `1` | Auch als verbunden geltende mobile Clients wecken (iOS) |
| `CMBNET_FCM_WAKE_POLL_INTERVAL_SECONDS` | `30` | Prüfintervall des Workers |
| `CMBNET_FCM_PUSH_TOKEN_RETENTION_MINUTES` | `43200` | Aufbewahrung nicht verbundener Tokens (30 Tage) |
| `CMBNET_WS_CLIENT_OFFLINE_TIMEOUT_SECONDS` | `180` | Zeit ohne Lebenszeichen bis zur Offline-Markierung |
## Beschränkungen und Konsequenzen bei PWAs
### Allgemein
- Ein Service Worker kann keine dauerhafte WebSocket-Verbindung halten und
keine Seite im Hintergrund starten. Das eigentliche Reconnecten und Senden
übernimmt immer ein PWA-Fenster.
- Ist die PWA vollständig geschlossen, kann FCM den Service Worker wecken,
aber nicht zuverlässig ein Fenster öffnen. Dann bleibt nur eine sichtbare
Benachrichtigung; der Nutzer muss sie antippen. Das ist eine Plattform- und
keine Implementierungsgrenze.
- Ein Wake-Signal ist eine Aufforderung, keine Garantie. Zustellung kann durch
Netz, Energiesparmodus, Firebase oder das Betriebssystem verzögert oder
zusammengefasst werden.
- Ein Positionsupdate ist nur möglich, wenn die Seite tatsächlich läuft und
der Browser Geolocation im Hintergrund erlaubt. Andernfalls wird die letzte
bekannte Position verwendet oder das Update entfällt.
- Die PWA muss über HTTPS ausgeliefert werden. Das Token ist ein
installationsbezogenes Geheimnis und sollte nicht geloggt werden.
- FCM ist ein Google-Dienst. Verfügbarkeit, Datenschutz und Netzwerkzugriffe
müssen betrieblich bewertet werden.
### Android (Chrome/Edge)
- Web Push funktioniert in der installierten PWA und im Browser, sofern
Benachrichtigungen erlaubt sind.
- Chrome kann Hintergrundtabs einfrieren. Der Service Worker bleibt für
Push-Events zuständig; die Seite wird beim `postMessage` möglicherweise
erst verzögert aktiv.
- Hersteller-Energiesparfunktionen und „App beenden“ verhindern Zustellungen.
- `clients.openWindow` ist aus einem Push-Event nicht zuverlässig erlaubt;
deshalb der Benachrichtigungs-Fallback.
### iOS/iPadOS (Safari)
- Web Push ist erst ab iOS/iPadOS 16.4 und nur für zum Home-Bildschirm
hinzugefügte PWAs verfügbar. In einem normalen Safari-Tab wird kein
FCM-Token registriert.
- Benachrichtigungen müssen ausdrücklich erlaubt werden. Ohne Erlaubnis
bleibt die App offline, bis sie manuell geöffnet wird.
- iOS kann Hintergrund-Pushes stark drosseln oder zusammenfassen. Ein
stilles Data-Push ist nicht garantiert; der sichtbare Benachrichtigungs-
Fallback ist Teil des Designs.
- Hintergrund-Geolocation ist stark eingeschränkt. Das garantierte
„mindestens ein Positionsupdate“ gilt deshalb nur, solange die Seite nach
dem Wake tatsächlich ausgeführt wird.
- APNs/FCM können die Zustellung verweigern, wenn die PWA vom Nutzer
entfernt oder die Benachrichtigungserlaubnis entzogen wurde.
### Konsequenz für die Bedienung
Die Funktion ist eine beschleunigte Synchronisierung, kein Ersatz für das
Öffnen der App. Disponenten sollten bei zeitkritischen Lagen weiterhin den
manuellen Radar-Button nutzen und die mobile Gruppe bei Bedarf zusätzlich
telefonisch erreichen.