Files
Sternsinger/Architektur.txt
T
2026-10-23 00:05:06 +02:00

340 lines
25 KiB
Plaintext

Architekturskizze: CMBNet
Dieses Dokument beschreibt den grundsätzlichen Aufbau der Webanwendung CMBNet gemäß den Anforderungen. Es werden Architekturentscheidungen, Modulzusammenhänge, Schnittstellen, Datenmodell und Ablaufdiagramme erläutert, bevor mit der Implementierung begonnen wird.
1. Ziele und Rahmenbedingungen
Anforderung Entscheidung
Server Python 3 + Flask
Frontend Reines Vanilla-JavaScript, pico.css (https://picocss.com/), Leaflet (https://leafletjs.com/)
Realtime-Synchronisation WebSocket mit eigenem Protokoll und mandantenabhängigem Routing
Mandantenfähigkeit Tenant-ID in URL, Referenz auf Tenant in jeder Entität und Account
Zugriffsschutz Login mit Rollenmodell (Gast, Beobachter, Gruppe, Dispatcher, Administrator)
Verwaltung Separate Admin-Views für Accounts, Gruppen, Straßen
Historie & Logging State-Historie für Straßen/Gruppen, reversibel; transaktionales Logfile
Performance In-Memory-Caching für Gruppen (mit Invalidierung)
Kartenanwendung Leaflet mit Polylines aus str2pl.js, dynamische Marker für Gruppen
2. Projektstruktur
Der Code soll sauber strukturiert im Projektverzeichnis CMBNet/ abgelegt werden. Folgende Gliederung wird vorgeschlagen:
CMBNet/
├── app.py # Entrypoint, Flask-App-Initialisierung
├── config.py # Konfiguration (DB, Secret, Tenant-Defaults, Limits)
├── requirements.txt # Abhängigkeiten (Flask, flask-sock/gevent/eventlet o.ä., ...)
├── wsgi.py # WSGI für Deployment
├── instance/ # SQLite-DB, Laufzeitdateien (nicht versioniert)
├── logs/ # Lesbare Transaktions-Logs
├── data/ # Importvorlagen / Hilfsdaten (z. B. CSV)
├── migrations/ # Schema-Migrationen für SQLite
├── cmbnet/ # Hauptpaket
│ ├── __init__.py # create_app(), Blueprints, Erweiterungen
│ ├── extensions.py # DB, WebSocket-Broker-Instanz, etc.
│ ├── auth/ # Authentifizierung, Sessions, Token
│ ├── core/ # Konstanten, Protokolldefinition, Fehlerklassen
│ ├── db/ # DB-Verbindung, Schema, Hilfsfunktionen
│ ├── models/ # DAO/Repository für Entitäten
│ ├── services/ # Geschäftslogik (Streets, Groups, Accounts, History, Logging)
│ ├── api/ # AJAX/REST-Handler (Initialdaten + Aktionen)
│ ├── ws/ # WebSocket-Broker, Routing, Protokoll, Heartbeat
│ ├── views/ # View-Routen für Nicht-Admin
│ ├── admin/ # Admin-Routen & Handler
│ ├── utils/ # Helfer (CSV-Parsing, Geo, Zeit)
│ └── static/ # Statische Assets
│ ├── css/ # pico.css + eigene Styles
│ ├── js/ # Vanilla-JS
│ │ ├── lib/ # leaflet.js, ggf. pico.js (falls benötigt)
│ │ ├── core/ # ws_client.js, utils.js, state.js
│ │ ├── map/ # map.js, str2pl.js Integration
│ │ ├── views/ # dispatcher.js, gruppen.js, login.js, admin-*.js
│ │ └── str2pl.js # Extern bereitgestelltes Polyline-Fragment (wie gefordert)
│ └── img/ # Icons/Symbole
├── templates/ # Jinja2-Templates
│ ├── base.html
│ ├── login.html
│ ├── dispatcher.html
│ ├── dispatcher_mobil.html
│ ├── gruppen.html
│ ├── praesentation.html
│ ├── oeffentlich.html
│ └── admin/
│ ├── accounts.html
│ ├── gruppen.html
│ └── strassen.html
└── README.md
Begründung: Trennung von Routen (views/, admin/, api/), Geschäftslogik (services/), Datenzugriff (models/), Echtzeit (ws/) und Frontend (static/js/views/) sorgt für Übersichtlichkeit und Erweiterbarkeit.
3. Mandantenfähigkeit & Routing
- Tenant in URL: Alle relevanten Zugriffe laufen über /<tenant>/.... Der Tenant wird aus der URL extrahiert, validiert und im Request-Kontext (g.tenant_id) verfügbar gemacht.
- Accounts mandantengebunden: accounts.tenant_id ist Pflicht, Login prüft (tenant_id, name) eindeutig.
- Datenisolation: Alle Queries filtern konsequent nach tenant_id (Streets, Groups, Accounts, History, Messages).
- Blueprints: auth_bp, views_bp, admin_bp, api_bp, ws_bp mit url_prefix='/<tenant>' bzw. tenant-Middleware.
4. Datenmodell (SQLite3)
Folgende Tabellen werden vorgeschlagen (Schlüsselideen). Genauere Typen/Indizes werden bei Implementierung finalisiert.
Tabelle Zweck Wesentliche Felder
tenants Mandantenstamm id (PK), code (z. B. BV/RV/SV), name, created_at
accounts Nutzer id (PK), tenant_id (FK), name, password_hash, role (ENUM/Gast/Beobachter/Gruppe/Dispatcher/Administrator), created_at, updated_at
groups Gruppen id (PK), tenant_id (FK), aliasname, state (offen/unterwegs/online/pausierend/fertig), last_lat, last_lon, last_pos_at (DATETIME), account_id (FK -> accounts, 1:1 wie gefordert), created_at, updated_at
streets Straßen id (PK), tenant_id (FK), name, state (unbearbeitet/zugewiesen/erledigt), group_id (FK -> groups, NULL wenn unbearbeitet), hn_min, hn_max, bbox (TEXT/JSON: [ [nwLon,nwLat],[seLon,seLat] ] oder Array), created_at, updated_at
street_state_history Historie Straßen id (PK), tenant_id, street_id (FK), from_state, to_state, group_id (vorher/nachher Kontext), actor_account_id (FK), reason, created_at (DATETIME)
group_state_history Historie Gruppen id (PK), tenant_id, group_id (FK), from_state, to_state, last_lat, last_lon, last_pos_at, actor_account_id, created_at
ws_tokens Zugriffstokens für WS-Auth id (PK), tenant_id, account_id, token (zufällig), session_id, expires_at, used (bool), created_at
ws_messages_store Persistenz für >=1000 (Late Entry) id (PK), tenant_id, sender_id, receiver_id (nullable für Broadcast/Gruppe), code (INT), ts (DATETIME/UNIX), msg (TEXT/JSON), delivered_to (JSON/rel), created_at
transaction_log Lesbares Transaktionslog id (PK), tenant_id, ts (DATETIME), actor_account_id, action, entity_type, entity_id, details (TEXT)
Anmerkungen:
- bbox wird als JSON-String in SQLite abgelegt, beim Ausliefern an Frontend als JS-Array geparst.
- Historieeinträge werden bei jedem State-Wechsel erzeugt. Revert setzt State zurück und schreibt neuen History-Eintrag (inkl. Kontext) gemäß "durch Anklicken alten States wieder gültig".
- Transaktionen (CRUD an Accounts/Gruppen/Straßen) werden sowohl in transaction_log als auch lesbar in Logfile geschrieben (logs/cmbnet-YYYY-MM-DD.log).
5. Authentifizierung & Sessions
- Passwortprüfung: Nur Hashvergleich (siehe Accounts-Service).
- Weiterleitung: next-Parameter wird unterstützt. Ansonsten Rollenbasiert.
- Zugriffsschutz: Decorators login_required, role_required([roles...]), tenant_required für alle geschützten Routen.
- WS-Token: Nach Login/bei Initialload liefert AJAX-Endpoint /<tenant>/api/auth/ws-token ein zufälliges Token, das serverseitig kurzzeitig gespeichert (ws_tokens) und für WS-Auth benötigt wird.
6. WebSocket-Protokoll & Broker
6.1 Protokollformat
Jede Nachricht ist JSON mit folgendem Schema:
{
"sender_id": 123,
"receiver_id": 456, // optional, je nach Code/Broadcast
"code": 100,
"ts": 1729612345678, // UNIX ms oder ISO8601; Broker setzt/validiert
"msg": "{\"name\":\"Musterstraße\",\"state\":\"zugewiesen\",\"actor\":...}"
}
- code < 100: nur intern, wird nicht in UI angezeigt
- Zeitstempel wird serverseitig normalisiert
- msg ist Freitext oder JSON (abhängig von Code)
6.2 Broker-Architektur
Der Broker verwaltet Verbindungen pro Tenant und Account.
Komponenten:
- ws/broker.py: Connection-Pool (connections[tenant_id][account_id] = ws), Auth-Flow (Code 0 + Token), Heartbeat (Code 1/2), Broadcast/Unicast
- ws/router.py: Entscheidung Empfängerkreis je Nachrichtentyp
- ws/handlers.py: Verarbeitung eingehender Codes
- ws/protocol.py: Validierung, Serialisierung
6.3 Routing nach Nachrichtentypen
Code Auslöser Empfängerkreis Inhalt msg Persistenz
0 Client nach Connect Broker-intern (Auth) Token Nein
1 Server (zyklisch 1/min) Alle verbundenen Clients Ping/Markierung Nein
2 Client (Antwort auf 1) Nur Dispatcher-Views Pong/Antwort Nein
100 State-Wechsel Straße Alle Dispatcher, Gast, Beobachter + Gruppe, die mit Straße verknüpft ist (bei Zuweisung/Änderung) JSON {name, state, actor, street_id, group_id?} Nein (Echtzeit)
200 State-Wechsel Gruppe Alle Dispatcher, Beobachter + betroffene Gruppe JSON {group_id, state, actor} Nein
300 Positionswechsel Gruppe Verbundene Dispatcher, Beobachter + betroffene Gruppe JSON {group_id, lat, lon, ts, actor} Nein
1000 Dispatcher Alle Dispatcher, Beobachter, alle Gruppen (Broadcast) Freitext Ja (>=1000)
1100 Dispatcher Alle Dispatcher, Beobachter + spezielle Gruppe (Aliasname vorangestellt) Freitext mit Präfix Ja
2000 Gruppe Alle Dispatcher, Beobachter JSON {group_id, text} Ja
Heartbeatroutine: Server sendet code=1 jede Minute. Clients antworten code=2. code=2 wird ausschließlich an angeschlossene Dispatcher-Views weitergeleitet. Verbindungen ohne rechtzeitige Antwort können nach Timeout getrennt werden.
Late Entry: Bei Anmeldung am Broker werden nur für diesen Client berechtigte Nachrichten aus ws_messages_store mit ts >= now - 8h in chronologischer Reihenfolge zugestellt. Ältere Einträge werden gelöscht. Zuständigkeit für Löschung: Broker-Routine (z. B. bei Zustellung oder periodisch).
7. Backend-Module im Detail
7.1 models/ (DAO)
Abstraktionsschicht für CRUD. Jede Methode filtert nach tenant_id.
- streets.py: get_all(), get_by_id(), create(), update(), delete(), import_from_csv_rows()
- groups.py: primär über Service (In-Memory), aber DB-Zugriff hier
- accounts.py: get_by_name_and_tenant(), get_by_id(), create(), update_role(), delete(), set_password_hash()
- history.py: Historieneinträge lesen/schreiben
- messages.py: Persistenz für Code>=1000 + Cleanup
- log.py: Transaktionslog (DB + File)
7.2 services/ (Geschäftslogik)
- streets_service.py
- handle_initial_ajax(tenant_id, ...) -> JSON aller Straßenattribute inkl. State
- update_street(street_id, changes, actor) -> DB-Update, History-Eintrag, Logging, Broker-Notify (Code 100 je nach Statewechsel)
- groups_service.py (Kernstück)
- In-Memory-Cache: groups_cache[tenant_id][group_id] = {...}
- load_from_db(tenant_id): beim Start + bei Invalidierung
- invalidate(tenant_id): erzwingen Neuladen (z. B. Admin-Änderung)
- is_account_linked(account_id, group_id)
- get_accounts_for_group(group_id)
- get_streets_for_group(group_id)
- handle_initial_ajax(...)
- update_group(...), set_position(...), change_state(...) -> DB + Cache + History + Broker (200/300)
- accounts_service.py
- verify_password(account, password) (Hashvergleich)
- has_role(account, roles)
- issue_ws_token(account, session)
- history_service.py: Revert-Funktion (lädt alten Snapshot, setzt Entität zurück, schreibt neuen History-Eintrag)
7.3 api/ (AJAX)
Endpoints für Initialload und Aktionen:
Endpoint Methode Zweck
/<tenant>/api/init/streets GET Liste Straßen (inkl. State, group_id)
/<tenant>/api/init/groups GET Liste Gruppen (inkl. State, Position, last_pos_at)
/<tenant>/api/auth/ws-token GET/POST Token für WS-Auth erzeugen
/<tenant>/api/streets/<id>/state POST State-Wechsel Straße (Dispatcher/Gruppen-Kontext)
/<tenant>/api/groups/<id>/state POST State-Wechsel Gruppe
/<tenant>/api/groups/<id>/position POST Position setzen (Gruppen-View)
Antworten sind JSON. CSRF-Schutz gemäß Flask-Konzept (oder passende Maßnahme).
7.4 admin/
Nur für Rolle Administrator. Validierung serverseitig.
- accounts: Liste, Rolle ändern (AJAX), Passwort-Reset (Modal), Anlegen (Modal), Löschen (mit Rückfrage)
- gruppen: Liste, State ändern, Account verknüpfen/ändern, Position manuell/aus Historie zurücksetzen/löschen, Anlegen, Löschen, Historie-Anzeige + Revert
- strassen: Tabelle editierbar, Modal Edit, Modal Neu, Löschdialog, CSV-Import (Upload multipart/form-data, Delimiter ;, Spalten Name, Hausnummer minimal, Hausnummer maximal, Bounding Box). Import erzeugt Einträge mit State unbearbeitet, group_id = NULL. Jede Änderung triggert Transaktionslog + bei State-Wechsel Broker-Code 100.
CSV-Import: Parsing robust (Quotes/Encoding). bbox wird validiert und als JSON für Frontend normalisiert.
7.5 ws/ Ablauf Code 0 Auth
1. Client sendet {code:0, msg: token, sender_id: account_id}
2. Broker sucht Token in ws_tokens (tenant, account, nicht genutzt, nicht abgelaufen)
3. Bei Erfolg: markiert genutzt/erstellt Session-Mapping, führt Late-Entry durch, registriert Connection in Routing-Tabellen
4. Bei Misserfolg: schließt Verbindung
8. Frontend-Architektur
8.1 Templates
- base.html: Grundgerüst, pico.css, Leaflet CSS/JS, gemeinsame Skripte
- login.html: Formular Name/Passwort + Select Mandant (BV/RV/SV, Default RV)
- View-Templates binden view-spezifisches JS ein
8.2 JS-Module
Datei Aufgabe
core/ws_client.js WebSocket-Verbindung, Reconnect, Senden/Empfangen, Heartbeat-Handling (Code 1 -> Code 2)
core/utils.js Helper, Formatierung Zeit/Datum, LocalStorage
core/state.js Gemeinsamer State (streetsDict, groupsDict, token, tenant)
map/map.js Leaflet-Initialisierung, Bounds, Tiles (OSM/Luftbild), Marker/Polylines, Events
map/str2pl_integration.js Lädt str2pl.js, baut Strasse2Polylines, rendert Polylines nach State
views/dispatcher.js Dispatcher-View Logik (Accordion, Position, Code 1000/1100, Opacity/Weight, Timer)
views/gruppen.js Gruppen-View (State-Wechsel, Position setzen, Nachrichten)
views/praesentation.js / oeffentlich.js Nur Darstellung + Suche, keine Modifikation
views/dispatcher_mobil.js Mobiloptimiert, selektive Darstellung
views/admin_*.js Admin-Interaktionen (Modals, AJAX, CSV-Upload)
views/login.js Client-seitige Validierung falls gewünscht
8.3 str2pl.js
Wird als separates JS-Fragment unter static/js/str2pl.js bereitgestellt. Erwartetes Format (konzeptionell):
// Beispielhaft
window.STRASSE2POLYLINES = {
"Musterstraße": [
[[7.1234, 50.1234],[7.1235,50.1235]],
[[7.1235,50.1235],[7.1236,50.1236]]
],
// ...
};
map/str2pl_integration.js iteriert über Einträge, erzeugt L.polyline pro Segment, speichert Referenz in Strasse2PolylinesMap[streetName] = [polyline1,...] für spätere Farbupdates bei Code 100.
8.4 Initialisierungsreihenfolge (Dispatcher-Prototyp)
8.5 Kartenlogik
- Bounds: Union aller bbox von Straßen -> L.latLngBounds
- LocalStorage: cmbnet:<tenant>:map speichert {center:[lat,lng], zoom, opacity, weight}
- Tiles: OSM + optional Luftbild (Layer-Control)
- Polylines: Farbe nach State (unbearbeitet blau, zugewiesen rot, erledigt grün), opacity, weight konfigurierbar
- Klick Polyline: Modal State-Wechsel je Übergang (wie 156-161), sendet Code 100 via API/WS-Pfad
- Gruppen-Marker: individuelle Farben, Position aus last_lat/lon oder Browser-Geolocation bei unbekannt
- Code 100: Aktualisiert Farbe aller Segmente betroffener Straße
- Code 200/300: Aktualisiert Accordion + Marker
8.6 Kontrollansicht (Dispatcher)
- Header: Wochentag/Datum (klein), Uhrzeit (groß), sekundengenau aktualisiert
- Dropdown: Kartenhintergrund
- Lautsprecher: Modal Freitext -> Code 1000
- Zentral: Accordion pro Gruppe, Kreis Farbe, State, Position-Button, Progressbar (Zeitdiff), Fadenkreuz-Modus (Klick setzt Position -> Code 300), Nachrichtenfeld (Code 2000), Chat-Dialog für >=1000
- Footer: Opacity-Slider (0-1 step 0.05), Weight-Slider (1-100), Fit-Bounds-Button, Exit -> Logout
Progressbar-Berechnung: diff = now - last_pos_at. 100% < 60s, 0% >= 3600s, linear dazwischen. >3600s -> Button inaktiv.
Fadenkreuz-Modus: Cursor-Wechsel, ESC oder erneuter Button-Abbruch, Klick -> API set_position + WS Code 300.
8.7 Views nach Anforderung
View Zielgerät Darstellung Interaktion
Login-View Alle Login-Formular Authentifizierung, Redirect
Dispatcher-View Desktop Karte 2/3 + Kontrollansicht 1/3 Voll (State-Wechsel, Nachrichten, Position)
Dispatcher-Mobil-View Smartphone Optimiert, selektiv Ähnlich reduziert
Gruppen-View Smartphone Für Gruppenaccount Nur eigene Gruppe, State-Wechsel, Position, Nachrichten
Präsentations-View Alle Alle Infos Nur Suche, keine Modifikation
Öffentlicher-View Alle Wie Präsentation, ohne Gruppen Nur Suche
9. Wichtige Abläufe (Diagramme)
9.1 State-Wechsel Straße (Dispatcher klickt Polyline)
9.2 Gruppenposition setzen (Gruppen-View / Fadenkreuz)
9.3 Admin CSV-Import
10. Logging, Historie & Revert
10.1 Transaktionslog
Jede schreibende Transaktion muss sowohl in einer maschinenlesbaren Datenbanktabelle, als auch in einem menschenlesbaren Logfile protokolliert werden.
Ziel Umsetzung
Datenbank Tabelle transaction_log mit ts, tenant_id, actor_account_id, action, entity_type, entity_id und details (als JSON-String für eine strukturierte Auswertung).
Logfile Tagesbasiert unter logs/cmbnet-YYYY-MM-DD.log. Jedes Logformat soll folgende Felder beinhalten: Timestamp, Tenant, Actor (Account-ID + Name), Aktion, Entitätstyp, Entitäts-ID, Details.
Auslöser CRUD für Accounts, Gruppen und Straßen, CSV-Import, State-Wechsel, Positionsänderungen, Rollenänderungen, Passwort-Resets sowie das Setzen/Löschen einer Gruppenposition.
Beispielhafter Logeintrag:
2026-10-22 14:32:18.542 [TENANT:RV] [ACTOR:42(DispatcherMax)] ACTION:street.state_change ENTITY:street:123 DETAILS:{"from":"unbearbeitet","to":"zugewiesen","group_id":5}
10.2 State-Historie
Für Straßen und Gruppen wird eine lückenlose Historie aller relevanten Zustandsänderungen geführt.
Tabelle Zweck Gespeicherter Snapshot
street_state_history Historie für Straßen from_state, to_state, group_id (Kontext zum Zeitpunkt des Wechsels), actor_account_id, reason, created_at
group_state_history Historie für Gruppen from_state, to_state, last_lat, last_lon, last_pos_at (vollständiger Positionssnapshot), actor_account_id, created_at
- Erzeugung: Bei jedem validierten State-Wechsel wird automatisch ein neuer Historieneintrag erzeugt, bevor oder im selben Datenbank-Commit wie das Update der Entität.
- Anzeige: In den jeweiligen Verwaltungsseiten (Gruppenverwaltung, Straßenverwaltung) ist eine Historieansicht pro Eintrag aufrufbar. Diese wird chronologisch absteigend dargestellt.
- Transparenz: Jeder Eintrag zeigt Zeitpunkt, auslösenden Account, vorherigen und neuen Zustand sowie den zum Wechsel gehörenden Kontext (z. B. verknüpfte Gruppe oder Positionssnapshot).
10.3 Revert von historischen Zuständen
Über das Anklicken eines historischen Eintrages soll der Zustand der Entität wiederhergestellt werden können. Dies ist bewusst als neuer Übergang, nicht als bloßes Überschreiben ohne Nachverfolgung, umgesetzt.
Regeln für den Revert:
- Nur Administratoren: Der Revert ist ausschließlich für Accounts mit der Rolle Administrator freigegeben und wird serverseitig validiert.
- Neuer History-Eintrag: Durch den Revert wird kein Eintrag entfernt. Es wird stattdessen ein neuer Eintrag in der Historie geschrieben, der den Übergang vom aktuellen Zustand zum wiederhergestellten Zustand abbildet.
- Positionswiederherstellung: Für Gruppen wird bei einem Revert eines Positions-Snapshots sowohl last_lat, last_lon, last_pos_at wiederhergestellt, als auch eine Code-300-Nachricht über den Broker ausgelöst, um Marker und UI aller berechtigter Clients zu synchronisieren.
- Gruppenverknüpfung: Bei Straßen wird group_id anhand des historischen Kontextes wiederhergestellt. Ist der wiederherzustellende Zustand unbearbeitet, wird group_id auf NULL gesetzt.
- Konsistenz: Nach einem Revert wird der In-Memory-Cache der Gruppen invalidiert (sofern betroffen) und das Transaktionslog entsprechend aktualisiert.
11. Sicherheit
Da die Anwendung Zugangsschutz, Mandantenfähigkeit und Echtzeitkommunikation kombiniert, werden folgende Maßnahmen konsequent umgesetzt.
Bereich Maßnahme Begründung
Authentifizierung Nur Passwort-Hash-Vergleich über einen etablierten Hash-Algorithmus (z. B. werkzeug.security mit generate_password_hash/check_password_hash) Niemals Klartextpasswörter speichern
Sessions Flask-Sessions mit HttpOnly, Secure (in Produktion), SameSite=Lax/Strict Schutz vor Session-Hijacking und CSRF-ähnlichen Angriffen
Autorisierung Serverseitige Decorators (login_required, role_required, tenant_required) für alle geschützten Routen und Aktionen Client-seitige Prüfungen sind niemals ausreichend
Mandantenisolation Filterung sämtlicher DB-Queries nach tenant_id, Prüfung beim Routing und bei jedem Broker-Zugriff Verhindert Cross-Tenant-Zugriff
WebSocket-Auth Einmalig nutzbarer, kurzlebiger Token (Code 0), Speicherung in ws_tokens mit used-Flag und optionalem expires_at Verhindert Missbrauch von Tokens
CSRF CSRF-Schutz für alle POST/PUT/PATCH/DELETE Requests (AJAX und Formulare) Schutz vor Cross-Site-Request-Forgery
Input-Validierung Serverseitige Validierung für alle Formulare, AJAX-Payloads und CSV-Import Robustheit und Integrität der Daten
Datei-Upload Nur .csv zulassen, Dateigröße begrenzen, Delimiter explizit ; erzwingen, Inhalte parsen und validieren Verhindert unerwartete Dateien und fehlerhafte Importe
SQL-Injection Ausschließlich parametrisierte Queries über den DB-Layer Vermeidung von SQL-Injection
XSS Jinja2-Autoescaping aktiv, keine Einbettung ungeprüften HTMLs im Frontend Schutz vor Cross-Site-Scripting
Logging sensibler Daten Keine Passwörter, Tokens oder sensiblen Rohdaten in Logs Vermeidung von Credential-Leaks
12. Konfiguration, Abhängigkeiten & Start
12.1 Abhängigkeiten (requirements.txt)
Folgende Pakete werden für den ersten Entwicklungsstand vorgeschlagen:
Flask>=3.0.0
Werkzeug>=3.0.0
flask-sock>=0.7.0
simple-websocket>=1.0.0
python-dateutil>=2.9.0
Hinweis: Je nach Deployment kann gevent oder eventlet für produktivere WebSocket-Verbindungen ergänzt werden. Für den Entwicklungsserver ist flask-sock in Kombination mit dem Flask-Dev-Server ausreichend.
12.2 Konfiguration (config.py)
Zentrale Konfigurationspunkte:
Variable Zweck Default (Dev)
SECRET_KEY Session-Verschlüsselung Aus Umgebungsvariable laden
DATABASE_PATH Pfad zur SQLite-DB instance/cmbnet.sqlite3
TENANTS Erlaubte Mandanten ["BV", "RV", "SV"]
DEFAULT_TENANT Vorbelegung Login "RV"
WS_HEARTBEAT_INTERVAL Intervall für Code 1 60 Sekunden
WS_HEARTBEAT_TIMEOUT Timeout für Code 2 Antwort 15 Sekunden
LATE_ENTRY_MAX_AGE_HOURS Max. Alter für gespeicherte Nachrichten 8 Stunden
LOG_DIR Verzeichnis für Transaktionslogs logs/
MAX_CSV_SIZE_BYTES Upload-Limit z. B. 5_000_000
12.3 Initialisierung & Start des Entwicklungsservers
Vor dem ersten Start müssen Verzeichnisse angelegt und das Datenbankschema initialisiert werden.
# Ins Projektverzeichnis wechseln
cd CMBNet
# Virtuelles Environment erstellen und aktivieren
python3 -m venv .venv
source .venv/bin/activate # macOS/Linux
# .\.venv\Scripts\activate # Windows
# Abhängigkeiten installieren
pip install -r requirements.txt
# Benötigte Verzeichnisse anlegen
mkdir -p instance logs data migrations
# Datenbank initialisieren (über CLI-Command der App)
flask --app app init-db
# Entwicklungswebserver starten
flask --app app run --debug --host 127.0.0.1 --port 5000
Anschließend ist die Anwendung unter http://127.0.0.1:5000 erreichbar. Der Zugriff erfolgt mandantenspezifisch über http://127.0.0.1:5000/<tenant>/login (z. B. /RV/login).
Hinweis: app.py bzw. das create_app() in cmbnet/__init__.py muss den CLI-Befehl init-db registrieren, um das Schema aus migrations/ bzw. cmbnet/db/schema.sql anzuwenden.
13. Implementierungsreihenfolge
Um Komplexität beherrschbar zu halten, wird eine schrittweise Umsetzung empfohlen:
Phase Fokus Ziel
Phase 0: Grundgerüst Projektstruktur, Config, DB-Verbindung, Blueprints Laufende Flask-App ohne Businesslogik
Phase 1: Datenmodell & Auth Schema für alle Tabellen, Accounts-Service, Login-View, Rollen-/Tenant-Decorators Funktionsfähiger Login mit Mandantenwahl
Phase 2: Entitätenbasis Models/Services für Streets, Groups, Accounts. In-Memory-Cache für Gruppen inkl. Invalidierung Datenzugriffsschicht steht
Phase 3: WebSocket-Broker Protokoll, Routing, Auth (Code 0), Heartbeat (1/2), Late-Entry, Persistenz für >=1000 Realtime-Grundgerüst funktionsfähig
Phase 4: Admin-Views Account-, Gruppen- und Straßenverwaltung, CSV-Import, Historie + Revert, Transactionlog Vollständige Administration
Phase 5: Karten-Views Login-Flow finalisieren, Dispatcher-Prototyp (Karte + Accordion), str2pl.js Integration, Polylines/Marker, Code 100/200/300 Erster funktionsfähiger Kartenprototyp
Phase 6: Weitere Views Dispatcher-Mobil, Gruppen-View, Präsentations-View, Öffentlicher-View Abdeckung aller geforderter Views
Phase 7: Feintuning Logging, Cleanup alter Nachrichten, LocalStorage, Responsiveness, Fehlerbehandlung Stabilisierung für den Entwicklungsstand
14. Fazit
Der hier beschriebene Aufbau trennt klar zwischen Datenzugriff, Geschäftslogik, Echtzeitkommunikation und Frontend. Durch das mandantenfähige Datenmodell, das eigene WebSocket-Protokoll mit Routing nach Account/Rolle/Gruppenverknüpfung, den In-Memory-Cache für Gruppen, die reversible State-Historie und das ausführliche Transaktionslogging wird bereits im Grundgerüst die geforderte Erweiterbarkeit für die später noch hinzuzufügende Applikationslogik geschaffen.