feat(docs): neue ADRs für Plan-USB, Offline-Lizenzierung & Netzwerk-Discovery hinzugefügt

Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>
2026-04-29 12:35:16 +02:00
parent e1bf4d8454
commit d0edfa2538
6 changed files with 116 additions and 4 deletions
@@ -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`                                              |
@@ -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.
@@ -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.
@@ -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.
@@ -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.*