Files
Sternsinger/CMBNet/README_CMBNet.md
T

11 KiB

CMBNet

Webanwendung für die Verwaltung von Straßen und Gruppen mit Kartendarstellung.

Setup

cd CMBNet
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdir -p instance logs data migrations
flask --app cmbnet init-db
flask --app cmbnet run --debug --host 127.0.0.1 --port 5000

Zugriff

Öffne http://127.0.0.1:5000 und wähle einen Mandanten (BV, RV, SV).

Administrator-Dashboard

Das Dashboard unter /<tenant>/admin/dashboard bietet zusätzlich:

  • Datenbank-Backup herunterladen: erzeugt über die SQLite-Backup-API einen konsistenten Snapshot der laufenden Datenbank (.sqlite3).
  • Backup wiederherstellen: lädt eine solche Datei hoch, prüft Integrität und Grundschema und ersetzt anschließend die Live-Datenbank. Währenddessen sollten keine anderen Benutzer aktiv arbeiten.
  • Konfiguration anzeigen/herunterladen: listet alle Konfigurationsparameter als Key: Value und exportiert sie als Textdatei. Geheimnisse wie SECRET_KEY und FCM_SERVICE_ACCOUNT_JSON werden maskiert.

Die maximale Upload-Größe wird über CMBNET_BACKUP_MAX_UPLOAD_MB (Default 256) festgelegt.

Dispatcher: Gruppenposition teilen

Der Nadel-Button (📍) einer Gruppe zentriert die Karte auf die letzte Gruppenposition. Die Zoomstufe ist über CMBNET_GROUP_POSITION_ZOOM (Default 18) konfigurierbar. Zusätzlich öffnet der Button ein Karten-Popup mit einem QR-Code. Der QR-Code verweist auf einen WhatsApp-Deep-Link, der die Position als Google-Maps-Link teilt.

Mandantenspezifische Straßen-Polylines

Die Karten-Views laden static/js/str2pl-<tenant>.js, sofern diese Datei existiert (z. B. static/js/str2pl-RV.js). Andernfalls wird die gemeinsame static/js/str2pl.js verwendet. Eine mandantenspezifische Datei ersetzt die gemeinsame Datei vollständig und muss dieselbe Struktur besitzen (window.STRASSE2POLYLINES = { ... }).

Im View „Straßenverwaltung“ kann ein Administrator die Datei über den Button „Polyline-Datei erzeugen“ neu schreiben lassen. Dabei werden immer alle Straßen des Mandanten aus der Datenbank berücksichtigt; die gemeinsame str2pl.js dient als Geometriequelle. Segmente außerhalb der jeweiligen Bounding Box werden verworfen, aneinanderhängende Segmente mit identischen Endpunkten werden zusammengefasst. Eine vorhandene mandantenspezifische Datei wird überschrieben.

Zusatz und geteilte Straßen

Jede Straße besitzt neben dem Namen einen optionalen Zusatz. Die Polyline-Datei verwendet bei gesetztem Zusatz den Key <Name> <Zusatz> (z. B. Aggerstraße Nord). Fehlt dieser Key, wird automatisch der Key ohne Zusatz verwendet. Bei der Suche im Dispatcher wird der Zusatz ignoriert; die Karte zoomt auf die gemeinsame Bounding Box aller Straßen mit demselben Namen.

Über den Button „Schneiden“ kann eine Straße an einer Hausnummer in zwei Abschnitte geteilt werden. Beide Abschnitte enthalten die Trennnummer, erhalten neu berechnete Bounding Boxes und bekommen je nach räumlicher Lage einen Zusatz aus Nord, Süd, Ost oder West.

Straßen- und Hausnummernimport

Der Import in der Straßenverwaltung erwartet eine CSV-Datei mit dem Trenner ; und den Spalten #Straßenname;Hausnummer;Longitude;Latitude. Aus den Einträgen werden die Straßen gruppiert und jeweils minimale/maximale Hausnummer sowie die Bounding Box berechnet. Der Import ersetzt die Straßen- und Hausnummerndaten des Mandanten vollständig; neue Straßen starten mit dem Status unbearbeitet und leerem Zusatz.

Betrieb hinter einem Reverse-Proxy (URI-Prefix)

Die Anwendung kann unter einem beliebigen Pfad ausgeliefert werden, z. B. https://example.com/cmbnet/. Dazu muss der Proxy den öffentlichen Prefix im Header X-Forwarded-Prefix setzen:

