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

```jsonc
{
  "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.

```jsonc
{
  "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é.