feat(manager): add opt-in native V4 shadow operation telemetry

2026-10-01 16:20:36 +00:00
parent 8d83b083bf
commit 640fe53720
7 changed files with 600 additions and 0 deletions
@@ -0,0 +1,83 @@
+# V4: native Betriebsdaten, ausschliesslich Schattenbetrieb
+
+Stand 2026-10-01: Der optionale Sender und die Diagnose sind implementiert.
+Kein V4-Plan wird damit uebernommen, kein Aktor geschrieben, kein V1-Sollwert
+geaendert. Der Sender ist nach Installation standardmaessig AUS.
+
+## Konfiguration im Manager
+
+- NetzfahrplanV4SchattenAktiv: bool, Standard false. Eigener 60-s-Timer,
+  unabhaengig vom bestehenden Prognose-Timer. Fehler betreffen nur den Sendestatus.
+- NetzfahrplanV4NetzladenErlaubt: bool, Standard false. Betrifft ausschliesslich
+  die im Schattenplan angenommene Berechtigung, keine reale Netzladefreigabe.
+- NetzfahrplanV4BatterieOptionen: JSON-Objekt je Topologie-ID. Optional
+  SOCKapazitaet_kWh und MaxSOC_Prozent (sonst 100). Bei unterschiedlicher Nenn-
+  und Nutzkapazitaet ist SOCKapazitaet_kWh zwingend explizit anzugeben.
+- NetzfahrplanV4MessnachweisVariableID: JSON-Stringvariable, Standard 0.
+  Ein vollstaendiger historischer/registerbasierter Messnachweis-Produzent
+  ist NOCH NICHT integriert. Fehlende Nachweise bleiben fehlend.
+
+Die Quelle muss der gemeinsame Netzanschluss sein. Topologiebatterien werden
+nur einer eindeutigen aktiven Batterieinstanz mit derselben SOC- UND
+Leistungsmessquelle zugeordnet. Externe SDL-Batterien werden nicht automatisch
+hinzugefuegt. SDL-/Grundlastbereinigung bleibt eine separate, noch offene Aufgabe.
+BMS-Grenzen werden mit Topologieleistungen begrenzt. Normale Betriebsreserve
+und technisches Minimum werden nicht verwechselt: die hoehere Grenze gilt.
+
+Bei aktueller Entladehysterese wird die Entladeleistung konservativ auf 0
+begrenzt. Eine spaetere Freigabe innerhalb der 48h wird noch nicht modelliert.
+Das ist sichtbar diagnostiziert und kann den Schattenplan wirtschaftlich
+beschraenken; eine zeitabhaengige Hysterese-Modellierung bleibt offen.
+SOC unterhalb der Reserve wird nicht kuenstlich angehoben: Diagnosefehler,
+kein angeblich gueltiger Plan. Recovery-/Nachladungsmodell bleibt offen.
+
+## Diagnose ohne Netzwerk oder Stellbefehl
+
+Im Symcon-Skript nach Installation des neuen Modulstands:
+
+```php
+<?php
+print_r(json_decode(ENELIX_GetNetzfahrplanV4Diagnose(17004), true));
+echo ENELIX_GetNetzfahrplanV4Sendestatus(17004);
+```
+
+Die Diagnose enthaelt KEINE Tokens oder sonstigen Zugangsdaten. Sie ist auch
+bei ausgeschaltetem Sender verfuegbar. Die Instanz-ID ist fuer Lihrenmoos aus
+der bestehenden Konfiguration bekannt, nicht fuer andere Anlagen zu kopieren.
+Nicht ungeprueft deployen: Host-CLI- und Zielsystemtests getrennt nachweisen.
+
+## Messnachweis-Vertrag (Beispiel, KEINE realen Messwerte)
+
+```json
+{
+  "version": 1,
+  "meterId": "symcon:53476",
+  "measuredAt": "2026-10-01T12:05:00Z",
+  "measuredPeaks": {
+    "2026-10": {"kw": 18.4, "source": "meter_month_register"}
+  },
+  "quarterPast": {
+    "start": "2026-10-01T12:00:00Z",
+    "measuredSeconds": 300,
+    "importKwh": 0.5
+  }
+}
+```
+
+Zulaessige Herkunft: meter_month_register, verified_month_history oder
+verified_new_month. Der Nachweis-Produzent muss deren Wahrheit garantieren.
+Managergrenzen sind NIE ein gemessener Monatspeak. Der Monatswert muss den
+vollstaendigen bisherigen Abrechnungsmonat abdecken. Fuer quarterPast muessen
+Zaehlerzeitpunkt, abgedeckte Sekunden und Entscheidungszeitpunkt exakt passen;
+veraltete Energie wird nicht hochgerechnet oder als aktuelle Messung ausgegeben.
+Die kumulative kWh-Variable allein erfuellt diesen Vertrag noch nicht.
+
+Die V4-API meldet bei fehlendem Monatspeak/quarterPast weiterhin awaiting_inputs.
+Ein HTTP stored bestaetigt nur den Eingang der Telemetrie, nicht einen gueltigen
+Fahrplan und schon gar nicht dessen Ausfuehrung. Backend und Portal-Bruecke
+muessen separat aktiviert werden. Keine neue Modellwahl oder Aktorfreigabe hier.
+
+## Tests
+
+21 offline Konvertierungsszenarien plus PHPUnit-Strukturpruefungen. Werte sind
+synthetisch; keine reale HTTP-Anbindung oder Symcon-Laufzeit damit behauptet.