# 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 //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 `//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 //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 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_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. ## 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` | `.firebaseapp.com` | Auth-Domain | | `CMBNET_FCM_WEB_PROJECT_ID` | `CMBNET_FCM_PROJECT_ID` | Web-Projekt-ID | | `CMBNET_FCM_WEB_STORAGE_BUCKET` | `.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_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.