Manager-Lizenzierung dokumentieren

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)

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