etm-powersync-app/docs/UI_data_contract.md

# 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.