etm-powersync-energy-plugin-etm/RECAP_phase2_ratios.md

RECAP — Phase 2 ratios (autoconsommation / autonomie)

Point de reprise. Dernière session : 2026-07-03. Branche : feature/beta-rulebased. Commit feature : 444b13d (poussé sur origin/feature/beta-rulebased, pas encore sur landing-silo, non mergé).

1. Objectif (rappel)

Exposer autoconsommation + autonomie comme source canonique de l'energymanager, pour remplacer le seam interim app-side EnergyRatiosInterim.compute() (etm-powersync-app/lib/services/energy_ratios.dart).

2. Décision d'architecture — voie (c) (actée)

Comparé (a) champs sur Energy.PowerBalance vs (c) méthode/notif sur le handler NymeaEnergy de NOTRE plugin. Retenu : (c).

• (a) aurait imposé de forker nymea-experience-plugin-energy (plugin cœur), passage mirror→build + rebase 1.14.2→1.15.2 + rebase perpétuel à chaque bump nymea. Coût d'infra que Patrick fuit.
• (c) vit dans powersync-energy-plugin-nymea (déjà forké/buildé), calcule depuis l'interface abstraite stable EnergyManager (totalProduction/Return/ Consumption/Acquisition + signal powerBalanceChanged()). Valeurs identiques à (a) ; seul le canal diffère. Zéro fork du cœur.
• Coût app : un appel GetEnergyRatios + un abonnement EnergyRatiosChanged (vs lire 2 champs PowerBalance). Borné, ponctuel, dans un repo qu'on contrôle.
• Feature request upstream nymea (champs sur PowerBalance) à ouvrir séparément — PAS besoin de forker pour la demander. Si acceptée → migration app triviale.

3. Ce qui est FAIT (commit 444b13d, 11 fichiers)

Fichier	Rôle
energyplugin/etm/ratios/energyratioscalculator.{h,cpp}	Calc GPL pur mesure, porté 1:1 de l'interim
energyplugin/etm/etm.pri	Sources
energyplugin/nymeaenergyjsonhandler.{h,cpp}	Méthode + notif + ctor EnergyManager*
energyplugin/energypluginnymea.cpp	Câblage energyManager()
tests/auto/simulation/experience/energyexperienceenergymock.cpp	Câblage mock
tests/auto/simulation/simulation.{h,cpp}	testEnergyRatiosAlignment
docs/INTERFACE_energyratios.md	Contrat pour l'agent app

Contrat exposé (namespace NymeaEnergy)

• GetEnergyRatios → {o:selfConsumptionRate, o:autonomyRate} Double (%). Champ OMIS si n/a (dénominateur ≤ 0). Jamais null.
• EnergyRatiosChanged → mêmes champs ; branchée sur powerBalanceChanged() ; émise seulement si une valeur (ou sa disponibilité) change.

Sémantique (1:1 interim)

Δ de cumuls sur la journée locale (minuit local). Reseed si 1er appel / nouveau jour / non-monotone (Δ<0 : restart nymead / re-add / rollover). den≤0 → n/a. Clamp [0,100]. Unité %.

autonomie        = (Δ totalConsumption − Δ totalAcquisition) / Δ totalConsumption
autoconsommation = (Δ totalProduction  − Δ totalReturn)      / Δ totalProduction

Validation (session)

• Build prod 0/0, energyratioscalculator.o linké dans le .so.
• testEnergyRatiosAlignment PASS (seed, normal, clamp-bas, den≤0→n/a, non-monotone, nouveau jour).
• Suite simulation 25/0 (testLoadConfigRpc traverse le handler → pas de régression).

4. RESTE À FAIRE (reprise)

1. Merge landing-silo — Patrick le fait lui-même, quand validé. (Workflow : git push origin feature/beta-rulebased:landing-silo, NE PAS toucher master/stable.) Le commit ratios 444b13d est poussé sur origin/feature/beta-rulebased, mais landing-silo est resté à ad385ca (bump .deb d'avant les ratios) — reste à landing + merger.
2. .deb : pas rebuildé. hems tourne 1.15.2+etm2 (rév.3 validée live). Quand on voudra livrer les ratios sur hems → cross-build arm64 + bump version + publier APT (voir DEPLOY.md). À décider au moment voulu.
3. Côté repo app (etm-powersync-app, séparé, Patrick) :
   • Mirrorer docs/INTERFACE_energyratios.md.
   • Swap : GetEnergyRatios au boot + abonnement EnergyRatiosChanged ; supprimer EnergyRatiosInterim.compute() + état baseline ; mapper champ-absent → null.
4. Feature request upstream nymea (champs PowerBalance) — à ouvrir, séparé.

Dette/notes non bloquantes (héritées)

• Worktrees git cassés landing-silo/experimental-silo (git worktree prune/repair).
• docs/TEST_TERRAIN.md stale (dit [EcsRelayAdapter] → devrait être [RelayRouter]).
• Mirror docs/INTERFACE_etmvariableload.md rév.3 vers le repo app (manuel).

5. Build & test (commandes vérifiées en sandbox amd64)

# --- Build prod (0/0 attendu) ---
BD=/tmp/build-prod; rm -rf $BD; mkdir -p $BD; cd $BD
qmake6 <repo>/etm-powersync-energy-plugin-etm.pro && make -j$(nproc)

# --- Build suite simulation ---
BD=/tmp/build-sim; rm -rf $BD; mkdir -p $BD; cd $BD
qmake6 CONFIG+=build_tests <repo>/tests/auto/simulation/simulation.pro && make -j$(nproc)

# --- PIÈGE : rebuild du .so mock si stale (sinon les tests ETM échouent au setup
#     de création de thing : !ecsId.isNull(), relayA && relayB, "valid ThingId") ---
cd <repo>/tests/mocks/plugins/energymocks
qmake6 energymocks.pro && make -j$(nproc)   # régénère aussi plugininfo.h si besoin

# --- Run (NYMEA_PLUGINS_PATH = energymocks + plugins système nymea) ---
cd /tmp/build-sim
export NYMEA_PLUGINS_PATH="/usr/lib/x86_64-linux-gnu/nymea/plugins:<repo>/tests/mocks/plugins/energymocks"
rm -rf /tmp/nymea-test
./nymea-energy-simulation                       # suite complète → 25/0
./nymea-energy-simulation testEnergyRatiosAlignment   # ratios seul → 3/3

6. Garde-fous projet (ne pas oublier)

• Frontière GPL : ratios = pur mesure (Δ compteurs). Aucun optim/forecast/ pondération dans le GPL — ça reste dans l'optimiseur propriétaire.
• Remotes : origin = travail ; etm-public = miroir, jamais push direct ; etm-pro = reliquat, ne pas utiliser.
• Jamais merger vers master/stable depuis cette branche ; rév.3 + ratios = testing.