OPENCLAW_ARCHIVE3_17/workspace/airtria-concierge-vehicule-SPEC.md

# Concierge véhicule Airtria — spécification (convenue OpenClaw ↔ EVCS, 2026-09-13)

## 🔁 MISE À JOUR 2026-09-15 : déclenchement AU BRANCHEMENT (plus à la session)
Le propriétaire veut la question dès le BRANCHEMENT (au branchement du soir, la borne
ne tire rien avant les HC de 01:24 ; attendre une session laissait la 1re mal étiquetée).
concierge-live.js détecte désormais sur les transitions 'on' de `evenement` (plus sur
session_charge). Le helper porte `branchement` = **ts::text VERBATIM** de la transition
'on' (PAS horodatage_ha, antérieur de 3-51 s → EVCS raterait le branchement en cours),
qui remplace `sessions`. Fraîcheur = sélecteur changé dans [on−10 min, min(now, on+30 min)]
(EVCS). Règle de puissance abandonnée au branchement (pas de session/p_max) → on demande
pour TOUT branchement périmé, invité géré par la réponse. Division : Airtria détecte le
branchement + demande + publie ; EVCS résout, mémorise, applique aux sessions du câble au
fur et à mesure (HC 01:24 comprises), refuse les contradictions. Validé contre l'historique
(15 branchements, distribution de fraîcheur inchangée) ; déployé, test de portée vert.

## 🟢 LIVE EN PRODUCTION depuis 2026-09-14 02:22
Kill-switch airtria_concierge_enabled = ON, lecteur EVCS déployé (commit d8ef69b).
Preuve end-to-end réelle : session 12/09 11:55 → JEEP, vehicule_sur=t, evenement
origine=airtria/source_airtria=whatsapp ; cycle suivant idempotent (etiquette=0).
Colonne : 6 confirmées (arbitrages voix du 13/09) / 13 à confirmer. Défaut vehicule_sur
basculé à false, 17 lignes rattrapées. Bug de format clef (PG `…+02` vs ISO `…Z`, même
instant) attrapé au dry-run EVCS et corrigé côté service (canonisation ISO avant dédup) —
côté Airtria rien à changer, on envoie la clef verbatim. Véhicule débranché 14/09 01:31 :
prochaine question sur un branchement neuf. Le concierge tourne en régime réel.

## VALIDÉ END-TO-END (2026-09-13, essai réel, kill-switch OFF)
Simulation sur le branchement 12/09 11:55 : détection → question WhatsApp → réponse
« JEEP » du propriétaire → routage → helper publié
`{"sessions":["2026-09-12 11:55:54.493+02"],"label":"JEEP","confirmed_at":…,"source":"whatsapp"}`
→ confirmation « ✅ Noté ». Base non touchée (kill-switch OFF).
⚠️ LEÇON ROUTAGE : le modèle local (qwen) IGNORE une consigne de réponse discrète
(a répondu « Bonjour Thierry » au lieu de router). Il faut un RÉFLEXE PRIORITAIRE en
tête du traitement WhatsApp (AGENTS.md §5.0) : vérifier concierge-pending.json et lancer
`answer` AVANT toute autre réponse. Avec ça, le routage passe de façon fiable.
Cron `concierge-vehicule` ACTIVÉ (enabled) → mode essai : une vraie charge à sélecteur
périmé déclenchera une vraie question. Reste pour appliquer en base : kill-switch ON +
lecteur EVCS (après validation de son dry-run).

## État d'avancement (2026-09-13)
Fichiers dans le workspace : `concierge-detection.js` (détection + calibration),
`concierge-write.js` (écriture helper, entité unique + relecture),
`concierge-write.test.js` (test de portée, VERT), `concierge-live.js`
(sous-commandes `detect` et `answer`). Dépendance `pg` installée dans le workspace.
TESTÉ : calibration 2-3-2-1-1-1 / 5 questions / 0 mixte ; aller-retour écriture sur
le vrai helper ; detect bootstrap ; chemin question (état en attente, clef debut
verbatim) ; chemin réponse (reconnaissance + publication + confirmation).
CÂBLÉ : cron `concierge-vehicule` (id d113b997-0942-4d71-9e9b-d64249949540, payload
COMMAND `node concierge-live.js detect`, */10, announce whatsapp) — testé : exitCode 0,
sortie vide → delivery suppressReason "empty" (aucun WhatsApp vide). Routage des réponses
ajouté à AGENTS.md §5bis (sauvegarde AGENTS.md.bak-concierge-*). pg installé dans le
workspace.
ACTIVATION PAR ÉTAPES (toutes décisions du propriétaire) :
(1) `openclaw cron enable d113b997-…` → boucle Q/R en réel, le helper se publie sur une
    vraie réponse. La BASE n'est pas touchée.
