# 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 //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 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` | `.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_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.