diff --git a/docs/UI_data_contract.md b/docs/UI_data_contract.md new file mode 100644 index 0000000..84ef878 --- /dev/null +++ b/docs/UI_data_contract.md @@ -0,0 +1,358 @@ +# ETM-PowerSync — Contrat de données UI (qui calcule quoi) + +> Compagnon de `DASHBOARD_SPEC.md`. Tranche la question récurrente +> « **qui calcule les valeurs affichées ?** » pour chaque écran. +> Rev. 4 — §8.3 corrigé : **réutiliser l'InfluxDB nymea** (pas SQLite), DB ETM +> dédié + rollups natifs (retention policies) + checkpoint local pour le contrôle +> vivant. Alerte : tag Docker `latest` → InfluxDB 3 Core (72 h de rétention). +> Rev. 3 — ajout §7 (Héos data inputs & metering map) + §8 (persistance & +> historique : mesures brutes stockées / ratios dérivés / plan stocké). +> Rev. 2 — §2 corrigé après sonde terrain sur `.75` (nymead 1.15.2) : +> `GetPowerBalanceLogs` n'expose **aucun ratio**, seulement +> production/consumption/acquisition/storage + cumuls. La source canonique +> des ratios est donc le **state du plugin energymanager**, pas l'app, +> pas l'Energy experience nymea. + +--- + +## 0. Principe directeur + +**L'app Flutter est un moteur de rendu, pas un moteur de calcul.** + +Source de vérité unique, comme `INTERFACE_etmvariableload.md` côté plugins. +Si l'app refait les maths de son côté, elle finit par **contredire l'arbitre** +(cf. Invariant 3 — charges pilotées au Grid mais hors surplus d'arbitrage ; +cf. phantom EV reservation — commandé vs mesuré). Un seul endroit calcule. + +### Frontière + +| Catégorie | Où ça se calcule | Raison | +|---|---|---| +| Sens / couleur des flèches du flow | **App** (dérivé du signe d'un état) | trivial, non ambigu, instantané | +| Surplus d'arbitrage | **energymanager plugin** | respecte l'Invariant 3 | +| Auto-conso / autonomie / totaux jour | **energymanager plugin (state)** | nymea 1.15.2 ne logge pas les ratios (sonde `.75`) | +| Décisions / raisons en cours | **energymanager** (`loadActions[]`) | l'arbitre est seul à savoir *pourquoi* | +| Plan de la journée (futur) | **Héos** (etm-powersync-eos) | seul à avoir forecast + MILP | +| Plan de la journée (passé) | **nymea energy logs** | historique réalisé | + +### Couches (rappel) + +1. **nymea things** → états instantanés bruts (P par compteur) + energy logs (historique). +2. **energymanager plugin** → surplus (Invariant 3), décisions+raisons, ratios live. +3. **etm-powersync-eos (Héos)** → forecast + plan + raisonnement tarifaire. +4. **App Flutter** → rend 1+2+3. Ne dérive QUE le sens des flèches. + +--- + +## 1. Flux énergétique (flow-card) + +### 1.1 Direction & couleur — règles figées + +| Nœud | Comportement | Sens des particules | Couleur | +|---|---|---|---| +| **Solaire (PV)** | producteur pur | toujours PV → hub | jaune `#FEC113`, jamais inversé | +| **Maison** | consommateur pur | toujours hub → Maison | bleu `#31A3DD`, jamais inversé | +| **Réseau** | bidirectionnel | import = Réseau→hub / export = hub→Réseau | import **rouge** (coût) · export **vert atténué** (revente faible) | +| **Batterie** | bidirectionnel | charge = hub→Bat / décharge = Bat→hub | décharge **vert** (aide) · charge **neutre/bleu** | + +> La convention de signe doit être **explicite et documentée** (un seul endroit). +> Sur la capture actuelle : Réseau en rouge vers le centre = import 2.4 kW ✓. +> Vérifier que le sens batterie reflète bien charge vs décharge. + +### 1.2 Héos au centre — décision à prendre + +Physiquement **faux** : Héos est le contrôleur, pas un nœud électrique. +Le vrai point de couplage AC est au centre, Héos est à côté. + +- **Option A** — garder Héos au centre comme « le cerveau ». Les lignes = la + conscience/le contrôle, pas le câble. Métaphore assumée. Fort en branding. + Acceptable car la carte parle *de pilotage*. +- **Option B** — nœud central = point de couplage (busbar AC neutre), Héos en + badge/overlay. Physiquement correct, plus sobre. + +→ **Reco** : A est défendable tant que l'animation respecte 1.1. Ne pas laisser +les particules « traverser » Héos dans un sens physiquement impossible. + +### 1.3 Mono vs multi-onduleur + +- Le **nœud Solaire du diagramme affiche TOUJOURS l'agrégat** (somme). Ne jamais + multiplier les nœuds dans le schéma — ça le casse visuellement. +- Le détail (tap sur `+`) gère la multiplicité : + - 1 onduleur → prod + strings si dispo. + - N onduleurs → agrégat en tête + liste par onduleur. + +### 1.4 Détails Maison & compteur non mesuré (ex. PAC) + +- Nœud Maison = consommation **totale**, dérivée : + `Maison = PV + import_grid + décharge_bat − export_grid − charge_bat`. +- Le détail ne montre des sous-postes **que pour les compteurs qui existent**. +- **Charge connue mais non mesurée (PAC sans compteur dédié)** : + - ne **jamais** afficher un faux 0 ni une estimation inventée (anti-oversell) ; + - soit on l'omet, soit on affiche « non mesuré » explicitement. +- Décision implicite à acter : la décomposition par appareil **nécessite un + compteur par appareil**. Pas de compteur PAC = pas de ligne PAC. + +--- + +## 2. Cartes Auto-conso / Autonomie + +- **Agrégats sur une période** → **jamais** calculés par l'app (sinon dérive + selon le rythme de polling, et désaccord avec le bilan/logs). +- **Réalité 1.15.2 (sonde `.75`)** : `GetPowerBalanceLogs` n'expose **aucun + ratio ni décomposition par bande** — seulement production / consumption / + acquisition / storage + **cumuls**. La prémisse « ratios déjà calculés + backend » est donc fausse littéralement. +- **Source canonique = state du plugin energymanager** (une seule source). + Pas l'app, pas l'Energy experience. Justification : ce n'est pas un pis-aller, + c'est le **seul composant capable de calculer juste** (voir ci-dessous). + +### 2.1 Formules déterministes (depuis cumuls, zéro drift de polling) + +``` +autonomie = (consommation − import) / consommation +autoconsommation = (production − export) / production +``` + +- **autonomie** : dérivable directement, `import` est dans les logs. ✅ +- **autoconsommation** : exige **l'export (return) comme cumul DISTINCT**. + ⚠️ **Point bloquant à vérifier sur la sonde** : `acquisition` est-il *net + signé* (import − export en un nombre) ou import/export **séparés** ? + - séparés → dérivable depuis logs ; + - net → **non récupérable** des logs ⇒ l'energymanager doit **intégrer + import et export lui-même** (il voit la P réseau signée en continu, + + connaissance Invariant 3). C'est ce qui rend #2 *architecturalement obligé*. +- Ces formules sont **correctes avec batterie** : import/export au compteur + réseau nettent déjà les flux batterie ; PV→batterie→maison compte comme + autoconsommé (pas exporté). Pas de correction round-trip. + +### 2.2 Bande autoconso instantanée (graphe Puissances) + +- Même propriétaire : `selfConsumptionPower = max(production − max(export,0), 0)`. +- À exposer en **state plugin**, pas dérivé app — sinon re-bug de signe à chaque + refonte (le `.abs()` interim n'était qu'un pansement sur un calcul app-side). + +--- + +## 3. Carte décisions — AVEC vs SANS Héos (frontière open-core) + +La carte actuelle parle **au futur** : « coût réseau ce soir 0,22 € », +« objectif 80 % pour 18h ». Ça suppose un **forecast + un plan** = Héos. + +### 3.1 Avec Héos (tier Predict/AI) + +Inchangé : raisonnement tarifaire, objectifs horaires, plan. Texte = sortie Héos. + +### 3.2 Sans Héos (tier Community, rule-based) + +Le rule-based **n'a ni forecast ni plan**. Il ne peut donc pas tenir ce discours. + +- En-tête : « **Pilotage automatique** » (pas « Héos pilote »). +- Décisions exprimées **au présent, réactives** : + - « Surplus solaire 2.0 kW → chauffe-eau activé » + - « Pas de surplus → voiture en pause » +- **Zéro promesse au futur** (pas de « ce soir », pas de « objectif 18h »). + Honnêteté : ne pas faire croire à une intelligence prédictive absente. +- Source du texte : `loadActions[]` de l'energymanager (la *raison* additive + qu'on a déjà figée), pas une reconstruction côté app. + +### 3.3 Conséquence sur « Plan de la journée » + +Voir §4 : sans Héos, la partie future (hachurée) disparaît. Surface d'upsell +naturelle : « Activez Héos pour planifier la journée ». + +--- + +## 4. Plan de la journée + +- **Passé (barres pleines)** = énergie réalisée → **nymea energy logs**. +- **Futur (barres hachurées)** = **Héos** (etm-powersync-eos → socket → + energymanager → state/endpoint exposé). L'app ne projette **rien** elle-même. +- Sans Héos : n'afficher **que le passé**. Pas de projection bricolée côté app. +- Légende (Maison / ECS / VE / Batterie / Réseau / Batt→maison) = catégories + de l'allocation Héos ; mêmes clés que le plan, pas de remapping côté app. + +--- + +## 5. Config — Things (placeholder actuel) + +L'app n'est **pas** un fork de nymea-app → il faut réimplémenter les RPC +(`Integrations.*` : GetThings, GetThingClasses, GetVendors, DiscoverThings, +AddThing/PairThing/ConfirmPairing, EditThing, RemoveThing). C'est gros, et +nymea-app le fait déjà bien. **Décision de périmètre à acter explicitement** : + +- **Option MVP** — liste read-only des things + actions simples (renommer, + activer/désactiver, supprimer). 80 % de la complexité du wizard est dans + l'ajout avec discovery/pairing/paramètres — on l'évite. +- **Option ciblée** — réimplémenter le wizard **seulement pour TES classes** + (eastron, abbterra, v2c… dont tu maîtrises les params). +- **Option hand-off** — la config avancée reste dans nymea-app (installateur), + l'app ETM se concentre sur l'experience énergie (client final). + +→ Question vraie : le client final a-t-il **besoin** d'ajouter des things, ou +c'est un acte installateur (toi/Mathieu) ? Si installateur-only, ne pas +construire un demi-wizard. + +--- + +## 6. Config — Protocoles → ModbusRTU master + +Surface **finie et bien définie**, dont **tes propres plugins compteurs +dépendent** (SDM, abbterra) → vaut le coup en natif. + +- `ModbusRtu.GetSerialPorts` → lister les ports. +- `GetModbusRtuMasters` / `AddModbusRtuMaster` / `Reconfigure…` / `Remove…`. +- Params : serialPort, baudrate, parity, stopBits, dataBits. + +→ Petit, fermé, et bloquant pour tes meters. Le construire avant le wizard Things. + +--- + +## 7. Héos — data inputs & metering map + +### 7.1 Règle de granularité + +**nymea ne stocke que ce qui est compté.** Un consommateur n'a de série de +puissance que s'il est un *thing avec un state `currentPower`* (interfaces +`smartmeter`/`energymeter`/consumer/producer, `logged: true`). +→ **La granularité d'optimisation Héos = la granularité de comptage.** + +⚠️ **Convention de signe nymea** : `currentPower` est toujours du point de vue +**consommateur** → **négatif pour un producteur** (le PV a un `currentPower` < 0). +Signe canonique, à ne jamais « deviner » côté app (cause du bug autoconso / `.abs()`). + +### 7.2 Carte de comptage (état du parc) + +| Consommateur | Thing ? | `currentPower` ? | Héos optimise finement ? | +|---|---|---|---| +| Réseau (GRID) | ✅ | ✅ | référence (root meter) | +| PV / onduleur | ✅ | ✅ (négatif) | oui, **par onduleur** | +| Batterie | ✅ | ✅ | oui | +| VE (wallbox) | ✅ | ✅ | oui | +| ECS (relais SDM) | ✅ | ✅ ou déduit du niveau | oui | +| **PAC** | SG-Ready | ❌ `sgReadyMode` seul | **non — pilotable, pas mesurable** | +| **Clim (Zenkeo/Tuya)** | bridge | ⚠️ seulement si DP Tuya puissance | partiel | +| Maison (base) | dérivé | résidu = total − charges pilotées | `Maison_base` | + +- **Trou PAC** : SG-Ready n'expose que `sgReadyMode` (Off/Low/Standard/High), + aucune puissance. Sans compteur dédié, Héos **pilote** la PAC mais ne la + **mesure** pas ; sa conso reste noyée dans `Maison_base`. +- **Clim** : seulement si `clim_bridge.py` remonte un state puissance. +- **Production par panneau de toit : non.** Par onduleur oui ; par string + seulement si le plugin expose les states MPPT. Ne pas concevoir Héos en + supposant une granularité panneau. +- **Conséquence** : toute optim PAC/clim fine est une décision **matérielle** + (poser un compteur / exposer un DP), pas logicielle. + +### 7.3 Alimentation de Héos — Route B (tranché) + +- **States = source live**, lus en in-process par le plugin. +- **energymanager = série historique canonique** par consommateur/générateur, + échantillonnée à la résolution du MPC (buckets 15 min), Invariant-3-correcte. +- **logs nymea = filet / contrôle croisé**, pas l'entrée primaire de Héos. +- Justification : la Route A (logs nymea) impose le downsampling/rétention de + nymea sans contrôle du schéma, et ne sépare pas import/export. Seul le plugin + peut scinder import/export depuis la P réseau signée et figer la décomposition. + +--- + +## 8. Persistance & historique + +> Deux classes de données aux cycles de vie **opposés**. C'est la règle centrale. + +### 8.1 Mesures — stocker le brut, dériver les ratios + +- On stocke le **brut intégrable** par bucket : production, consommation, + import, export (séparés !), + par charge pilotée, + charge/décharge batterie. +- Les **ratios ne sont JAMAIS stockés** comme donnée primaire — vues dérivées : + +``` +autonomie = (Σ conso − Σ import) / Σ conso +autoconsommation = (Σ prod − Σ export) / Σ prod +``` + + → recalculables à la lecture pour **n'importe quelle période** (jour / semaine + / mois / plage custom). Stocker des ratios figés = verrouillage de granularité. + +### 8.2 Plan — stocker explicitement (non recalculable) + +- Un **ratio se reconstruit à l'infini** depuis le brut. + Un **plan ne se recalcule jamais après coup** : il dépendait des prévisions + PV/conso/tarif **à T0** et de la solution MILP de cet instant. + → **S'il n'est pas persisté au moment où il est produit, il est perdu.** +- Schéma : `(produced_at, bucket_start, asset, planned_value [, inputs_hash])`. + → stockable dans Influx tagué par `plan_run_id` ; le plan **en cours + d'exécution** est en plus checkpointé localement (§8.3). +- Cadence limitée : ne pas stocker chaque tick MPC. Garder un **plan-of-record** + (ex. 1/h ou snapshot début+fin de journée), pas chaque itération. +- Débloque **plan vs réalisé** : overlay prévu/réalisé → confiance client + + matière première du federated-learning-lite (erreur de prévision). + +### 8.3 Store & rétention (réalité embarquée) + +**Réutiliser l'InfluxDB déjà présente** (nymea s'en sert). L'argument « service en +plus » ne tient pas : le coût est déjà payé. Influx est faite pour les séries ; +ses **retention policies + downsampling (CQ 1.x / tasks 2.x)** font les rollups +**nativement** → moins de code qu'un SQLite hand-rollé. Et configurer la rétention +**corrige au passage le « shard accumulation »** qui faisait crash-looper l'instance +(les shards s'empilaient faute de purge). + +- **DB / bucket ETM dédié** — pas dans les measurements nymea. Isole ta donnée des + upgrades/migrations nymea et te donne ta propre rétention. +- **Rollups par paliers** (retention policies dédiées) : + - 15 min → ~30 jours · horaire → ~2 ans · journalier → indéfini +- ⚠️ **Pinner la version Influx.** Le tag Docker `latest` pointe désormais vers + **InfluxDB 3 Core**, qui en OSS impose **72 h de rétention** + limite 5 DB → + destruction silencieuse de l'historique. Le diagnostic « shard accumulation » + = TSM = on est en **1.x / 2.x** (bonne version). Ne jamais laisser un upgrade + auto basculer en 3 Core. +- **Checkpoint local minuscule** (fichier / petit SQLite) pour l'**état de contrôle + vivant** (plan en cours d'exécution, dernier setpoint). Si Influx tombe, Héos ne + doit **ni hard-fail ni perdre le plan exécuté** — dégradé propre, cohérent avec + le L2 watchdog. ***Logging store down ≠ arbitrage down.*** +- Distinct du log engine nymea (filet brut générique) : la série dans le DB ETM est + la **série curée** (Invariant-3, import/export scindés) dont dérivent Héos *et* + l'historique client. + +### 8.4 Read model de l'historique client + +``` +période choisie + → agrège les mesures au palier de rollup correspondant + → dérive autoconso / autonomie (§8.1) + → overlay plan-of-record (§8.2) si dispo → vue « prévu vs réalisé » +``` + +Même donnée parcourue dans les deux sens du temps : passé = mesures réalisées, +futur = plan Héos. La metering map §7.2 est le socle commun (entrée Héos + bandes +du « Plan de la journée »). + +--- + +## Récap des décisions + +1. Héos au centre du flow : **Option A — métaphore « cerveau » assumée** + (condition : animation respecte les sens figés §1.1, jamais de particule à + contre-sens à travers Héos). ✅ tranché. +2. Source des ratios : **state du plugin energymanager** (ni app, ni Energy + experience). Court terme : dérivation depuis cumuls via §2.1, **sous réserve** + que l'export soit loggé séparément — sinon le plugin intègre import/export + lui-même. ✅ tranché. +3. Périmètre Things app : **hand-off nymea-app + MVP read-only client** ; + **ModbusRTU master en premier** (§6, bloquant pour SDM/abbterra). Wizard + ciblé seulement si vraiment nécessaire. ✅ tranché. +4. Carte sans Héos : wording **présent/réactif** + masquage du futur, texte + issu de `loadActions[]`. ✅ tranché. +5. Alimentation Héos : **Route B** — states (live) + série canonique + energymanager (15 min, Invariant-3), logs nymea en filet. ✅ tranché. +6. Persistance : **mesures brutes stockées + ratios dérivés** ; **plan stocké + explicitement** (non recalculable) ; **réutiliser l'InfluxDB existante** (DB ETM + dédié, rollups via retention policies) + **checkpoint local** pour l'état de + contrôle vivant. ⚠️ pinner Influx en **1.x/2.x** (pas 3 Core / 72 h). ✅ tranché. + +### Reste ouvert (à lever avant code §2 / §8) + +- `acquisition` dans `GetPowerBalanceLogs` = **net signé** ou **import/export + séparés** ? Détermine si l'autoconso est dérivable des logs ou doit être + intégrée par le plugin (§2.1 / §8.1). +- **Carte de comptage §7.2** : décider quels consommateurs non mesurés (PAC, + clim) justifient un compteur matériel pour une optim fine.