(2) EVCS déploie son lecteur en DRY-RUN (redémarre son service) : il journalise ce qu'il
    écrirait (jointure ±1 s sur les clefs verbatim, extension au groupe) SANS écrire.
    Valide la moitié EVCS avant que ça compte.
(3) kill-switch `input_boolean.airtria_concierge_enabled` → ON + EVCS commit la bascule
    → les étiquettes corrigent session_charge.
⚠️ La bascule vehicule_sur n'est PAS neutralisée par le kill-switch : le kill-switch gate
l'APPLICATION d'un label, pas le DEFAULT de la colonne. Passer DEFAULT false trop tôt
afficherait 100 % de sessions « douteuses » (motif faux) sur le Grafana « Les véhicules ».
Donc la bascule = TROIS pièces soudées au commit du ON : DEFAULT false + true-sur-
confirmation-humaine + libellé Grafana « selecteur change » → honnête.
Décision COMMAND vs agentTurn : command choisi car déterministe (pas de LLM, sortie exacte,
suppression auto sur vide). Cron existants modèles : daily-email-report (Gmail 8h30),
orange-cloture (17h40).


Objectif : combler le seul trou qu'aucun capteur ne comble — savoir QUEL véhicule
(VW / JEEP / invité / bientôt moto ZERO) est branché sur la borne EVCS, pour que
`session_charge` cesse d'attribuer l'énergie au mauvais véhicule.

Contexte déclencheur : le sélecteur `input_select.victron_evcs_vehicle` est resté
figé sur « VW » du 07/09 au 13/09 → 11 sessions d'affilée mal étiquetées, sans
aucun signal. VW et JEEP sont électriquement indiscernables l'une de l'autre
(~3 680 vs ~3 655 W à 20 A).

## Principe d'architecture (non négociable)
- Le cœur déterministe EVCS reste seul juge. Airtria intervient APRÈS, jamais
  dans la boucle 30 s.
- Une seule main sur chaque variable. Airtria ne touche AUCUN actionneur.
- Toute valeur porte son propre horodatage (`confirmed_at`), pas celui du run.
- Producteur qui s'arrête : invalidation STRUCTURELLE (le label est lié à une
  session précise, il ne peut pas contaminer une autre session). On NE vide PAS
  le helper (fenêtre de perte inutile) ; on laisse la dernière confirmation.

## Décisions du propriétaire (2026-09-13)
- Lancement v0 + v1 ENSEMBLE.
- Canal de correction = écriture HA restreinte `input_text.airtria_*`
  (variante PostgreSQL INSERT-only écartée).

## Détection d'une session (v0)
- Source = table PostgreSQL `session_charge`, PAS le binary_sensor HA (il flappe :
  disconnected x2 câble branché le 07/09).
