261 lines
13 KiB
Markdown
261 lines
13 KiB
Markdown
# 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.
|
||
|
||
Der vollständige Ablauf vom Laden der PWA bis zur Reaktion auf das
|
||
Aufwachsignal – mit allen Funktionsnamen, Endpunkten und Fehlerpfaden – steht
|
||
in [`FCM_PROTOKOLL.md`](FCM_PROTOKOLL.md). Dort sind auch die Anforderungen an
|
||
Reverse Proxy, Service Worker, WebSocket und CORS beschrieben.
|
||
|
||
## 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.
|