Files
Sternsinger/CMBNet/docs/FCM_ARCHITEKTUR.md
T

200 lines
9.5 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 und fordert ein Wake-Signal an. |
| `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 getrennten mobilen Client
eingereiht wird, versucht der Broker ein FCM-Signal. Mehrere Nachrichten
innerhalb des Queue-Cooldowns lösen nur ein Signal aus.
### 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 getrennten mobilen Clients. Ein kurzer Cooldown
verhindert versehentliche Doppelklicks.
## 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_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 zusammen mit den Client-Queues
aufgeräumt.
## 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_MANUAL_WAKE_COOLDOWN_SECONDS` | `15` | Cooldown für den Button |
| `CMBNET_FCM_SIGNAL_TTL_SECONDS` | `600` | FCM-TTL |
| `CMBNET_FCM_WAKE_POLL_INTERVAL_SECONDS` | `30` | Prüfintervall des Workers |
| `CMBNET_FCM_PUSH_TOKEN_RETENTION_MINUTES` | `1440` | Aufbewahrung verwaister Tokens |
## 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.