example.com {
    redir /cmbnet /cmbnet/ 308

    handle_path /cmbnet/* {
        reverse_proxy 127.0.0.1:5000 {
            header_up X-Forwarded-Prefix /cmbnet
        }
    }
}

Die Middleware in cmbnet/__init__.py setzt daraus SCRIPT_NAME, sodass url_for alle Links, Formularziele und statischen Dateien mit Prefix erzeugt. Der Prefix wird außerdem als CMBNET_BASE_URL an JavaScript übergeben; AJAX- und WebSocket-Aufrufe bilden ihre URLs damit korrekt. Eine vollständige Beispielkonfiguration (auch für Proxys, die den Prefix nicht entfernen) steht in Caddyfile.example.

Wichtig: Der Flask-Port sollte nur für den Reverse-Proxy erreichbar sein, damit Clients den Header nicht selbst setzen können.

WebSocket-Synchronisierung

Jede Webview erzeugt beim Laden einmalig eine Client-ID. Sie wird bewusst nicht in sessionStorage gespeichert: Ein Seiten-Reload erzeugt eine neue Client-ID und damit eine neue Broker-Verbindung. Nicht zustellbare Nachrichten mit Code >= 100 werden beim Broker pro (Mandant, Client-ID) gepuffert und bei der nächsten WebSocket-Verbindung mit derselben Client-ID ausgeliefert. Mehrere Clients desselben Accounts werden getrennt verwaltet und alle beliefert.

Die Zeitfenster lassen sich über Umgebungsvariablen konfigurieren:

  • CMBNET_WS_QUEUE_MAX_AGE_MINUTES (Default 15): Maximales Alter einer Client-Queue. Ältere Queues werden verworfen; beim nächsten Reconnect mit derselben Client-ID wird stattdessen eine Code-99-Nachricht mit Hinweis auf die zu lange Unterbrechung zugestellt.
  • CMBNET_WS_CLIENT_RETENTION_MINUTES (Default 60): Wie lange eine nicht mehr verbundene Webview samt Queue registriert bleibt, bevor der Broker sie endgültig aufräumt. Clients mit gültigem FCM-Token bleiben länger erhalten.
  • CMBNET_WS_CLIENT_OFFLINE_TIMEOUT_SECONDS (Default 180): Zeit ohne Lebenszeichen (Pong oder beliebige eingehende WebSocket-Nachricht), nach der der Server eine halb offene Verbindung schließt und den Client als getrennt markiert. Erst dadurch werden schlafende Mobilgeräte zuverlässig als „offline“ erkannt.
  • CMBNET_WS_GROUP_ONLINE_TIMEOUT_SECONDS (Default 120): Zeit ohne Code-2- Lebenszeichen, nach der eine Gruppe von online auf unterwegs wechselt.
  • CMBNET_WS_DEBUG_MESSAGES (Default 1): schreibt jede beim Broker eingehende Nachricht inklusive Absender, Client-ID, Code und ermitteltem Empfängerkreis nach logs/cmbnet-ws-YYYY-MM-DD.log. Mit 0 lässt sich die Ausgabe abschalten.
  • CMBNET_WS_BUS_POLL_INTERVAL (Default 0.5): Intervall in Sekunden, in dem jeder Worker die gemeinsame Queue für seine lokal verbundenen Clients prüft.
  • CMBNET_WS_EPHEMERAL_TTL_SECONDS (Default 30): Lebensdauer kurzlebiger Code-2-Zustellaufträge.
  • CMBNET_WS_WORKER_ID: optionale feste Worker-ID; muss je Worker-Prozess eindeutig sein. Standardmäßig wird <hostname>:<pid> verwendet.

Die Client-Queues und Sequenznummern liegen in der gemeinsamen SQLite-Datenbank (ws_clients, ws_client_queue). Dadurch überstehen sie einen Worker-Neustart und einen Reconnect auf einem anderen WSGI-Worker. Jeder Worker betreibt eine eigene Zustellschleife und liefert nur an seine lokal verbundenen Clients aus. Die Latenz für workerübergreifende Nachrichten ergibt sich aus CMBNET_WS_BUS_POLL_INTERVAL (Default 0.5 Sekunden). Der mobile Client puffert zusätzlich ausgehende fachliche Nachrichten kurzzeitig im Speicher und sendet sie nach erfolgreicher Authentifizierung automatisch nach.

Für den Betrieb mit mehreren Workern muss Gunicorn ohne preload_app laufen, damit Heartbeat und Zustellschleife in jedem Worker-Prozess starten:

gunicorn --worker-class gevent --workers 4 --bind 127.0.0.1:5000 wsgi:app

SQLite läuft dabei im WAL-Modus mit einem busy_timeout. Bei sehr vielen Clients oder hoher Schreiblast sollte statt SQLite ein Redis- oder PostgreSQL-Bus verwendet werden.

Eine ausführliche Beschreibung des Protokolls, der Brokerlogik, der Nebenläufigkeit und der aktuellen Abweichungen steht in ../doc/broker.md.

FCM-Aufwachsignale für mobile PWA-Clients

Mobile Gruppen- und Dispatcher-Views können über Firebase Cloud Messaging (FCM) aus dem Hintergrund geweckt werden. FCM transportiert nur ein Signal; Nachrichten und Positionen bleiben in der WebSocket-Kommunikation bzw. in der Broker-Queue. Die Signale werden bei gequeueten Nachrichten, nach einem konfigurierbaren Offline-Timeout und über den Radar-Button im Desktop- und mobilen Dispatcher ausgelöst. Nachrichten und der manuelle Radar-Button wecken auch Clients, die der Broker noch als verbunden führt; auf iOS ist der Verbindungsstatus häufig veraltet. Mit CMBNET_FCM_WAKE_CONNECTED_CLIENTS=0 lässt sich dieses zusätzliche Wecken abschalten.

Die Architektur, Trigger, Grenzen auf Android/iOS und alle Konfigurationsvariablen stehen in docs/FCM_ARCHITEKTUR.md. Der vollständige Protokollablauf inklusive Funktionsnamen sowie die Anforderungen an Reverse Proxy und CORS sind in docs/FCM_PROTOKOLL.md beschrieben. Die praktische Einrichtung von Firebase-Projekt, Web-App, VAPID-Schlüssel, Service-Account und PWA-Installation beschreibt docs/FCM_HOWTO.md.

Externe Gruppenpositions-API

Externe Systeme können die Position einer Gruppe per HTTP-POST melden:

POST /<tenant>/api/groups/position
Content-Type: application/json

{
  "lat": 50.701243,
  "lon": 7.153290,
  "timestamp": "2026-11-04T12:00:00Z",
  "token": "<API-Zugriffstoken>",
  "aliasname": "Gruppe 1"
}

Der Zeitstempel kann als ISO-8601-String oder als Unix-Zeit in Sekunden bzw. Millisekunden angegeben werden; Zeitangaben ohne Zeitzone werden als UTC interpretiert. Ist er älter als der in der Datenbank gespeicherte last_pos_at, wird weder die Datenbank noch der Broker aktualisiert. Eine erfolgreiche Aktualisierung wird als Code-300-Nachricht an Dispatcher, Beobachter und die betroffene Gruppe verteilt.

Die Zugriffstoken sind mandantenweit gültig und werden im Admin-Dashboard unter API-Zugriffstoken angezeigt. Dort kann jeder Token einzeln gelöscht und ein neuer zufälliger Token erzeugt werden. Ohne einen gültigen Token wird der Request mit HTTP 401 abgewiesen.

Zum Testen des Endpunkts dient scripts/test_group_position_api.py. Es liest Koordinaten aus ../data/rv-hnr.csv, verwendet standardmäßig den ersten Token und die erste Gruppe des Mandanten RV und prüft Aktualisierung, ältere Zeitstempel und ungültige Tokens:

python scripts/test_group_position_api.py

Alternativ lassen sich Token und Gruppe explizit angeben:

python scripts/test_group_position_api.py \
    --base-url http://127.0.0.1:5000 \
    --tenant RV \
    --alias "Gruppe 1" \
    --token "<API-Zugriffstoken>"

Erste Einrichtung

Nach der Initialisierung der Datenbank müssen noch Mandanten und ein Admin-Account angelegt werden.

sqlite3 instance/cmbnet.sqlite3
INSERT INTO tenants (code, name) VALUES ('BV', 'Bezirk BV'), ('RV', 'Bezirk RV'), ('SV', 'Bezirk SV');
INSERT INTO accounts (tenant_id, name, password_hash, role) VALUES (2, 'admin', '...', 'Administrator');

Für den Passwort-Hash kann python3 -c "from werkzeug.security import generate_password_hash; print(generate_password_hash('admin'))" verwendet werden.