# Agent Plugin — `powersync-energy-plugin-etm`
> Lire aussi le `CLAUDE.md` du dossier parent avant de commencer.

---

## Mon rôle
Je suis le **cœur du HEMS ETM-PowerSync**. Je contiens toute la logique
d'optimisation énergétique : gestion des consommateurs (EV, ECS, PAC),
tarification, météo, et décision d'activation par surplus solaire.

Je suis un **code propriétaire ETM** — pas open-source, pas de publication upstream.

---

## Ce que je FOURNIS

### API JSON-RPC `EnergyPlugin.*`
| Méthode | Rôle |
|---|---|
| `GetChargingInfos(evChargerId)` | Config recharge EV (mode, deadline, SOC cible) |
| `SetChargingInfo(chargingInfo)` | Mettre à jour la config d'une borne EV |
| `GetChargingSchedules(evChargerId)` | Planning calculé par l'OptimizationEngine |
| `GetAvailableSpotMarketProviders()` | Liste des providers tarifs disponibles |
| `SetSpotMarketConfiguration(enabled, providerId)` | Activer/choisir un provider |
| `GetSpotMarketScoreEntries(date)` | Cotations horaires aWATTar |
| `SetPhasePowerLimit(Uint)` | Protection surcharge réseau (A/phase) |
| `SetAcquisitionTolerance(Double)` | Seuil surplus déclenchant la charge |
| `SetBatteryLevelConsideration(Double)` | Facteur batterie dans le calcul surplus |

### Notifications push
`ChargingInfoAdded/Removed/Changed`, `ChargingSchedulesChanged`,
`SpotMarketConfigurationChanged`, `SpotMarketScoreEntriesChanged`,
`PhasePowerLimitChanged`

---

## Ce que je CONSOMME

### Interfaces nymea (détection par interface, jamais par ThingClassId)
| Interface | États lus | Actions envoyées |
|---|---|---|
| `evcharger` | `chargingEnabled`, `maxChargingCurrent`, `pluggedIn`, `charging`, phases | `setChargingEnabled`, `setMaxChargingCurrent` |
| `electricvehicle` | `batteryLevel`, `maxChargingCurrent`, `capacity` | — |
| `rootmeter` / `energymeter` | `currentPowerPhaseA/B/C`, `currentPhaseA/B/C` | — |
| `energystorage` | `currentPower`, `batteryLevel` | — |
| `thermostat` | `temperature`, `mode` | `setMode`, `setTargetTemperature` |

### Depuis `nymea-experience-plugin-energy`
- `EnergyManager*` injecté via `EnergyPlugin::init()`
- Signal `PowerBalanceEntryAdded` → déclenche le cycle d'optimisation (~1 min)

---

## Architecture interne cible

```
powersync-energy-plugin-etm
│
├── TierManager                    ← lit /etc/powersync/tier.conf
│   └── active/désactive les modules selon le tier
│
├── OptimizationEngine             ← chef d'orchestre (à créer)
│   ├── calcule le surplus PV disponible
│   ├── consulte TariffManager (tarif actuel)
│   ├── consulte WeatherManager (météo J+1 si tier Auto+)
│   └── distribue la puissance selon la priorité :
│       1. ECS  (priorité haute — chaleur)
│       2. PAC  (selon température extérieure)
│       3. EV   (selon deadline connue)
│
├── ConsumerManager
│   ├── EvConsumer                 ← refactor SmartChargingManager existant
│   ├── EcsConsumer                ← à créer
│   └── HeatPumpConsumer           ← à créer
│
├── TariffManager
│   ├── StaticHcHpProvider         ← à créer (Community)
│   └── aWATTarProvider            ← ✅ existe (AT + DE)
│
└── WeatherManager
    └── OpenMeteoProvider          ← à créer (Auto uniquement)
```

---

## État actuel du code

### ✅ Fonctionnel
- `SmartChargingManager` : recharge EV sur surplus solaire (mode Eco)
- `SpotMarketManager` : planification aWATTar AT/DE avec cache 24h
- `NymeaEnergyJsonHandler` : API JSON-RPC `EnergyPlugin.*` complète
- Overload protection triphasée
- Détection appareils par interface (zero UUID hardcodé)

### ❌ À corriger en priorité
| Fichier | Problème | Priorité |
|---|---|---|
| `evcharger.cpp:171`, `smartchargingmanager.cpp:394,477,517` | Assume toujours phase A — faux pour EV monophasé sur B/C | 🔴 Haute |
| `smartchargingmanager.cpp:59` | Migration `endTime → endDateTime` + récurrence hebdo non terminée | 🟠 Moyenne |
| `smartchargingmanager.cpp:884` | Planification limitée à 24h | 🟠 Moyenne |
| `smartchargingmanager.cpp:1835` | Actions EV non séquentielles, pas de retry | 🟠 Moyenne |
| `EnergyPluginNymea::init()` | Pas de guard si `EnergyManager*` est null | 🟠 Moyenne |

### ❌ À créer
- `StaticHcHpProvider` (TariffManager — Community)
- `EcsConsumer` (chauffe-eau / ECS sur surplus)
- `HeatPumpConsumer` (PAC sur surplus)
- `OptimizationEngine` (orchestrateur multi-consommateurs)
- `WeatherManager` + `OpenMeteoProvider` (Auto)
- `TierManager` + lecture `/etc/powersync/tier.conf`

---

## Règles de modification

- Tout changement de signature `EnergyPlugin.*` → mettre à jour `INTERFACE.md`
- Tout nouveau StateType ou ActionType → notifier l'Agent App
- Ne jamais modifier `nymea-experience-plugin-energy` depuis ce repo
- Tester sur un système Community avant d'activer des features Auto/Predict AI
- Build : `qmake energyplugin.pro && make -j$(nproc)`
- Install : `/usr/lib/nymea/energy/libnymea_energypluginnymea.so`