Files
Sternsinger/CMBNet/README_CMBNet.md
T

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