From d0edfa2538de1c11302c81212d922e19fdd25f77 Mon Sep 17 00:00:00 2001 From: stefan Date: Wed, 29 Apr 2026 12:35:16 +0200 Subject: [PATCH] =?UTF-8?q?feat(docs):=20neue=20ADRs=20f=C3=BCr=20Plan-USB?= =?UTF-8?q?,=20Offline-Lizenzierung=20&=20Netzwerk-Discovery=20hinzugef?= =?UTF-8?q?=C3=BCgt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Stefan Mogeritsch --- docs/01_Architecture/MASTER_ROADMAP.md | 17 ++++++++-- .../adr/0025-plan-usb-offline-integritaet.md | 22 ++++++++++++ ...0026-offline-lizenzierung-pay-per-event.md | 23 +++++++++++++ ...27-netzwerk-discovery-interface-binding.md | 20 +++++++++++ ...-29_Technische-Initialisierung-Plan-USB.md | 34 +++++++++++++++++++ gradle.properties | 4 +-- 6 files changed, 116 insertions(+), 4 deletions(-) create mode 100644 docs/01_Architecture/adr/0025-plan-usb-offline-integritaet.md create mode 100644 docs/01_Architecture/adr/0026-offline-lizenzierung-pay-per-event.md create mode 100644 docs/01_Architecture/adr/0027-netzwerk-discovery-interface-binding.md create mode 100644 docs/99_Journal/2026-04-29_Technische-Initialisierung-Plan-USB.md diff --git a/docs/01_Architecture/MASTER_ROADMAP.md b/docs/01_Architecture/MASTER_ROADMAP.md index 11439381..b3e5501a 100644 --- a/docs/01_Architecture/MASTER_ROADMAP.md +++ b/docs/01_Architecture/MASTER_ROADMAP.md @@ -73,9 +73,19 @@ und über definierte Schnittstellen kommunizieren. ## 2. Der neue Weg: Fachliche Realität (Roadmap 2026) -Fokus: Physische Implementierung der Turnier-Hierarchie. +Fokus: Physische Implementierung der Turnier-Hierarchie und technisches Onboarding. -### MEILENSTEIN 1: Die Basis-Hierarchie (Prio 1) 🔵 IN ARBEIT +### MEILENSTEIN 0: Technische Geräte-Initialisierung (Prio 1) 🔵 IN ARBEIT + +*Ziel: Ein stabiles, offline-fähiges technisches Fundament für die Desktop-App.* + +* [ ] **OS-Pfad-Auflösung:** Umstellung der `settings.json` auf OS-Standardpfade (`%APPDATA%`, `~/.config`). +* [ ] **Netzwerk-Interface-Binding:** Manuelle Auswahl des Netzwerkadapters zur Vermeidung von Fehl-Discovery. +* [ ] **Geführte Discovery ("Radar-Modus"):** Visuelle Suche nach Mastern im LAN inkl. Hilfe-Tooltips. +* [ ] **Plan-USB Integration:** Paralleler, verschlüsselter Delta-Export auf Wechseldatenträger inkl. Sync-Vorschau. +* [ ] **Offline-Lizenzierung:** Vorbereitung des Ticket-Systems ("Pay-per-Event") zur Offline-Validierung. + +### MEILENSTEIN 1: Die Basis-Hierarchie (Prio 1) *Ziel: Veranstaltung -> Turnier -> Bewerb/Abteilung physisch anlegen und speichern.* @@ -148,6 +158,9 @@ Code-Stand.* | CI/CD | `.gitea/workflows/docker-publish.yaml` | | Agent Playbooks | `docs/04_Agents/Playbooks/` | | ADR-Verzeichnis | `docs/01_Architecture/adr/` | +| ADR-0025: Plan-USB | `docs/01_Architecture/adr/0025-plan-usb-offline-integritaet.md` | +| ADR-0026: Lizenzierung | `docs/01_Architecture/adr/0026-offline-lizenzierung-pay-per-event.md` | +| ADR-0027: Discovery | `docs/01_Architecture/adr/0027-netzwerk-discovery-interface-binding.md` | | ZNS-Importer Roadmap | `docs/01_Architecture/Roadmap_ZNS_Importer.md` | | Masterdata Roadmap | `backend/services/masterdata/docs/ROADMAP.md` | | Masterdata Changelog | `backend/services/masterdata/docs/CHANGELOG.md` | diff --git a/docs/01_Architecture/adr/0025-plan-usb-offline-integritaet.md b/docs/01_Architecture/adr/0025-plan-usb-offline-integritaet.md new file mode 100644 index 00000000..af74dbe6 --- /dev/null +++ b/docs/01_Architecture/adr/0025-plan-usb-offline-integritaet.md @@ -0,0 +1,22 @@ +# ADR-0025: "Plan-USB" & Offline-Datenintegrität + +## Status +Vorgeschlagen + +## Kontext +Im professionellen Turniersport ist eine stabile Netzwerkverbindung (LAN/WLAN) nicht immer garantiert. Ein Ausfall des Netzwerks darf den laufenden Betrieb (Ergebniserfassung, Meldestelle) nicht blockieren. Zudem müssen sensible Reiter- und Pferdedaten (DSGVO) auch auf physischen Datenträgern geschützt sein. + +## Entscheidung +Wir führen die "Plan-USB" Strategie als primären Fallback und parallelen Sicherungsmechanismus ein. + +1. **Permanenter Delta-Export:** Der Master-PC schreibt kontinuierlich verschlüsselte Delta-Pakete (JSON-basiert) in ein definiertes Backup-Verzeichnis. +2. **Verschlüsselung:** Alle Daten auf dem USB-Stick werden mit dem `Shared Key` (AES-256) verschlüsselt. Dies stellt sicher, dass bei Verlust des Sticks keine personenbezogenen Daten gelesen werden können. +3. **Datenintegrität:** Pakete werden signiert, um Manipulationen durch Texteditoren zu verhindern. +4. **Sync-Vorschau:** Die UI bietet eine visuelle Bestätigung ("Sync-Dashboard"), welche Daten zuletzt erfolgreich auf den Stick geschrieben wurden. +5. **Manueller Not-Import:** Clients erhalten eine Funktion, um Delta-Pakete manuell von einem Stick einzulesen und eigene Ergebnisse dorthin zurückzuschreiben. + +## Konsequenzen +- Erhöhte Komplexität in der Sync-Logik (Hybrid-Modus: Netzwerk + Datei). +- Benutzer muss initial einen `Shared Key` festlegen. +- Rechtliche Absicherung bei Verlust von Hardware durch Verschlüsselung. +- Maximale Ausfallsicherheit: Das Turnier kann rein via USB-Stick ("Turnschuh-Netzwerk") zu Ende geführt werden. diff --git a/docs/01_Architecture/adr/0026-offline-lizenzierung-pay-per-event.md b/docs/01_Architecture/adr/0026-offline-lizenzierung-pay-per-event.md new file mode 100644 index 00000000..c4117290 --- /dev/null +++ b/docs/01_Architecture/adr/0026-offline-lizenzierung-pay-per-event.md @@ -0,0 +1,23 @@ +# ADR-0026: Offline-Lizenzierung ("Pay-per-Event") + +## Status +Vorgeschlagen + +## Kontext +Die Software wird als Service pro Veranstaltung lizenziert. Da die App primär offline betrieben wird (Meldestelle am Turnierplatz), kann keine permanente Online-Verbindung zur Lizenzprüfung vorausgesetzt werden. + +## Entscheidung +Wir implementieren ein ticketbasiertes Offline-Lizenzmodell. + +1. **Online-Erwerb:** Der Veranstalter kauft ein "Event-Ticket" über das zentrale Web-Backend. +2. **Lizenz-Datei:** Das Backend generiert eine digital signierte Lizenz-Datei (`.mlic`). Diese enthält: + - Veranstalter-Identität (OEPS-Nummer). + - Gültigkeitszeitraum (Von-Bis). + - Event-Typ (z.B. CSN-B*). +3. **Offline-Aktivierung:** Im `EventWizard` der Desktop-App wird die Lizenz-Datei hochgeladen. Die App validiert die Signatur gegen unseren Public-Key (völlig offline). +4. **Hardware-Fingerprint:** Die Lizenz wird beim ersten Import an die Hardware-ID des Master-PCs gebunden, um unkontrollierte Vervielfältigung zu verhindern. + +## Konsequenzen +- Benutzer muss einmalig (vor dem Turnier) Internetzugang haben, um die Lizenzdatei herunterzuladen. +- Keine Abhängigkeit von Server-Verfügbarkeit während des Turniers. +- Sicherer Schutz unseres Geschäftsmodells ohne Gängelung des ehrlichen Nutzers. diff --git a/docs/01_Architecture/adr/0027-netzwerk-discovery-interface-binding.md b/docs/01_Architecture/adr/0027-netzwerk-discovery-interface-binding.md new file mode 100644 index 00000000..ce27faa1 --- /dev/null +++ b/docs/01_Architecture/adr/0027-netzwerk-discovery-interface-binding.md @@ -0,0 +1,20 @@ +# ADR-0027: Netzwerk-Discovery & Interface-Binding + +## Status +Vorgeschlagen + +## Kontext +Desktop-Rechner auf Turnieren sind oft mit mehreren Netzwerken gleichzeitig verbunden (z.B. LAN für das Turnier-Netzwerk, WLAN für Internet-Hotspot). Automatische Discovery-Dienste (JmDNS) wählen ohne explizite Konfiguration oft das falsche Interface, wodurch sich Clients und Master nicht finden. + +## Entscheidung +Wir führen ein explizites Netzwerk-Management für die Initialisierung ein. + +1. **Interface-Selektion:** Der Benutzer muss bei der technischen Initialisierung explizit wählen, über welches Netzwerk-Interface (IP-Adresse/Adapter) die App kommunizieren soll. +2. **Geführte Discovery:** Sobald ein Interface gewählt ist, startet ein "Radar-Modus". Dieser scannt aktiv nach vorhandenen Master-Geräten. +3. **Adaptive Rolle:** Findet die Discovery einen Master, wird dem Benutzer die Rolle "Client" mit automatischer Konfigurationsübernahme vorgeschlagen. Werden nur Clients oder nichts gefunden, wird die Rolle "Master" empfohlen. +4. **Validierung:** Vor Abschluss der Initialisierung wird ein Verbindungstest durchgeführt (Pre-Flight Check). + +## Konsequenzen +- Verhindert "Geistersuchen" im falschen Netzwerk. +- Erhöht die Benutzerfreundlichkeit durch automatische Vorschläge. +- Erfordert Zugriff auf System-Netzwerk-APIs in der Desktop-Shell. diff --git a/docs/99_Journal/2026-04-29_Technische-Initialisierung-Plan-USB.md b/docs/99_Journal/2026-04-29_Technische-Initialisierung-Plan-USB.md new file mode 100644 index 00000000..4ee5d8d1 --- /dev/null +++ b/docs/99_Journal/2026-04-29_Technische-Initialisierung-Plan-USB.md @@ -0,0 +1,34 @@ +# Curator Journal: Technische Geräte-Initialisierung & "Plan-USB" + +**Datum:** 29. April 2026 +**Agenten:** 🏗️ [Lead Architect], 🎨 [Frontend Expert], 🧹 [Curator] + +## 🎯 Fokus der Session +Definition der robusten technischen Basis für die Desktop-App, insbesondere unter Berücksichtigung von Netzwerkausfällen ("Plan-USB") und Offline-Lizenzierung. + +## 📝 Wichtigste Entscheidungen & Artefakte + +### 1. "Plan-USB" Strategie (ADR-0025) +* **Fallback:** Permanenter, verschlüsselter Export von Delta-Paketen auf USB-Sticks. +* **Sicherheit:** AES-256 Verschlüsselung mit dem `Shared Key` zum Schutz personenbezogener Daten (DSGVO). +* **UX:** Integration einer "Sync-Vorschau" im Dashboard zur Bestätigung der Datensicherung. + +### 2. Offline-Lizenzierung (ADR-0026) +* **Modell:** "Pay-per-Event" via digital signierter Ticket-Dateien (`.mlic`). +* **Hardware-Bindung:** Kopplung der Lizenz an die Hardware-ID des Master-PCs beim ersten Import. +* **Aktivierung:** Völlig offline im Event-Wizard möglich. + +### 3. Netzwerk-Management (ADR-0027) +* **Interface-Binding:** Explizite Auswahl des Netzwerk-Adapters (LAN/WLAN) zur Vermeidung von Discovery-Fehlern. +* **Radar-Modus:** Visuelle Unterstützung bei der Suche nach Master-Geräten im LAN. + +## 🗺️ Roadmap-Update +Die `MASTER_ROADMAP.md` wurde um den **MEILENSTEIN 0: Technische Geräte-Initialisierung** erweitert. Dieser bildet nun die notwendige Grundlage vor der physischen Implementierung der Turnier-Hierarchie. + +## 🚀 Nächste Schritte +1. Implementierung der OS-spezifischen Pfadauflösung für die `settings.json`. +2. Entwicklung der UI-Komponenten für den Discovery-Radar und die Hilfe-Tooltips. +3. Vorbereitung der Verschlüsselungs-Logik für den USB-Export. + +--- +*Dokumentiert durch den Curator.* diff --git a/gradle.properties b/gradle.properties index 4e8dff48..522fbc93 100644 --- a/gradle.properties +++ b/gradle.properties @@ -73,8 +73,8 @@ dev.port.offset=0 # ------------------------------------------------------------------ # Setze enableWasm=true, um die Web-App zu bauen oder Web-spezifische # Module zu testen. Default=false spart massiv Zeit beim Desktop-Build. -enableWasm=true -enableDesktop=false +enableWasm=false +enableDesktop=true # Dokka Gradle plugin V2 mode (with helpers for V1 compatibility) # See https://kotl.in/dokka-gradle-migration