Firebase Cloud Messaging 1. Versuch
This commit is contained in:
1 parent
f1fb926c2f
commit
4c8b11c4d5
25 files changed
+2111
-31
No files matched your search
@@ -0,0 +1,199 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,241 @@
|
||||
# Firebase/FCM einrichten – Howto
|
||||
|
||||
Dieses Dokument beschreibt die praktischen Schritte, um die im Code
|
||||
vorbereiteten FCM-Aufwachsignale für die mobilen PWA-Ansichten zu aktivieren.
|
||||
FCM überträgt ausschließlich das Signal; Nachrichten und Positionen laufen
|
||||
weiterhin über WebSocket und die Broker-Queue. Die Architektur und die
|
||||
Plattformgrenzen stehen in [`FCM_ARCHITEKTUR.md`](FCM_ARCHITEKTUR.md).
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
- Ein Google-Konto und Zugriff auf die [Firebase Console](https://console.firebase.google.com/).
|
||||
- Die CMBNet-Installation läuft über **HTTPS** (auch im Test). Web Push und
|
||||
Service Worker funktionieren nicht über eine reine HTTP-Adresse, außer auf
|
||||
`localhost`.
|
||||
- Die mobile Ansicht ist als PWA installiert (zum Home-Bildschirm
|
||||
hinzugefügt). Besonders auf iOS/iPadOS ist das Voraussetzung für Web Push.
|
||||
- Python-Umgebung der Anwendung kann Pakete installieren.
|
||||
|
||||
## 1. Firebase-Projekt anlegen
|
||||
|
||||
1. In der Firebase Console **Projekt hinzufügen** wählen.
|
||||
2. Projektnamen vergeben (z. B. `cmbnet-push`) und die Analytics-Option nach
|
||||
Bedarf aktivieren. Für FCM ist Analytics nicht erforderlich.
|
||||
3. Nach dem Anlegen die Projekt-ID notieren. Sie wird später als
|
||||
`CMBNET_FCM_PROJECT_ID` bzw. `CMBNET_FCM_WEB_PROJECT_ID` verwendet.
|
||||
|
||||
## 2. Web-App registrieren
|
||||
|
||||
1. In den **Projekteinstellungen → Allgemein** unter *Meine Apps* die
|
||||
Plattform **Web** (`</>`) hinzufügen.
|
||||
2. Einen Spitznamen vergeben und die App registrieren.
|
||||
3. Den angezeigten `firebaseConfig`-Block notieren. Er enthält ausschließlich
|
||||
öffentliche Werte:
|
||||
|
||||
```js
|
||||
{
|
||||
apiKey: "...",
|
||||
authDomain: "cmbnet-push.firebaseapp.com",
|
||||
projectId: "cmbnet-push",
|
||||
storageBucket: "cmbnet-push.appspot.com",
|
||||
messagingSenderId: "...",
|
||||
appId: "..."
|
||||
}
|
||||
```
|
||||
|
||||
Diese Werte sind **keine Geheimnisse** und werden vom Server an Browser
|
||||
und Service Worker ausgeliefert. Der Service-Account aus Schritt 4 darf
|
||||
dagegen niemals in eine Webseite oder in das Repository gelangen.
|
||||
|
||||
## 3. Cloud Messaging und VAPID-Schlüssel
|
||||
|
||||
1. In der Firebase Console unter **Cloud Messaging** die Web-Push-
|
||||
Konfiguration öffnen.
|
||||
2. Falls noch kein Schlüsselpaar existiert, unter *Web-Push-Zertifikate*
|
||||
ein Schlüsselpaar erzeugen.
|
||||
3. Den angezeigten **VAPID-Schlüssel** (öffentlicher Schlüssel) notieren. Er
|
||||
wird als `CMBNET_FCM_VAPID_KEY` benötigt.
|
||||
4. Die Web-Push-Konfiguration muss zum selben Firebase-Projekt wie die
|
||||
Web-App gehören.
|
||||
|
||||
## 4. Service-Account für den Server erzeugen
|
||||
|
||||
1. In der Firebase Console **Projekteinstellungen → Dienstkonten** öffnen.
|
||||
2. **Neuen privaten Schlüssel generieren** wählen und die JSON-Datei
|
||||
herunterladen.
|
||||
3. Die Datei außerhalb des Repositories ablegen, z. B.
|
||||
`/etc/cmbnet/firebase-service-account.json`, und nur für den
|
||||
Anwendungsbenutzer lesbar machen:
|
||||
|
||||
```bash
|
||||
sudo install -m 600 firebase-service-account.json \
|
||||
/etc/cmbnet/firebase-service-account.json
|
||||
```
|
||||
|
||||
4. Alternativ kann der JSON-Inhalt als eine Zeile in
|
||||
`CMBNET_FCM_SERVICE_ACCOUNT_JSON` gesetzt werden. Für den Dauerbetrieb ist
|
||||
eine Datei mit restriktiven Rechten vorzuziehen, weil Umgebungsvariablen
|
||||
leichter in Prozesslisten oder Logs auftauchen.
|
||||
|
||||
## 5. Python-Abhängigkeit installieren
|
||||
|
||||
FCM nutzt das optionale Paket `firebase-admin`. Es ist in
|
||||
`requirements.txt` eingetragen, muss aber in der aktiven Umgebung installiert
|
||||
sein:
|
||||
|
||||
```bash
|
||||
cd CMBNet
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
Ohne dieses Paket startet die Anwendung weiterhin; FCM bleibt dann deaktiviert
|
||||
und protokolliert einen entsprechenden Hinweis.
|
||||
|
||||
## 6. Umgebungsvariablen setzen
|
||||
|
||||
Die Anwendung liest die Konfiguration aus Umgebungsvariablen (siehe
|
||||
`config.py`). Ein vollständiges Beispiel für einen Dienstmanager oder eine
|
||||
`.env`-Datei:
|
||||
|
||||
```bash
|
||||
CMBNET_FCM_ENABLED=1
|
||||
|
||||
# Serverseitiger Versand
|
||||
CMBNET_FCM_PROJECT_ID=cmbnet-push
|
||||
CMBNET_FCM_SERVICE_ACCOUNT_FILE=/etc/cmbnet/firebase-service-account.json
|
||||
# Alternativ statt der Datei:
|
||||
# CMBNET_FCM_SERVICE_ACCOUNT_JSON={"type":"service_account",...}
|
||||
|
||||
# Öffentliche Web-Konfiguration aus Schritt 2
|
||||
CMBNET_FCM_WEB_API_KEY=...
|
||||
CMBNET_FCM_WEB_AUTH_DOMAIN=cmbnet-push.firebaseapp.com
|
||||
CMBNET_FCM_WEB_PROJECT_ID=cmbnet-push
|
||||
CMBNET_FCM_WEB_STORAGE_BUCKET=cmbnet-push.appspot.com
|
||||
CMBNET_FCM_WEB_MESSAGING_SENDER_ID=...
|
||||
CMBNET_FCM_WEB_APP_ID=...
|
||||
|
||||
# Web-Push aus Schritt 3
|
||||
CMBNET_FCM_VAPID_KEY=...
|
||||
|
||||
# Optional: Zeitverhalten
|
||||
CMBNET_FCM_OFFLINE_WAKE_MINUTES=5
|
||||
CMBNET_FCM_QUEUE_WAKE_COOLDOWN_SECONDS=60
|
||||
CMBNET_FCM_MANUAL_WAKE_COOLDOWN_SECONDS=15
|
||||
CMBNET_FCM_WAKE_POLL_INTERVAL_SECONDS=30
|
||||
```
|
||||
|
||||
Die Datei mit den Umgebungsvariablen muss dieselben Rechte wie die
|
||||
Service-Account-Datei besitzen. Nach Änderungen den WSGI-Prozess neu starten;
|
||||
Python liest die Werte beim Start.
|
||||
|
||||
### Prüfen, ob die Konfiguration vollständig ist
|
||||
|
||||
`public_fcm_config()` aktiviert FCM nur, wenn `CMBNET_FCM_ENABLED` gesetzt ist
|
||||
**und** API-Key, Projekt-ID, Sender-ID, App-ID und VAPID-Schlüssel vorhanden
|
||||
sind. Prüfen lässt sich das über die vom Server erzeugte Datei:
|
||||
|
||||
```bash
|
||||
curl -s https://example.com/fcm-sw-config.js
|
||||
```
|
||||
|
||||
Erwartet wird ein JavaScript-Objekt mit `"enabled": true` und gefüllten
|
||||
`firebase`-Werten. Bei `"enabled": false` fehlt mindestens einer der oben
|
||||
genannten Werte oder `firebase-admin` ist nicht installiert.
|
||||
|
||||
## 7. Datenbankmigration
|
||||
|
||||
Beim nächsten Start führt `ensure_schema()` die idempotenten Migrationen aus.
|
||||
Neu sind die Spalten `ws_clients.client_type`, `ws_clients.last_wake_at`,
|
||||
`ws_clients.last_wake_reason` sowie die Tabelle `ws_push_tokens`. Eine
|
||||
manuelle Migration ist nicht nötig; ein Backup der SQLite-Datei vor dem
|
||||
ersten Start ist trotzdem empfehlenswert.
|
||||
|
||||
## 8. Mobile PWA installieren und Benachrichtigungen erlauben
|
||||
|
||||
1. Die mobile Ansicht (Gruppen-View bzw. mobiler Dispatcher) über HTTPS
|
||||
öffnen.
|
||||
2. Im Browsermenü **Zum Home-Bildschirm** bzw. **App installieren** wählen.
|
||||
3. Die PWA aus dem Home-Bildschirm starten.
|
||||
4. In den Einstellungen der mobilen Ansicht **Benachrichtigungen aktivieren**
|
||||
antippen und die Browserabfrage bestätigen.
|
||||
5. Danach lädt die Seite das Firebase-SDK, fordert ein FCM-Token an und
|
||||
registriert es über `POST /<tenant>/api/push/register`. Der Client-Typ
|
||||
(`group_view` bzw. `dispatcher_mobile`) wird dabei gegen die Rolle geprüft.
|
||||
|
||||
Auf iOS/iPadOS muss die App wirklich installiert sein; in einem normalen
|
||||
Safari-Tab wird kein Token registriert. Nach dem Entfernen der PWA vom
|
||||
Home-Bildschirm oder dem Entziehen der Benachrichtigungserlaubnis endet die
|
||||
Zustellung.
|
||||
|
||||
## 9. Funktion testen
|
||||
|
||||
### Token-Registrierung prüfen
|
||||
|
||||
Nach dem Aktivieren der Benachrichtigungen in der Datenbank nachsehen:
|
||||
|
||||
```bash
|
||||
sqlite3 instance/cmbnet.sqlite3 \
|
||||
"SELECT tenant_id, client_id, account_id, client_type, platform, auto_position, invalid
|
||||
FROM ws_push_tokens;"
|
||||
```
|
||||
|
||||
Es muss ein Eintrag für den mobilen Client vorhanden sein. Ein leeres Ergebnis
|
||||
bedeutet meist: keine HTTPS-Verbindung, keine installierte PWA, keine
|
||||
Benachrichtigungserlaubnis oder `enabled: false` in `fcm-sw-config.js`.
|
||||
|
||||
### Manuellen Wake auslösen
|
||||
|
||||
Im Desktop-Dispatcher oder im mobilen Dispatcher den Radar-Button antippen.
|
||||
Der Button ruft `POST /<tenant>/api/push/wake` auf. Die Antwort enthält
|
||||
`candidates`, `sent` und `failed`.
|
||||
|
||||
- `sent > 0`: FCM hat das Signal angenommen.
|
||||
- `candidates = 0`: kein getrennter mobiler Client mit gültigem Token.
|
||||
- HTTP 503: FCM ist nicht vollständig konfiguriert.
|
||||
- HTTP 403: Rolle darf nicht wecken (nur Dispatcher/Administrator).
|
||||
|
||||
Da nur getrennte Clients geweckt werden, muss die mobile PWA vor dem Test
|
||||
geschlossen oder die WebSocket-Verbindung unterbrochen sein.
|
||||
|
||||
### Offline-Timeout prüfen
|
||||
|
||||
`CMBNET_FCM_OFFLINE_WAKE_MINUTES` testweise auf `1` setzen, PWA schließen und
|
||||
nach ein bis zwei Minuten den Radar-Button im Desktop-Dispatcher verwenden.
|
||||
Bei aktiver automatischer Positionsübertragung sollte die Gruppen-View nach
|
||||
dem Wake eine neue Position senden. Der Service Worker zeigt nur dann eine
|
||||
Benachrichtigung, wenn kein PWA-Fenster erreichbar ist.
|
||||
|
||||
### FCM-Versand direkt prüfen
|
||||
|
||||
Bei aktiviertem Debug-Logging des WSGI-Servers erscheinen Warnungen, wenn
|
||||
`firebase-admin` fehlt, die Initialisierung scheitert oder FCM einen Batch
|
||||
ablehnt. Ungültige Tokens werden als `invalid` markiert und nicht mehr
|
||||
verwendet.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Ursache / Lösung |
|
||||
| --- | --- |
|
||||
| `fcm-sw-config.js` liefert `enabled: false` | `CMBNET_FCM_ENABLED` nicht gesetzt oder einer der Web-Werte/VAPID fehlt. |
|
||||
| Kein Token in `ws_push_tokens` | PWA nicht installiert, keine Benachrichtigungserlaubnis, kein HTTPS oder Client-Typ/Rolle passt nicht. |
|
||||
| `firebase-admin ist nicht installiert` im Log | `pip install -r requirements.txt` in der aktiven Umgebung ausführen. |
|
||||
| `FCM-Initialisierung fehlgeschlagen` | Service-Account-Datei fehlt, ist nicht lesbar oder gehört zu einem anderen Projekt. |
|
||||
| `SENDER_ID_MISMATCH` bzw. Token wird ungültig | Web-Konfiguration und Service-Account stammen aus verschiedenen Firebase-Projekten. |
|
||||
| Radar-Button meldet 0 Kandidaten | Der Client ist noch verbunden, hat kein Token oder wurde bereits innerhalb des Cooldowns geweckt. |
|
||||
| iOS erhält keine Push-Nachricht | PWA nicht installiert, iOS < 16.4 oder Benachrichtigungen nicht erlaubt. |
|
||||
| Benachrichtigung erscheint, aber keine Position | Kein PWA-Fenster aktiv oder Standort im Hintergrund nicht erlaubt; die letzte bekannte Position wird verwendet. |
|
||||
| Doppelte Wakes bei mehreren Workern | `CMBNET_FCM_WAKE_POLL_INTERVAL_SECONDS` und `CMBNET_WS_BUS_POLL_INTERVAL` prüfen; die Reservierung erfolgt über `last_wake_at`. |
|
||||
|
||||
## Sicherheit und Datenschutz
|
||||
|
||||
- Der Service-Account-Schlüssel bleibt auf dem Server und gehört nicht ins
|
||||
Repository, in Templates oder in Browser-JavaScript.
|
||||
- FCM-Tokens sind installationsbezogene Kennungen. Sie werden nicht geloggt
|
||||
und beim Abmelden über `DELETE /<tenant>/api/push/register` entfernt.
|
||||
- Das FCM-Signal enthält nur `type` und `reason`. Mandant, Rolle, Nachricht,
|
||||
Absender und Position werden nicht über Firebase übertragen.
|
||||
- Firebase ist ein externer Google-Dienst. Der Betrieb muss die daraus
|
||||
folgenden Datenschutz- und Verfügbarkeitsanforderungen bewerten.
|
||||
- Die PWA muss über HTTPS laufen; der Server sollte nur hinter dem
|
||||
Reverse-Proxy erreichbar sein.
|
||||
Reference in new issue
Block a user