etm-powersync-energy-plugin-etm/docs/DESIGN_3g.md

DESIGN — 3g : la transplantation du VE dans le waterfall

Statut : conception, à valider avant tout code (AGENTS.md, workflow obligatoire). Entrée : specs/spec_loadmodel.md §12, critère d'acceptation LM-1204-b. Écrit après lecture de smartchargingmanager.cpp (1 900 lignes) et rulebasedscheduler.cpp.

Ce document répond d'abord à la question posée : la transplantation perd-elle quelque chose de ce que le proxy fait de juste ? Oui, trois choses, et elles sont nommées au §3. Deux d'entre elles demandent une décision qui n'est pas technique.

---

1. Le constat qui justifie 3g, et il est plus dur que prévu

Le scénario des deux bornes n'est pas une faiblesse théorique du proxy. C'est un défaut présent, et il se lit en huit lignes (planSurplusCharging, ~1215) :

double allowanceInWatt  = -currentLoad;
double allowanceInAmpere = allowanceInWatt / 230;
while (it.hasNext()) {
    EvCharger *evCharger = it.next();
    double newRawValue = (evCharger->currentPower() / 230) + allowanceInAmpere;
    …
    if (chargingEnabled) it.remove();
}

allowanceInAmpere est calculé UNE fois, avant la boucle, et n'est jamais décrémenté. Chaque borne reçoit donc la totalité du surplus disponible, comme si elle était seule.

Avec 4 kW et deux bornes, le proxy ne produit pas « 2 kW à chacune » — il produit « 4 kW à chacune ». Ce qui rattrape la situation n'est pas l'arbitrage : c'est le compteur au cycle suivant, puis la protection de surcharge. Le système converge par correction d'erreur, pas par décision.

Le it.remove() n'y change rien : il sort la borne de la liste pour les étapes ultérieures, il ne rend pas son allocation au budget des suivantes.

Conséquence pour le critère LM-1204-b : le contre-exemple à ne pas produire — « 2 kW à chacune, rien ne charge » — n'est même pas le comportement actuel. Le comportement actuel est pire, et il est masqué par la boucle de rétroaction du compteur. Le test doit donc se lire ainsi : avant 3g, les deux bornes démarrent puis sont rattrapées ; après 3g, une seule démarre, délibérément.

---

2. Ce que la transplantation apporte sans rien ajouter

Ces points sont déjà résolus par le waterfall, et le VE en hérite gratuitement :

Ce que le proxy fait à la main	Ce que le waterfall fait déjà
Allocation identique à toutes les bornes	Cascade : remainingSurplusW décrémenté à chaque charge
Rang des bornes inexistant	priority, trié une fois, un seul rang pour toutes les charges
Rendre à la borne sa propre consommation	Recrédit anti-clignotement (correction B), déjà en place
EV_IDLE pour tout refus	BELOW_MIN_POWER / SURPLUS_INSUFFICIENT, distinction du §12

Le plancher du VE existe déjà dans le proxy — minimalChargingCurrent × acquisitionTolerance — et c'est exactement la notion du §12. Il devient declared.minPowerW.

⚠️ Avec une nuance qui compte : minimalChargingCurrent vaut max(charger.maxChargingCurrentMinValue, car.minChargingCurrent) (ligne 605). Le plancher d'une borne dépend donc de la voiture branchée. Ce n'est pas une valeur de configuration comme pour l'ECS : c'est une valeur runtime, republiée à chaque descriptor(). Le §12 le permet (le champ est dans LoadDeclared, pas seulement dans LoadConfig), mais l'écran ne doit pas la présenter comme un réglage.

---

3. Ce qui NE se transporte PAS — les trois points à trancher

3.1 L'échéance : la machinerie n'a pas d'équivalent, et le waterfall ne sait pas acheter

Le proxy force la charge à fond quand projectedEndTime > cible − 10 min. Ce calcul repose sur remainingPercentageToCharge = targetPercentage − carBatteryLevel (ligne 666) et sur une projection de durée — de la machinerie propre au VE, alimentée par le SoC de la voiture.

needs { dailyDeadline, minEnergyWhPerDay } porte bien la déclaration d'une échéance. Mais :

• le scheduler ne la lit pas — rulebasedscheduler.cpp porte en toutes lettres « Grid funding (ECS/PAC) : dormant jusqu'à 3f (waterfall réseau) — non implémenté ici » ;
• forcer à fond pour tenir une échéance, c'est soutirer au réseau, donc franchir la même frontière que les planchers éco du §10.

Décision demandée. Trois options, et elles n'ont pas le même coût :

(a) 3g déplace l'allocation de surplus seulement, et l'échéance reste au proxy — qui continue de produire une action TimeRequirement prioritaire, court-circuitant le waterfall quand elle mord. Le proxy ne disparaît pas ; il maigrit. (b) 3g embarque 3f (waterfall réseau) et l'échéance devient un besoin comme un autre. Lot bien plus gros, et il recoupe le §10. (c) L'échéance est suspendue en beta, la borne restant en surplus pur. À écarter : c'est la fonction qui a motivé le proxy.

Ma recommandation : (a). Elle isole 3g sur ce qu'il corrige réellement — la cascade — et laisse l'échéance là où sa machinerie vit déjà. La fusionner avec 3f mêlerait deux franchissements de frontière dans un même lot.

