From 683ef956fca2b5cf4df47b5c4ed2690f7a0c3a69 Mon Sep 17 00:00:00 2001 From: Stefan Mogeritsch Date: Tue, 31 Mar 2026 13:02:04 +0200 Subject: [PATCH] docs(adr): add ADR-0020 for LAN communication and data isolation architecture - Documented decision for Peer-to-Peer (P2P) model with mDNS discovery, WebSocket transport, and shared security keys. - Addressed data isolation with namespacing by turnierId. - Updated roadmap to reflect progress in Phase 6: Vernetzung & Inter-App Kommunikation. Signed-off-by: Stefan Mogeritsch --- .../Frontend_Komponenten_Roadmap.md | 17 ++++- docs/01_Architecture/MASTER_ROADMAP.md | 16 ++++- .../0020-lan-communication-isolation-de.md | 71 +++++++++++++++++++ docs/01_Architecture/adr/README.md | 1 + 4 files changed, 100 insertions(+), 5 deletions(-) create mode 100644 docs/01_Architecture/adr/0020-lan-communication-isolation-de.md diff --git a/docs/01_Architecture/Frontend_Komponenten_Roadmap.md b/docs/01_Architecture/Frontend_Komponenten_Roadmap.md index 6f8e12ab..1b5d8ecc 100644 --- a/docs/01_Architecture/Frontend_Komponenten_Roadmap.md +++ b/docs/01_Architecture/Frontend_Komponenten_Roadmap.md @@ -23,7 +23,7 @@ Bevor wir neue Features bauen, räumen wir die bestehenden Entwürfe auf, um Red * [x] Referenzen in `ping-feature` korrigiert. * [x] Referenzen in `profile-feature` korrigiert. -## Phase 2: Daten-Visualisierungs-Komponenten (Das Herzstück) 🔵 [IN ARBEIT] +## Phase 2: Daten-Visualisierungs-Komponenten (Das Herzstück) ✅ [ABGESCHLOSSEN] Turniermanagement bedeutet Arbeit mit Listen. Wir benötigen mächtige, aber kompakte Anzeige-Komponenten. @@ -57,13 +57,24 @@ Hier bringen wir alles zusammen, bevor das finale Routing implementiert wird. --- -## Phase 5: Routing & Screen-Komposition 🔵 [IN ARBEIT] +## Phase 5: Routing & Screen-Komposition ✅ [ABGESCHLOSSEN] In dieser Phase werden die Komponenten zu echten Features zusammengebaut. * [x] **Reiter-Verwaltung (MVP):** Erster Screen mit `MsMasterDetailLayout`, `MsDataTable` und Editor. * [x] **Pferde-Verwaltung (MVP):** Analog zur Reiter-Verwaltung (Fertiggestellt). -* [ ] **Navigation & Routing:** Integration der neuen Screens in die Hauptnavigation. +* [x] **Layout-Refactoring:** Umstellung auf Event-First Workflow (Login-Skip). + +--- + +## Phase 6: Vernetzung & Inter-App Kommunikation 🔵 [IN ARBEIT] + +Nachdem die UI-Bausteine stehen, vernetzen wir die Desktop-Apps im LAN. + +* [x] **Konzept & ADR:** ADR-0020 (LAN-Communication & Isolation) erstellt. +* [ ] **Discovery:** mDNS Integration für automatische Gerätefindung. +* [ ] **Sync:** WebSocket-basierte Echtzeit-Synchronisation zwischen Meldestelle und Richter. +* [ ] **Chat:** Implementierung des veranstaltungsweiten Chat-Fensters. --- diff --git a/docs/01_Architecture/MASTER_ROADMAP.md b/docs/01_Architecture/MASTER_ROADMAP.md index 2e3bd018..9f637857 100644 --- a/docs/01_Architecture/MASTER_ROADMAP.md +++ b/docs/01_Architecture/MASTER_ROADMAP.md @@ -186,7 +186,18 @@ und über definierte Schnittstellen kommunizieren. ## 4. Geplante Phasen -### PHASE 7: Series-Context & Erweiterungen 🔵 PHASE 2+ +### PHASE 7: Desktop-Vernetzung & Event-First Workflow 🔵 IN ARBEIT + +*Ziel: LAN-Kommunikation zwischen Apps und Fokus auf Veranstaltungs-Verwaltung.* + +* [x] **Konzept:** LAN-Discovery (mDNS) und Echtzeit-Sync (WebSockets) entworfen. +* [x] **ADR:** ADR-0020 (Lokale Netzwerk-Kommunikation) erstellt. +* [ ] **Discovery:** Implementierung des mDNS-Service für die Geräte-Suche. +* [ ] **Transport:** Aufbau der WebSocket-Infrastruktur für P2P-Sync. +* [ ] **Event-First:** Umstellung des App-Startpunkts auf die Veranstaltungs-Liste (Login-Skip). +* [ ] **Wizard:** Implementierung des `VeranstaltungNeuWizard` zur Neuanlage. + +### PHASE 8: Series-Context & Erweiterungen 🔵 PHASE 2+ *Ziel: Cups, Serien und Meisterschaften mit konfigurierbaren Reglements.* @@ -213,7 +224,8 @@ und über definierte Schnittstellen kommunizieren. | 11 | Masterdata: Importer-Einbettung als Worker | ✅ | ADR-0017 | | 12 | Masterdata: Rule-Versionierung (Regulation-as-Data) | ✅ | ADR-0018 | | 13 | Masterdata: API-Schichten (REST vs. Ingestion) | ✅ | ADR-0019 | -| 14 | Masterdata: Observability & Operations | ✅ | masterdata-ops.md, CHANGELOG | +| 14 | Lokale Netzwerk-Kommunikation und Daten-Isolierung | ✅ | ADR-0020 | +| 15 | Masterdata: Observability & Operations | ✅ | masterdata-ops.md, CHANGELOG | --- diff --git a/docs/01_Architecture/adr/0020-lan-communication-isolation-de.md b/docs/01_Architecture/adr/0020-lan-communication-isolation-de.md new file mode 100644 index 00000000..b36177ba --- /dev/null +++ b/docs/01_Architecture/adr/0020-lan-communication-isolation-de.md @@ -0,0 +1,71 @@ +--- +type: ADR +status: ACCEPTED +owner: Lead Architect +--- + +# ADR-0020: Lokale Netzwerk-Kommunikation und Daten-Isolierung + +## Status + +Akzeptiert (März 2026) + +## Kontext + +Die Desktop-Anwendung ("Meldestelle-Biest") muss in einer lokalen Netzwerkumgebung (LAN) auf Reitturnieren +funktionieren, oft ohne zuverlässige Internetverbindung. Dabei müssen verschiedene Instanzen der App (z.B. " +Meldestelle-Desk-App" und "Richter-Desk-App") in Echtzeit miteinander kommunizieren. + +Herausforderungen: + +1. Wie finden sich die Geräte automatisch im LAN? +2. Wie wird die Sicherheit der Datenübertragung ohne zentrale Cloud-Infrastruktur gewährleistet? +3. Wie können Daten zwischen verschiedenen Turnieren innerhalb einer Veranstaltung sauber isoliert werden, während ein + veranstaltungsweiter Austausch (z.B. Chat) möglich bleibt? + +## Entscheidung + +Wir implementieren ein Peer-to-Peer (P2P) Kommunikationsmodell basierend auf folgenden Säulen: + +1. **Discovery (Geräte finden):** Einsatz von `mDNS` (Multicast DNS / ZeroConf), damit sich Instanzen im lokalen + Netzwerk ohne manuelle IP-Konfiguration finden können. +2. **Transport & Echtzeit:** Nutzung von verschlüsselten **WebSockets** für die bidirektionale Datenübertragung in + Echtzeit. +3. **Sicherheit:** Verwendung eines **Shared Security Keys** (Sicherheitsschlüssel), der pro Veranstaltung vergeben + wird. Dieser dient als Basis für die Verschlüsselung und Authentifizierung der Peers. +4. **Daten-Isolierung (Namespacing):** + - Alle fachlichen Datenpakete (Nennungen, Ergebnisse) müssen zwingend eine `turnierId` im Header führen. + - Clients abonnieren spezifische Turnier-Streams. Daten anderer Turniere werden auf Protokollebene verworfen. +5. **Veranstaltungsweiter Chat:** + - Einführung eines globalen Kanals basierend auf der `veranstaltungId`. + - Nachrichten in diesem Kanal haben keine Turnier-Bindung und sind für alle Geräte der Veranstaltung sichtbar. + - Implementierung eines lokalen Nachrichtenspeichers (Buffering), um Offline-Phasen zu überbrücken. + +## Konsequenzen + +### Positiv + +- **Offline-First:** Volle Funktionalität im LAN ohne Internetzwang. +- **Benutzerfreundlichkeit:** Automatische Geräteerkennung spart Zeit beim Setup vor Ort. +- **Datenintegrität:** Strikte Trennung der Turniere verhindert Fehlbuchungen. +- **Flexibilität:** Richter und Meldestelle können nahtlos zusammenarbeiten. + +### Negativ/Herausforderungen + +- **Netzwerk-Komplexität:** Handhabung von Firewall-Regeln und MDNS-Einschränkungen in manchen Router-Konfigurationen. +- **Synchronisation:** Konfliktauflösung bei gleichzeitigen Änderungen (Eventual Consistency) muss implementiert werden. +- **Ressourcen:** Laufende WebSocket-Verbindungen und MDNS-Services benötigen (geringe) zusätzliche Systemressourcen. + +## Betrachtete Alternativen + +- **Zentraler lokaler Server:** Erfordert ein dediziertes "Server-Gerät" und erhöht die Komplexität des Deployments. ( + Verworfen zugunsten von P2P/Master-Client Hybrid). +- **HTTP Polling:** Zu langsam für Echtzeit-Richter-Eingaben und verursacht unnötigen Overhead. (Verworfen zugunsten von + WebSockets). +- **Manuelle IP-Eingabe:** Zu fehleranfällig für Endanwender unter Zeitdruck. (Verworfen zugunsten von mDNS). + +## Referenzen + +- Vision_03: Desktop-App Architektur +- [ADR-0004: Event-driven Communication](0004-event-driven-communication-de.md) +- [ADR-0008: Multiplatform Client Applications](0008-multiplatform-client-applications-de.md) diff --git a/docs/01_Architecture/adr/README.md b/docs/01_Architecture/adr/README.md index cd6e17ad..51a99878 100644 --- a/docs/01_Architecture/adr/README.md +++ b/docs/01_Architecture/adr/README.md @@ -17,5 +17,6 @@ Namensschema: ADR-XXX-title.md mit fortlaufender Nummerierung. - ADR-0014 Bounded Context Mapping & Aggregate Roots - ADR-0015 Context Map & Integration Patterns - ADR-0016 API-Design & Anti-Corruption Layer (ACL) +- ADR-0020 Lokale Netzwerk-Kommunikation und Daten-Isolierung Siehe Template: ADR-000-template.md.