etm-powersync-docs/interfaces/tariff.md

Contrat tariff — v0.1 (draft)

• Producteur : etm-powersync-tarif-provider (propriétaire, self-hosted)
• Consommateurs : plugin tarif-api (scalaire /now) et etm-powersync-optimizer (série /forecast)
• Transport : HTTP REST

Principe

Le etm-powersync-tarif-provider central maintient la grille TRV (mise à jour 2×/an), interroge l'API RTE Tempo (un seul compte pour tout le parc) et résout le contrat de chaque client. Il expose :

• /now → un scalaire pour le plugin nymea (vocabulaire rank / currentMarketPrice) ;
• /forecast → une série pour l'optimiseur (pondération + prix achat/revente sur l'horizon).

Conventions (définies dans ARCHITECTURE.md) : rank ∈ [0,100], plus bas = meilleur ; prix en c€/kWh (EuroCentPerKiloWattHour).

GET {tariffUrl}/tariff/{client}/now

Consommé par le plugin tarif-api → states nymea.

{
  "rank": 18,            // 0–100, classement de l'heure courante
  "buy": 13.25,          // c€/kWh, prix d'achat courant
  "sell": 10.00,         // c€/kWh, prix de revente courant (constante OA le plus souvent)
  "validUntil": 0        // epoch (s)
}

GET {tariffUrl}/tariff/{client}/forecast

Consommé par l'optimiseur → série sur l'horizon.

{
  "horizon": [
    { "t": 0, "rank": 18, "buy": 13.25, "sell": 10.00 }
    // un point par pas (horaire, ou 15-min selon disponibilité)
  ]
}

Résolution du tarif (côté serveur, non exposé)

Le client choisit à l'installation (cf. ARCHITECTURE.md §8) :

• manuel : tarif fixe ou HC/HP (prix + plages) → rank trivial (fixe = plat ; HC/HP = HC bas, HP haut) ;
• provider : EDF (Base/HC-HP/Tempo), Awattar, Tibber… → rank calculé sur le flux.

Dans tous les cas, la sortie est unifiée : l'optimiseur et le plugin ne voient que rank + buy + sell, jamais la logique de résolution.

Points ouverts (à figer pour v1)

• Identification du client : segment d'URL {client}, en-tête, ou jeton ? Authentification du parc.
• sell : champ par point dans forecast (permet le cas revente spot) ou constante renvoyée à part quand OA ? Le mécanisme par point couvre les deux, au prix d'une légère redondance.
• Pas de temps de forecast (horaire vs 15-min) et profondeur d'horizon.
• Méthode de normalisation du rank (ratio autour de la moyenne vs rang/quantile) — décidée côté serveur, mais à documenter pour la reproductibilité.