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