# CMBNet Webanwendung für die Verwaltung von Straßen und Gruppen mit Kartendarstellung. ## Setup ```bash 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 `//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-.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 ` ` (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: ```caddyfile 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 `:` 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: ```bash 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`](../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. Die Architektur, Trigger, Grenzen auf Android/iOS und alle Konfigurationsvariablen stehen in [`docs/FCM_ARCHITEKTUR.md`](docs/FCM_ARCHITEKTUR.md). Die praktische Einrichtung von Firebase-Projekt, Web-App, VAPID-Schlüssel, Service-Account und PWA-Installation beschreibt [`docs/FCM_HOWTO.md`](docs/FCM_HOWTO.md). ## Externe Gruppenpositions-API Externe Systeme können die Position einer Gruppe per HTTP-POST melden: ```http POST //api/groups/position Content-Type: application/json { "lat": 50.701243, "lon": 7.153290, "timestamp": "2026-11-04T12:00:00Z", "token": "", "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: ```bash python scripts/test_group_position_api.py ``` Alternativ lassen sich Token und Gruppe explizit angeben: ```bash python scripts/test_group_position_api.py \ --base-url http://127.0.0.1:5000 \ --tenant RV \ --alias "Gruppe 1" \ --token "" ``` ## Erste Einrichtung Nach der Initialisierung der Datenbank müssen noch Mandanten und ein Admin-Account angelegt werden. ```bash 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.