- ⚠️ NE PAS utiliser `evcs_lecture` : il a INSERT sur `evenement` (registre
  d'audit partagé) — inadapté à un agent. Rôle DÉDIÉ `airtria_ro`, LOGIN +
  SELECT sur `session_charge` et `evenement` uniquement, aucune écriture.
  Mot de passe déposé protégé dans le workspace (.pg-airtria). Base evcs sur
  10.10.10.22:5433.
- Colonnes utiles (session_charge, 17 col) : `debut` (clef, MS), `fin`,
  `terminee`, `vehicule`, `vehicule_sur` (DEFAULT true → à basculer côté service),
  `p_max_w` + `consigne_max_a` + `courant_max_a` (règle invité), `debranche_a`
  (frontière de groupe), `energie_compteur_kwh` (l'énergie qui FAIT FOI, pas
  `energie_kwh` qui rate si le service démarre après le début de charge).
- On hérite du débounce du service d'historisation : une ligne `session_charge`
  ne s'ouvre qu'au-delà de 300 W soutenus, se ferme après 10 min sous le seuil.
- Cadence : cron 10 min. La latence n'a aucun effet (session de plusieurs heures).
- Airtria garde son propre état (dernière `debut` traitée) dans son workspace.

## Test d'ambiguïté (quand poser la question) — RÈGLE FINALE
- Le sélecteur est FRAIS (ne pas demander) SEULEMENT s'il a changé de valeur dans
  la fenêtre [début du branchement − 10 min, début + 30 min]. Sinon → DEMANDER.
  Source : `evenement` (genre='intervention', entite=input_select.victron_evcs_vehicle),
  JAMAIS le `last_changed` HA. Implémenté : `selectorFreshAt()` dans concierge-live.js.
- Pourquoi la fenêtre serrée (EVCS, données) : un changement de sélecteur EN COURS de
  branchement ne peut pas étiqueter ce branchement (câble non bougé) — c'est le
  producteur mécanique des groupes mixtes. Ma 1ère règle (« bougé depuis le débranchement
  précédent ») déclarait « frais » EXACTEMENT les 2 branchements mixtes de l'historique.
- Validé sur 11 branchements 04-12/09 : 1 seul FRAIS (05/09, réglé à +13 min), 10 à
  DEMANDER dont les 2 mixtes. Stat marquante : sélecteur réglé au bon moment 1 fois / 12.
- Mauvais test (rejeté) : « sélecteur inchangé depuis le début de CETTE session »
  — vrai aussi quand le propriétaire a bien réglé au branchement.
- Avant de conclure « pas de geste humain », vérifier la table `evenement`
  (un redémarrage HA a pu changer la valeur ; l'auteur y est tracé depuis le 12/09).
- ✅ CAVEAT `last_changed` (2026-09-13) CORRIGÉ : le `last_changed` HA est remis à zéro
  par un passage `unavailable` (blip MQTT) sans vrai changement → il ferait croire
  « frais » un sélecteur périmé. La règle ci-dessus lit donc `evenement` (qui saute les
  lectures unavailable), pas `last_changed`. Limites de la source : le journal commence
  le 04/09 ; la mémoire du détecteur est en-processus (un changement pendant un
  redémarrage du service n'est pas rattrapé) → l'absence d'événement ne prouve pas tout,
  mais dans le doute la règle DEMANDE = le bon côté.
- En cas de doute : poser la question. Un WhatsApp de trop coûte moins qu'une
  ligne fausse pour toujours.

## Pré-filtre puissance (réduit les questions) — règle À SENS UNIQUE
- Le bon critère n'est pas la puissance brute mais la puissance RELATIVE À LA
  CONSIGNE. VW/JEEP saturent vers 16 A embarqués quelle que soit la consigne
  (~3 606 à 3 784 W à 20 A) ; la Megane a suivi jusqu'à 28 A (6 360 W).
- Règle conclusive : `consigne_max_a >= 20` ET `p_max_w > 4200` ⟹ **invité**,
  Airtria pré-étiquette « invité » SANS déranger le propriétaire.
- `consigne_max_a < 20` ⟹ AUCUNE information (6 A plafonne ~1 700 W pour tout le
  monde) → demander.
- ⚠️ La réciproque est FAUSSE : `p_max_w <= 4200` ne prouve PAS que c'est un
  véhicule du foyer (un invité à 16 A embarqués est indiscernable de la VW).
  Au-dessus du seuil on sait, en dessous on demande. NE JAMAIS inverser.
- La consigne vient du contrôleur EVCS : plafond 20 A hors BOOST
  (`input_number.evcs_plafond_courant_edf_on`, 28 en BOOST). Le cas conclusif
  est donc fréquent ; le cas muet = sessions à courant réduit (fin de charge
  solaire à 6 A).
- Moto ZERO (fin sept. 2026) : tombera sous 3,6 kW → côté foyer, distinguée par
  le sélecteur comme les autres. Seuil à réévaluer à son arrivée.

## Regroupement = frontière FACTUELLE via `evenement` (pas le temps)
- ⚠️ Ne PAS regrouper par écart de temps : le creux soir→heures creuses fait
  ~5 h 20 (fin solaire ~20:00 → HC ~01:24), indistinguable d'un vrai
  débranchement/rebranchement par un seuil de durée.
- La frontière est un FAIT : les transitions de
  `binary_sensor.victron_evcs_vehicle_connected` sont écrites dans `evenement`
  (off→on au branchement, on→off au débranchement). Un branchement = intervalle
  [off→on … on→off suivant]. Toutes les lignes `session_charge` dont `debut`
  tombe dans l'intervalle = même véhicule = UNE seule question. Intervalle ouvert
  (encore branché) = groupe en cours.
- Exemple semaine 08-12/09 : 6 branchements = 2-3-2-1-1-1 sessions
  (le mercredi 15:55+19:35+01:25 est un TRIPLET, même câble). Un regroupement qui
  rend des paires soir/nuit est FAUX.
- Le groupe reste la notion d'Airtria (propriétaire unique sur la notion dérivée) ;
  le service EVCS ne fait qu'itérer la liste du helper.
- ⚠️ Ne PAS émettre une écriture helper par session (elles écraseraient le même
  helper ; le service qui poll toutes les 60 s ne verrait que la dernière → perte
  silencieuse des autres). Le helper porte donc une LISTE de session_debut (voir
  ci-dessous), publiée en UNE écriture atomique. Le service itère la liste.
- Fallback coupure : les transitions ne sont écrites que si le service tourne.
  Frontière absente/incomplète → groupe INCERTAIN → poser la question PAR session,
  jamais sur une frontière reconstruite. Un WhatsApp de trop > une étiquette fausse.

## Sources de données (requêtes, lecture seule via airtria_ro)
- Frontière des branchements — table `evenement` (colonnes : ts, genre, source,
  resume, detail jsonb, id). Filtre robuste (pas de parsing de texte) :
  `detail->>'entite' = 'binary_sensor.victron_evcs_vehicle_connected'`,
  `detail->>'apres'` = 'on' (branchement) / 'off' (débranchement). Ordonner sur
  `ts`, borner les intervalles sur `detail->>'horodatage_ha'` (vérité physique
  après rattrapage). Le champ `entite` n'existe que sur les transitions → les
  fins de session sont exclues naturellement.
- Bonus qualité : les événements de fin de session portent `detail->>'debut'`
  (= session_charge.debut exact, ms comprises) et les trois énergies côte à côte
  (`kwh_compteur` fait foi, `kwh_integre`, `kwh_borne`). Un écart entre elles est
  un signal de qualité à remonter (pas une question au propriétaire).
- Accès : Node + node-postgres (pur JS, à ajouter au workspace) ; PG:5433
  joignable depuis la machine spark → calibration exécutable en lecture seule.
- Implémentation : `concierge-detection.js` (mode calibration, aucune écriture).

## La question WhatsApp
- Un seul message, au démarrage d'une session ambiguë (ou d'un groupe).
- Ouverte, pas binaire : « Quel véhicule est branché ? » avec options lues
  dynamiquement dans le sélecteur + « aucune des deux / invité ».
- Porte la clef `debut` de la session pour permettre l'application a posteriori.
- Réponse possible des heures plus tard, ou jamais.

## Le helper HA (le contrat v1)
- `input_text.airtria_vehicle_label`, déclaré **max: 255** (défaut HA = 100 →
  rejet silencieux ; incident vécu forecast_updated max:32 le 08/09).
- Contenu = UN JSON atomique portant une LISTE de sessions (atomicité
  indispensable, HA n'a pas de transaction entre entités) :
  {"sessions":["2026-09-08 19:39:12.334+02","2026-09-09 01:26:04.887+02"],
   "label":"VW","confirmed_at":"<horodatage Airtria>","source":"whatsapp"}
- Chaque entrée de `sessions` = clef `debut` rendue par la requête SANS
  reformatage (les `debut` portent les ms, ex. 2026-09-12 11:55:54.493+02 ; un
  arrondi minute ne matcherait jamais ; pas d'aller-retour par un objet Date).
  Le service EVCS joint sur ±1 s, pour chaque entrée de la liste.
- Taille : 2 sessions ≈ 150 car, 3 ≈ 180, sous 255. Au-delà, publier en deux
  écritures espacées de > 90 s (le service aura polé entre les deux).
- Après CHAQUE écriture : relire l'état et vérifier qu'il est identique à l'envoi
  (seul moyen de détecter un rejet silencieux HA).
- Auto-correction (« JEEP… non VW ») = republier avec `confirmed_at` plus récent ;
  le service applique le dernier pour une `session_debut` donnée.
- On NE vide PAS le helper à {} : l'invalidation est structurelle (session_debut).
  Le vidage ouvrirait une fenêtre de perte si le service est arrêté entre publication
  et vidage.

## Garde-fous d'écriture (non négociables — restriction CONVENTIONNELLE)
Le canal choisi est un token HA, qui peut techniquement écrire n'importe quel
service HA : la restriction à airtria_* ne tient QUE par la discipline du code.
Donc, côté OpenClaw :
- Le nom de l'entité écrite est une CONSTANTE EN DUR unique
  (`input_text.airtria_vehicle_label`), jamais construite dynamiquement, jamais
  interpolée.
- Un test type « mode ombre » ÉCHOUE si une écriture cible autre chose que cette
  constante (équivalent du tests/advisor/run.mjs d'EVCS qui garde advisor_*).
- Aucune écriture d'actionneur, jamais (liste des variables à propriétaire unique
  dans le MANUEL EVCS ; `carte-decisions.mjs` / `enquete.mjs` avant tout doute).

## Recoupement a posteriori (qualité de données)
- Comparer `session_charge.debranche_a` aux départs attendus :
  VW 08:50 (`input_datetime.victron_evcs_departure_time`),
  JEEP 06:30 (`input_datetime.victron_evcs_departure_time_jeep`).
- `debranche_a` n'est renseignée que si le service voit le débranchement (1 fois
  sur 12 récemment) → ne pas supposer qu'elle est toujours là.
- Ne signaler que si ça CONTREDIT le label (comportement idiot), pas à chaque
  session. Pas de notification pour l'état normal.

## Côté service EVCS (v1, fait par la session EVCS)
- Lit le helper chaque cycle (60 s), JSON.parse en try/catch ; objet vide /
  illisible / champs manquants → ne rien faire.
- `confirmed_at` antérieur au `debut` → ignoré. Jointure ±1 s sur session_debut.
- Met à jour `vehicule` ; `vehicule_sur` passe à VRAI uniquement sur confirmation
  humaine (changement de sens : défaut basculé à faux ; lignes antérieures gardent
  l'ancienne sémantique). Trace l'application dans `evenement` avec la source.

## Validation avant mise en service
- `tools/campagne-conseiller.mjs` (dépôt EVCS) rejoue des instants réels ;
  cumuler 3 runs (un run de 5 passages = bruit, écart-type ~0,22).
- Jeu de calibrage = les 12 sessions du 07 au 12/09, étiquetées par le
  propriétaire (voir ci-dessous). ⚠️ Le v0 ne DÉDUIT pas VW vs JEEP (impossible :
  la semaine, la routine était inversée — femme/JEEP en congés, fils/VW en stage
  sans retour le midi). Ce qui est testé = le ROUTAGE : MEGANE auto-détectée
  invité par la règle puissance ; toutes les autres correctement routées vers
  « demander » (sélecteur périmé). Ce sont les réponses du propriétaire qui
  donnent VW/JEEP. Si le routage rate une des 12, revoir la règle, pas l'étiquette.

### Cibles de routage du v0 (les 6 branchements du 08-12/09)
- 11/09 16:53→18:27 (Megane, 1 session) : auto-invité par la règle puissance,
  AUCUNE question.
- 5 autres branchements (2-3-2-1-1) : routés vers la question (sélecteur périmé).
- Total attendu = 5 questions pour 12 sessions. Un regroupement qui rend des
  paires soir/nuit (au lieu du triplet du mercredi) est FAUX.

### Jeu de calibrage FINAL (corrigé en base, arbitré par le propriétaire 2026-09-13)
```
branchement                     sessions                              étiquette
sam 12/09 11:55 → (en cours)    11:55  5,94                           JEEP
sam 12/09 11:42 → 11:53         11:42  0,09                           JEEP
ven 11/09 16:53 → 18:27         16:54  7,45  6360W/28A                MEGANE (auto)
jeu 10/09 18:19 → ven 16:27     18:20 2,97 · 01:24 4,26               VW
mer 09/09 15:55 → jeu 09:05     15:55 6,61 · 19:35 0,77 · 01:25 4,88  JEEP (triplet)
mar 08/09 19:39 → mer 08:57     19:39 0,76 · 01:26 5,01               VW
```
Semaine : 5 VW, 6 JEEP, 1 MEGANE (contre 11 VW + 1 JEEP avant correction).
Le triplet mercredi = JEEP les trois : la femme a branché la JEEP, le fils n'a pas
voulu la débrancher le soir pour mettre la VW → il a roulé à l'essence le jeudi.
Contexte humain qu'aucune règle ne produit — la raison d'être du concierge.
MEGANE = voiture de service (Rennes) + dépannage d'amis → « invité » RÉCURRENT.

### Cas tordus que le module DOIT gérer (dans les données de la semaine)
- sam 12/09 : on 11:42, off 11:53, on 11:55 = DEUX branchements (2 min de
  débranchement), pas du flapping. La session 0,09 kWh en est la trace.
- ven 11/09 : off 16:27, on 16:53 = DEUX branchements (26 min ; débranche un
  véhicule foyer pour brancher la Megane).
- ⚠️ AUCUN seuil de durée pour fusionner : 2 min et 26 min sont l'une et l'autre
  de vraies séparations. Règle = « toute transition compte » ; défensive limitée
  aux incohérences STRUCTURELLES (on déjà ouvert, off sans ouverture).
- Le branchement 12/09 11:55 est ENCORE OUVERT (borne haute nulle) → groupe en
  cours, ne pas conclure qu'il est incomplet.

### Fenêtre d'analyse : commencer sur un 'on'
Une fenêtre doit démarrer sur un `on`, jamais au milieu d'un branchement : sinon
le premier événement est un `off` orphelin (branchement ouvert avant la fenêtre),
la session ouverte avant tombe hors intervalle et est classée « incertaine » à
tort (ex. démarrer au 08/09 00:00 fait apparaître 6 questions au lieu de 5, à
cause de la session 08/09 01:26). En production, aucun souci (on suit le flux) ;
règle valable surtout au rejeu historique. Calibration calée sur 08/09 19:00.

### Invariant à vérifier EN PERMANENCE (le contrôle le plus solide du projet)
Un seul câble ⟹ toutes les sessions d'un même branchement portent la MÊME
étiquette. Un groupe à étiquettes mixtes = frontière fausse (Airtria) OU ligne
fausse (base) — les deux méritent une alerte. Propriété PHYSIQUE : ne nécessite
aucune connaissance métier (ni routine, ni horaire, ni puissance), et aucune
évolution de règle ne peut l'invalider. À faire tourner en continu, pas seulement
à la calibration — c'est ce qui aurait signalé le triplet incohérent le jour même.

## Points de vigilance
- ⚠️ Inventaire BMS mensonger (découvert 2026-09-13) : le BMS annonce 4 modules /
  400 Ah alors que le parc en compte 9 (le LV-Hub ne remonte que le groupe maître).
  Mesuré : 0,312 kWh/point de SOC (vs 0,169 sur l'ancien parc de 7). NE JAMAIS
  utiliser `capacite_installee` ni `nombre_de_modules_en_ligne` comme source de
  capacité (sous-estiment de ~38 %). Source qui fait foi :
  `input_number.evcs_balance_modules_en_service` (13 aujourd'hui). Concerne surtout
  un futur rôle 2 (rétro-évaluation énergétique), pas le concierge véhicule.
- Helper HA en place : `input_text.airtria_vehicle_label` (max:255, état initial
  `unknown` = « rien à appliquer »). Kill-switch consommateur
  `input_boolean.airtria_concierge_enabled` (OFF) = propriété d'EVCS, Airtria n'y
  touche pas. Aller-retour écriture/relecture validé le 2026-09-13.
- SPOF : OpenClaw vit sur 10.10.10.17, la machine qui porte aussi HA et n8n.
  Faible enjeu pour l'ID véhicule, mais réel. Chien de garde sur 10.10.10.22.
- Prérequis à câbler : (1) accès lecture PostgreSQL pour Airtria
  (`PG_LECTURE_PASSWORD`, déposé protégé comme le token HA) ; (2) création du
  helper `input_text.airtria_vehicle_label` (max:255) dans le paquet HA.