3.2 La prise en compte de la batterie change de portée

Le proxy calcule, à l'intérieur du chemin VE : pause de la charge sous le seuil de SOC, tampon de 500 W quand la batterie charge sous le seuil, et réinjection de la puissance batterie dans le surplus au-dessus.

Ce n'est pas une règle « VE » : c'est une règle de budget. Transplanté tel quel, deux issues, et aucune n'est neutre :

• la monter dans le budget → l'ECS et la PAC se mettent, elles aussi, à respecter batteryLevelConsideration. C'est probablement souhaitable — mais c'est un changement de comportement pour des charges qui ne l'ont jamais eu, sur des installations en service ;
• la laisser au VE → il faut la réécrire dans l'adaptateur EV, et le budget publié en télémétrie cesse de correspondre à ce que le VE a réellement vu.

Décision demandée. Ma recommandation : la monter dans le budget, et le dire au changelog comme un changement de comportement assumé. Une batterie sous son seuil de réserve ne devrait pas plus alimenter un chauffe-eau qu'une voiture.

3.3 Le nombre de phases se décide en ampères, le waterfall parle en watts

getBestPhaseCount() choisit 1 ou 3 phases à partir du courant brut, puis divise. Le waterfall, lui, alloue des watts — la conversion watts → ampères et le choix du nombre de phases doivent donc vivre dans l'adaptateur EV, au moment d'exécuter.

Ce n'est pas une perte : c'est conforme à la règle 4 d'AGENTS.md (les bornes de l'adaptateur écrêtent toute sortie de stratégie). Mais l'ordre change : aujourd'hui le nombre de phases est choisi avant de connaître l'allocation finale ; demain il sera choisi après. Une borne qui bascule en triphasé change son plancher effectif (6 A × 3 = 4,1 kW au lieu de 1,4 kW), donc le plancher publié doit correspondre au nombre de phases visé, pas au nombre courant.

C'est le piège le plus subtil du lot, et il produirait un défaut silencieux : un plancher annoncé à 1,4 kW, une borne qui passe en triphasé, et une allocation de 2 kW qui ne démarre rien.

---

4. Ce qui reste au proxy, quoi qu'il arrive

• planSpotMarketCharging — tarifs dynamiques (tier Predict AI), financement Grid, hors surplus. Précédence déjà gérée par le scheduler.
• verifyOverloadProtection / Recovery — protection par phase. Elle ne déleste que les bornes (§ du lot D) ; son extension au waterfall est une précondition du §10, pas de 3g.
• prepareInformation, l'estimation de SoC, setupPluggedInHandlers, lockOnUnplug — état du processus de charge, sans équivalent chez les autres charges.
• Le filtrage d'entrée : borne sans voiture assignée, ou en ChargingModeNormal. En waterfall, ces bornes doivent être absentes du contexte, pas présentes à rang 0 : une borne en mode manuel n'est pas « servie en dernier », elle est hors arbitrage.

---

4-bis. Vérifié : evReservedW après la transplantation

evReservedW (correction A) existe parce que l'EV est décidé avant le waterfall : sa consigne du cycle n'est pas encore visible au compteur, donc on la réserve. Une fois le VE dans la cascade, sa réservation devient son allocation — la compter en plus serait un double comptage.

Audit du financement de chaque action EV (rulebasedscheduler.cpp) :

action	financement	après 3g-1
spot market (l. 61)	Grid	reste au proxy → doit rester dans evReservedW
buildTimeRequirementAction (l. 202)	Grid	reste au proxy → doit rester
buildMinCurrentAction (l. 219)	Surplus	disparaît — remplacé par la cascade
buildIdleAction (l. 233)	Surplus	disparaît — remplacé par les motifs du §12

Conclusion : le filtre de evReservedW doit devenir funding == LoadAction::Grid. Il ne s'agit pas de le supprimer mais de le restreindre à ce qui reste hors cascade. Tant que la seconde moitié de 3g-1 n'est pas faite, il reste correct tel quel.

5. Découpage proposé

Étape	Contenu	Éprouvable
3g-1	EvAdapter publie declared.minPowerW (runtime, depuis la voiture) et LoadContext ; le VE entre dans nonEvLoads ; EV_IDLE cède à BELOW_MIN_POWER / SURPLUS_INSUFFICIENT	oui — LM-1204-b, les deux bornes du banc
3g-2	Conversion watts → ampères + choix de phases dans l'adaptateur, plancher publié pour le nombre de phases visé	oui, banc
3g-3	batteryLevelConsideration monte dans le budget (§3.2)	oui, banc
3g-4	Échéance : selon la décision du §3.1	dépend

3g-1 seul suffit à satisfaire LM-1204-b, et c'est le seul qui corrige le défaut du §1.

---

6. Ce qu'il faut décider avant que je code

1. §3.1 — l'échéance : option (a), (b) ou (c) ? (Recommandation : (a).)
2. §3.2 — la batterie : monter la règle dans le budget, en assumant le changement de comportement pour l'ECS et la PAC ? (Recommandation : oui.)
3. Le découpage : 3g-1 livré et éprouvé seul, ou le lot entier d'un coup ? (Recommandation : 3g-1 seul — il porte la correction, et il est le seul dont le critère d'acceptation est déjà écrit.)