From d804ba4bc13af7b62327c4768e103c44d3f4e57c Mon Sep 17 00:00:00 2001 From: dh_Agent Date: Tue, 22 Sep 2026 07:07:29 +0000 Subject: [PATCH] Manager-Lizenzierung dokumentieren --- README.md | 2 +- docs/module/Manager/README.md | 90 ++++++++++++++++++++++++++++++++--- 2 files changed, 85 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index b19175a..1ec7817 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ der Uebernahme in einen Freigabebranch erfolgreich sein. - [Zentrale Liste offener Teamentscheidungen](docs/Offene-Punkte.md) - [Manager-Verbraucher-Schnittstelle](docs/Schnittstelle.md) -- [Manager-Modul](docs/module/Manager/README.md) +- [Manager-Modul inklusive Lizenzierung](docs/module/Manager/README.md) - [Warmwassererwaermer-Modul](docs/module/Wassererwaermer/README.md) - [Verbraucher-1-Stufig-Modul](docs/module/Verbraucher-1-Stufig/README.md) - [Ladestation-Stand-Alone-Modul](docs/module/Ladestation-Stand-Alone/README.md) diff --git a/docs/module/Manager/README.md b/docs/module/Manager/README.md index 73b6dfa..9f3664e 100644 --- a/docs/module/Manager/README.md +++ b/docs/module/Manager/README.md @@ -59,12 +59,90 @@ Manager. Im Modus `Aus` bleibt Solarladen aktiv, nur die Peak-Begrenzung entfäl Die Monatsgrenzen werden in den Grundeinstellungen über eine Schaltfläche ein- und ausgeblendet. Die automatische Verbrauchersuche kann dort erneut ausgeführt werden, ohne andere ungespeicherte Formulareingaben zu verlieren. -Die Lizenzierung steht an erster Stelle des Formulars. Der Manager erzeugt dabei -einmalig eine UUIDv4 als stabile Installations-ID. Mit "Lizenz pruefen und binden" -wird der eingegebene Code ueber -`POST https://license.enelix.ch/api/v1/licenses/activate` an diese Installation -gebunden. Es werden weder Portal-Cookies noch ein CSRF-Token oder ein noch nicht -implementierter Lizenzendpunkt verwendet. + +## Lizenzierung + +Der Manager arbeitet nur mit einer gueltigen Manager-Lizenz. Das Lizenzfeld steht +zuoberst im Konfigurationsformular. Ohne Freigabe bleibt die Instanz mit Status +`203` inaktiv und sendet keine Leistungsvorgaben. + +### Voraussetzungen + +- Der Auftrag im Enelix-Lizenzportal ist bezahlt und enthaelt eine aktive + Manager-Berechtigung. +- IP-Symcon erreicht `https://license.enelix.ch` ueber HTTPS (Port 443). +- Der Lizenzcode liegt im Format `ENX-XXXX-XXXX-XXXX-XXXX` vor. + +### Lizenz aktivieren + +1. Manager-Konfiguration in IP-Symcon oeffnen. +2. Lizenzcode im Bereich `Lizenzierung` eintragen. +3. `Lizenz pruefen und binden` ausloesen. +4. Die erfolgreiche Freigabe am angezeigten Lizenzstatus kontrollieren. +5. Die Manager-Konfiguration mit `Uebernehmen` beziehungsweise `OK` speichern, + damit der eingegebene Lizenzcode als Property erhalten bleibt. + +Beim ersten Anlegen erzeugt die Manager-Instanz eine UUIDv4 als stabile +Installations-ID. Die Aktivierung sendet ausschliesslich `code` und +`installationId` per +`POST https://license.enelix.ch/api/v1/licenses/activate`. Sie benoetigt weder +Portal-Cookies noch einen CSRF-Token. Derselbe Code kann von derselben +Installation erneut abgerufen werden; die Bindung an eine andere Installation +wird vom Lizenzserver abgelehnt. + +### Berechtigungen + +| Berechtigung | Freigegebene Funktion | +| --- | --- | +| `manager_standard` | Manager-Grundregelung ohne Lastspitzenmodus. | +| `manager_peak` | Manager-Grundregelung einschliesslich konstantem oder monatlichem Lastspitzenmodus. | + +Wird mit `manager_standard` ein Lastspitzenmodus aktiviert, bleibt der Manager +mit dem Hinweis `Peak Shaving ist nicht lizenziert` gesperrt. `manager_peak` +gilt zugleich als Berechtigung fuer die Grundregelung. + +### Erneuerung und Offline-Betrieb + +Die erfolgreiche Serverantwort wird als Lease in der Manager-Instanz gespeichert. +Der Manager erneuert sie ab `refreshAfter` automatisch ueber denselben +Aktivierungsendpunkt. Schlaegt eine Erneuerung fehl, wird fruehestens nach einer +Stunde erneut angefragt. Eine bereits bestaetigte Entwicklungsfreigabe bleibt +bis `offlineUntil` verwendbar. Der aktuelle Entwicklungsvertrag setzt diesen +Zeitpunkt ungefaehr 14 Tage nach Ausstellung. Danach sperrt der Manager die +Regelung, bis der Lizenzserver wieder eine gueltige Antwort liefert. + +Die Installations-ID und die Lease liegen in internen Instanzattributen. Bei +einer Migration muss deshalb die vollstaendige Manager-Instanz mitsamt ihren +Attributen uebernommen werden. Eine neu erzeugte Instanz erhaelt eine andere +Installations-ID und kann einen bereits gebundenen Code nicht selbststaendig +uebertragen. + +### Status und Fehlerbehebung + +| Anzeige / Serverstatus | Bedeutung und Massnahme | +| --- | --- | +| `Lizenzcode fehlt.` | Code eintragen, pruefen und die Konfiguration speichern. | +| `Lizenzcode ist ungueltig.` | Format und Zeichen des Codes kontrollieren. | +| HTTP `404` | Code unbekannt oder zugehoeriger Auftrag noch nicht bezahlt. | +| HTTP `409` | Code ist bereits an eine andere Installation gebunden. | +| HTTP `429` | Zu viele Aktivierungsversuche; vor dem naechsten Versuch warten. | +| `Lizenzserver nicht erreichbar` | DNS, Internetzugang, HTTPS und Systemzeit des Symcon-Systems pruefen. Eine bestehende Lease gilt nur bis `offlineUntil`. | +| `Offline-Freigabe ist abgelaufen.` | Verbindung zum Lizenzserver wiederherstellen und Lizenz erneut pruefen. | + +Fuer eine genauere Diagnose koennen die Diagnosevariablen eingeblendet werden. +`Lizenzstatus` zeigt dann den aktuellen Zustand. Mit aktiviertem Debug-Logging +werden Fehlermeldungen der Lizenzpruefung ausgegeben, niemals jedoch der +Lizenzcode selbst. + +### Datenschutz und Entwicklungsstand + +Der Lizenzcode wird als Manager-Property in der IP-Symcon-Konfiguration +gespeichert. Fuer den internen Abgleich mit der Lease verwendet der Manager +zusaetzlich nur einen SHA-256-Hash und schreibt den Code nicht ins Debug-Log. +Die aktuelle Serverantwort ist ein Entwicklungsvertrag mit +`development: true` und noch nicht kryptografisch signiert. Ein optionaler +Geraete-Public-Key sowie Challenge-, Heartbeat- oder separate +Entitlement-Endpunkte werden vom Manager derzeit bewusst nicht verwendet. ## Verteilalgorithmus