248 lines
11 KiB
Markdown
248 lines
11 KiB
Markdown
# 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 `/<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:
|
|
|
|
```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 `<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:
|
|
|
|
```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. 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`](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 /<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:
|
|
|
|
```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 "<API-Zugriffstoken>"
|
|
```
|
|
|
|
## 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.
|