# 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). ## 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. - `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). ## 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.