Files
Support-Agent/docs/decisions.md
T
maximeandClaude Opus 5.5 75619e8f1c Remove the raw expert notes and the archived stations
Point the docs to the summaries that remain and record D-033.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 11:51:03 +02:00

356 lines
42 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Journal des décisions
Décisions de niveau **projet**, au format ADR allégé (inspiré de MADR). Ce qui est propre à une analyse va dans sa fiche (`docs/analyses/analyse_NN.md`).
Règles du journal :
- On ajoute, on ne réécrit pas.
- Une décision qui change garde son texte : son **statut** devient « remplacée par D-0XX », et la nouvelle entrée cite l'ancienne.
- Champs : **Statut**, **Décision**, **Pourquoi**, **Options écartées** (avec leur raison, pour ne pas les reproposer), **Conséquence**. Les champs sans objet sont omis.
- Statuts : `active` · `remplacée par D-0XX` · `remplacée en partie par D-0XX` · `abandonnée`.
---
## D-001 — 2026-10-09 — Point d'entrée : scan proactif d'un export
- **Statut** : active.
- **Décision** : l'agent parcourt un export, détecte les événements, les classe et explique chacun.
- **Pourquoi** : expliquer l'anomalie avant que le client ne pose la question.
- **Options écartées** : commencer par le mode « question de support » (« pourquoi D-300-A a sauté ? ») ; il viendra ensuite, sur le même socle.
## D-002 — 2026-10-09 — Premier cas d'usage : santé énergétique des stations
- **Statut** : active.
- **Décision** : commencer par la tension batterie et les interruptions de mesure, sur des stations solaires et sur secteur.
- **Pourquoi** : cas simple et fréquent, avec des diagnostics experts disponibles. Ici, le trou de données *est* l'anomalie.
- **Options écartées** : commencer par l'interprétation des déplacements ; elle viendra ensuite.
## D-003 — 2026-10-09 — 100 % analytique, embarquable, données réelles
- **Statut** : active, remplacée en partie par D-027 (le refus du LLM ne vaut plus que pour la couche déterministe).
- **Décision** : pas de LLM ; pas de données synthétiques ; code d'analyse en bibliothèque standard Python.
- **Pourquoi** : la cible est le système embarqué de la station, souvent sur batterie et panneau solaire. Chaque conclusion doit être traçable jusqu'aux faits calculés.
- **Options écartées** :
- le LLM ou l'agent de synthèse prévu par les docs AIMsight ;
- les CSV simulés et les générateurs de scénarios (refus explicite de l'utilisateur) ;
- pandas et numpy dans le code d'analyse.
## D-004 — 2026-10-09 — Définition : anomalie énergétique = régime non soutenable
- **Statut** : active.
- **Décision** : une anomalie énergétique est un régime qui menace le fonctionnement : l'apport ne couvre pas la consommation sur un cycle.
- **Pourquoi** : une station débranchée du secteur avec une batterie pleine est déjà en situation critique. Le niveau de charge dit **quand** la station tombera, pas **si** elle tombera.
- **Options écartées** : définir l'anomalie par une batterie basse ou par une zone de charge (plateau, coude). Ce n'est qu'un indicateur d'urgence.
- **Conséquence** : l'apport n'est pas mesuré (l'INA219 mesure la consommation). Il se déduit de la réaction de la batterie.
## D-005 — 2026-10-09 — Analyses multiples et imparfaites, combinées
- **Statut** : active.
- **Décision** : chaque analyse est une preuve parmi d'autres. Il suffit qu'elle ait raison dans la majorité des cas. C'est la combinaison d'analyses indépendantes qui fait le diagnostic. Préférer des fenêtres larges (plusieurs jours, multiples de 24 h).
- **Pourquoi** : ne pas surinvestir dans la précision d'une seule règle.
- **Options écartées** :
- une seule analyse « parfaite » qui couvrirait tous les cas ;
- un score continu de 0 à 1, qui serait une pseudo-probabilité, interdite.
- **Conséquence** : toutes les analyses suivent le contrat commun `run(series) -> {analysis, rule, points: [{t, value, anomaly, facts}]}`. Le calcul est causal. Une analyse seule conclut au plus `consistent with`.
## D-006 — 2026-10-09 — Un script et une fiche par analyse
- **Statut** : remplacée par D-026.
- **Décision** : l'analyse NN a un point d'entrée `src/analyse_NN.py` et une fiche `docs/analyses/analyse_NN.md`.
- **Pourquoi** : suivre une à une les analyses à venir, qui seront nombreuses.
- **Options écartées** : un `main.py` unique à la racine (essayé, puis renommé et déplacé).
## D-007 — 2026-10-09 — Livrable : graphiques HTML ouverts dans le navigateur
- **Statut** : remplacée en partie par D-011 (disposition des graphiques). Le reste est actif.
- **Décision** : le livrable d'une analyse est un graphique plotly, ouvert automatiquement dans le navigateur. Disposition initiale : en haut, tous les champs superposés, comme sur la plateforme de monitoring de l'entreprise ; dessous, l'analyse.
- **Pourquoi** : c'est le graphique qui sert, pas le texte.
- **Options écartées** : le résumé texte dans le terminal comme livrable principal, jugé peu utile. Il reste disponible via `energy_check.py`.
- **Conséquence** : plotly n'est installé que dans `.venv/`, sur le poste de dev. Le script y bascule seul.
## D-008 — 2026-10-09 — Prototype expérimental : pas de tests automatisés
- **Statut** : active, jusqu'à la fin de la phase prototype.
- **Décision** : les tests unitaires et de régression sont supprimés. On n'en ajoute pas.
- **Pourquoi** : ils ajoutent de la complexité pour un code très expérimental.
- **Options écartées** : des tests de régression sur données réelles (32 tests, supprimés).
- **Conséquence** : on vérifie à la main en lançant le script de l'analyse. Les tests restent récupérables dans l'historique git (commit `53b4f7e`).
## D-009 — 2026-10-09 — Jeu de travail : VERMONT seule
- **Statut** : active.
- **Décision** : les analyses ne tournent que sur VERMONT, le seul dataset complet (les 7 métriques système, comme sur la plateforme), placé dans `data/`. Les autres stations (`BusVoltage` seule) sont mises de côté dans `data/archive/`.
- **Pourquoi** : disposer de tous les champs vaut mieux qu'avoir plus de stations incomplètes.
- **Options écartées** : supprimer les autres stations (irréversible, car non versionnées) ; continuer à analyser les 5 stations.
- **Conséquence** : il n'y a plus de station saine pour vérifier qu'une analyse ne donne pas de fausse alerte. Les seuils calés avant cette décision gardent leur source historique.
## D-010 — 2026-10-09 — Organisation de la documentation
- **Statut** : active, complétée par D-012 ; remplacée en partie par D-026 (chemin des fiches).
- **Décision** : trois niveaux.
- `CLAUDE.md` est chargé à chaque session et reste court.
- `docs/decisions.md` (ce journal) porte les décisions de niveau projet.
- `docs/analyses/analyse_NN.md` porte la fiche vivante de chaque analyse.
- **Pourquoi** : rien ne doit se perdre entre deux conversations, sans alourdir le contexte chargé en permanence.
- **Options écartées** :
- mettre à jour après coup les specs et plans superpowers ;
- garder le savoir projet dans la mémoire automatique de Claude, qui est locale et non partagée.
- **Conséquence** : `docs/superpowers/` est un historique de travail, pas une référence. La spec d'une nouvelle analyse s'écrit directement dans sa fiche.
## D-011 — 2026-10-09 — Disposition des graphiques : l'analyse en haut, une série par graphique dessous
- **Statut** : active. Remplace la disposition de D-007.
- **Décision** : en haut, l'analyse avec ses courbes superposées ; dessous, un graphique séparé par série temporelle, chacun avec sa propre échelle.
- **Pourquoi** : superposer tous les champs sur un seul axe écrase l'échelle, parce que les amplitudes vont de ~13 V à ~5000 mW.
- **Options écartées** : tous les champs sur un même axe, à la manière de la plateforme de monitoring (D-007), essayée puis abandonnée.
## D-012 — 2026-10-09 — Documentation : une carte et des documents chargés à la demande
- **Statut** : active. Complète D-010. Remplacée en partie par D-026 (chemins des fiches, du modèle et de la règle `.claude`).
- **Décision** :
- `CLAUDE.md` devient une **carte** de moins de 200 lignes : état et prochaine étape, index des analyses, liens, règles non négociables, essentiel du domaine.
- Le savoir métier va dans `docs/domaine/`, une note par question.
- Une règle `.claude/rules/analyses.md` se charge seule quand Claude touche `src/` ou `docs/analyses/`.
- Ce journal prend le format ADR allégé (statut, options écartées).
- Un modèle de fiche `docs/analyses/_modele.md` et un skill `nouvelle-analyse` donnent la même forme à chaque analyse.
- **Pourquoi** :
- la doc officielle de Claude Code recommande moins de 200 lignes par CLAUDE.md, car un fichier plus long coûte du contexte à chaque session et est moins bien suivi ;
- les règles limitées à certains chemins et les skills ne se chargent qu'à la demande (divulgation progressive) ;
- les options écartées évitent de reproposer ce qui a déjà été rejeté.
- **Options écartées** : un CLAUDE.md exhaustif à la manière de DocLab (1194 lignes, ~93 Ko). Il donne une très bonne vue d'ensemble, mais chaque session paie ce contexte et l'adhérence baisse.
## D-013 — 2026-10-09 — Graphiques : zoom dans le temps, ordonnée recalée sur la plage visible
- **Statut** : active.
- **Décision** : dans tous les graphiques d'analyse :
- le zoom est horizontal seulement (dans le temps, au rectangle ou à la molette) et commun à tous les graphiques ;
- après chaque zoom, l'ordonnée de chaque graphique est recalée sur les points visibles. Le script est `energy_plot.AUTOSCALE_Y_JS`, avec les ordonnées en `fixedrange` ;
- la ligne de seuil reste visible ;
- un double-clic revient à la vue complète.
- **Pourquoi** : les graphiques sont peu hauts. Avec l'échelle de l'ensemble des données, les points sortaient du cadre dès qu'on zoomait, et plotly ne recale pas l'ordonnée tout seul.
- **Options écartées** : le zoom libre en rectangle sur les deux axes, parce que l'ordonnée fixée à la main serait écrasée par le recalage automatique.
- **Conséquence** : le script utilise l'API interne de plotly.js (`_fullLayout`, `d2l`, `r2l`). Il est à revérifier si plotly change de version majeure.
## D-014 — 2026-10-09 — Tout le projet est versionné et poussé sur le dépôt de l'entreprise
- **Statut** : active.
- **Décision** : `doc/` (documentation AIMsight), `data/` (dont `data/archive/`), `architecture.drawio` et la copie du collecteur `src/__main__ (3).py` sont versionnés et poussés sur `origin` (gitea de l'entreprise). Seuls `out/`, `.venv/` et `__pycache__/` restent ignorés.
- **Pourquoi** : demande explicite de l'utilisateur. Le projet doit être complet et récupérable depuis le dépôt.
- **Conséquence** :
- `data/metadata.md` contient des identifiants techniques de station (SIM CCID, adresses IP), d'où un dépôt qui doit rester privé ;
- les stations archivées deviennent récupérables, ce qui lève la raison « irréversible » évoquée dans D-009.
## D-015 — 2026-10-12 — Panneau d'analyse : deux courbes sur un seul axe en volts
- **Statut** : active. Précise D-011 pour le panneau du haut.
- **Décision** : le panneau d'analyse ne montre que la moyenne sur 7 jours et le seuil (référence − 0,2 V), en volts, sur un seul axe, avec le fond rouge des anomalies. L'écart et la référence restent au survol.
- **Pourquoi** : les 5 tracés précédents (écart, ligne à −0,2 V, moyenne, référence, seuil, sur deux axes) montraient deux fois le même test. L'utilisateur a demandé à simplifier.
- **Options écartées** :
- l'écart seul face à −0,2 V : le plus compact, mais on ne voit plus le niveau de tension ;
- moyenne, référence et seuil (3 courbes) : la référence n'est que le seuil décalé de 0,2 V.
- **Conséquence** : le seuil est une courbe, donc `AUTOSCALE_Y_JS` le garde visible sans cas particulier.
## D-016 — 2026-10-12 — Page commune : un panneau par analyse, pour les comparer
- **Statut** : active. Précise D-011 et D-006. Remplacée en partie par D-026 (un point d'entrée par analyse, ordre des panneaux par numéro).
- **Décision** : les analyses énergétiques partagent une page, `out/<STATION>_energy.html`. Chacune y a son panneau en haut, dans l'ordre de leur numéro (02 sous 01), puis viennent les graphiques des séries temporelles. Chaque analyse garde son point d'entrée `src/analyse_NN.py` (D-006), qui lance cette page.
- **Pourquoi** : demande de l'utilisateur, pour comparer `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` à `MOVING_AVERAGE_7_DAYS_DROP` sur le même axe de temps. C'est aussi un premier pas vers la combinaison des analyses (D-005).
- **Options écartées** : une page par analyse, qui obligerait à comparer deux onglets sans zoom commun.
- **Conséquence** : `energy_plot.figure()` prend une liste de résultats. Le calcul commun des deux analyses est `energy_check._ma_drop()`.
## D-017 — 2026-10-12 — Identifiants de règle en mots complets
- **Statut** : active.
- **Décision** : l'identifiant d'une règle (champ `analysis`, titre du panneau, conclusions) s'écrit en anglais, en majuscules, avec des mots complets et sans abréviation. Les deux premières analyses sont renommées : `MA7D_DROP` devient `MOVING_AVERAGE_7_DAYS_DROP`, et `MA7D_MIDNIGHT_DROP` devient `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP`.
- **Pourquoi** : demande de l'utilisateur : avec des abréviations, on ne comprend pas ce que fait la règle. L'identifiant est cité dans chaque conclusion, il doit se lire sans la fiche.
- **Options écartées** : les sigles courts (`MA7D_DROP`), illisibles pour qui ne connaît pas le projet.
- **Conséquence** : les documents de travail de `docs/superpowers/` gardent les anciens noms (historique non maintenu).
## D-018 — 2026-10-12 — Analyses suivantes : état jour par jour, seuils physiques du matériel
- **Statut** : active. Nuance D-005 (fenêtres larges) pour les analyses d'état.
- **Décision** :
- les prochaines analyses donnent l'état de la batterie **jour par jour**, plutôt qu'une moyenne glissante sur plusieurs jours ;
- elles s'appuient sur des **seuils physiques du matériel** (fin de charge du chargeur, coude LiFePO4), valables dès le premier jour, pour détecter les problèmes dès l'installation (alimentation absente, apport insuffisant) ;
- elles se construisent en deux phases : d'abord l'état seul (phase C), puis des niveaux gradués (phase B) ;
- elles tournent sur les exports CSV horaires, sur le poste de dev. Les données brutes de la station et le collecteur embarqué viendront plus tard.
- **Pourquoi** : demande de l'utilisateur. La moyenne glissante introduit trop d'inertie, alors qu'on veut l'état directement et une détection rapide à l'installation. Or une comparaison au propre passé est impossible sans historique.
- **Options écartées** :
- la comparaison au propre passé de la station, aveugle à l'installation ;
- l'hybride (seuils absolus puis passé), trop complexe pour commencer ;
- les états du collecteur à 1 Hz, mis de côté : pas de données brutes, et un seuil sur 60 s qui ne voit pas le plateau.
- **Conséquence** : le principe « les seuils de tension absolus ne se transposent pas » vise les niveaux propres à une station, comme la position du plateau la nuit. Les seuils du matériel sont admis, à condition de vérifier que le chargeur est le même sur toutes les stations. Première analyse : 03 `DAILY_BATTERY_STATE`.
## D-019 — 2026-10-12 — Points journaliers à midi ; fin de nuit non décalée
- **Statut** : active. Précise D-011 (graphique) pour les analyses jour par jour (D-018).
- **Décision** :
- sur le graphique, les points journaliers des analyses 03 et 04 sont placés à midi UTC de leur jour, au milieu de la journée, et non à leur `t` (23:00) ;
- le calcul ne change pas : la fin de nuit du jour J reste celle du matin de J, dans l'analyse 03 comme dans la 04.
- **Pourquoi** : choix de l'utilisateur. À 23:00, le point et la barre semblaient appartenir au lendemain : le 12/04 a été lu « 13 avril ».
- **Options écartées** :
- décaler la fin de nuit d'un jour, pour qu'elle porte sur la même journée que l'état (la fin de nuit du matin de J porte le bilan de J−1). Essayé dans la 03, puis dans la 04 seule, et écarté par l'utilisateur les deux fois. Sur VERMONT, il ramenait les barres de la 04 contraires à l'état de 16 à 4 sur 28 changements d'état, au prix d'un jour de retard ;
- garder `t` sur le jour J en prenant la fin de nuit de J+1 : non causal.
- **Conséquence** : l'incohérence entre l'état et la barre reste une limite connue de l'analyse 04 (limite 6 de sa fiche).
## D-020 — 2026-10-12 — Diagnostic énergétique livré : couleur du jour (matrice 03 × 04) et manuel
- **Statut** : active. Remplace, pour le diagnostic livré, la « phase B » de l'analyse 03 et la combinaison prévue par D-005.
- **Décision** :
- le diagnostic énergétique livré ne retient que les analyses 03 (`DAILY_BATTERY_STATE`) et 04 (`DAILY_BATTERY_TREND`) ;
- elles se combinent par une matrice état × tendance en une **couleur par jour et par station** : vert (soutenable ce jour-là), orange (incertain, à surveiller), rouge (non soutenable). La matrice est tenue par l'utilisateur dans `cas-d-usage-03-04.drawio` ;
- un manuel l'explique, en deux couches : une lecture rapide pour le client final, une annexe technique pour l'ingénieur support (`docs/guide/diagnostic-energetique.md`).
- **Pourquoi** : demande de l'utilisateur. Il faut apprendre au lecteur à lire les signaux envoyés ; la couleur sert d'entrée en matière, les analyses de détail.
- **Options écartées** :
- `NO_CHARGE` × `STABLE` en orange : une coupure d'alimentation passerait du rouge (1er jour) à l'orange (jours suivants) alors qu'elle continue, contre D-004 ;
- un manuel pour un seul public (client ou support).
- **Conséquence** :
- la matrice n'est pas encore codée : le manuel décrit la cible ;
- les analyses 01 et 02 restent dans le code et sur la page HTML, mais ne font plus partie du diagnostic livré ;
- les cas inconnus (état ou tendance) ne sont pas encore traités dans la matrice, laissés de côté par l'utilisateur ;
- le destinataire du diagnostic n'est plus ouvert : le client et le support, en couches.
## D-021 — 2026-10-12 — Graphique des analyses 03 et 04 pour le site de monitoring
- **Statut** : active. Complète D-020.
- **Décision** :
- le graphique destiné au site de monitoring (Plotly) est une seule figure : le panneau de l'analyse 03 en haut, celui de l'analyse 04 dessous, sur le même axe du temps. Ce sont les panneaux de la page des analyses (D-016), sans changement ;
- `src/energy_plot.py` en écrit une page de démo (`out/<STATION>_daily.html`) et la figure en JSON (`out/<STATION>_daily.json`), que le site passe à `Plotly.newPlot` ;
- la matrice de D-020 est codée dans `src/day_color.py` (bibliothèque standard, embarquable), mais n'est pas tracée. Quand l'état ou la tendance est inconnu, la couleur l'est aussi (gris).
- **Pourquoi** : demande de l'utilisateur, qui veut intégrer le diagnostic au site (page « System Summary ») et trouve les deux panneaux plus clairs qu'une couleur par jour.
- **Options écartées** :
- une bande d'une case par jour (couleur de la matrice, flèche de tendance) au-dessus de `BusVoltage` horaire : essayée, jugée « pas claire » par l'utilisateur ;
- superposer les deux panneaux en double axe (03 à gauche en V, 04 à droite en ΔV), dans un 3e panneau : essayé, mauvaise lisibilité selon l'utilisateur. Le zéro de l'axe de droite tombe vers 13,6 V, les tirets de la zone morte s'y lisent comme des seuils de tension, et les grandes barres cachent la fin de nuit. Deux superpositions sur un seul axe en V n'ont pas été essayées : la tendance en marqueurs ▲ ● ▼ sur la courbe de fin de nuit, ou chaque barre tracée de la fin de nuit de J−1 à celle de J ;
- teinter le fond de la courbe `BusVoltage`, jour par jour : la teinte se lit moins bien que des cases, et elle gêne la lecture de la courbe ;
- pour un jour inconnu, reprendre la couleur de la colonne de l'état quand elle est unique (`FULL_CHARGE` sans veille serait vert) : l'utilisateur préfère le gris, les cas inconnus restant à traiter (D-020).
- **Conséquence** :
- la couleur du jour est calculée mais n'apparaît sur aucun graphique ;
- le calcul des analyses 03 et 04 (`battery_state.py`, `battery_trend.py`) n'importe plus rien des analyses 01 et 02 : il se livre seul ;
- le format d'intégration côté site (JSON, fragment HTML ou backend Python) reste à choisir avec l'équipe du site.
## D-022 — 2026-10-12 — Maquettes de page en HTML ; Figma seulement sur demande
- **Statut** : active.
- **Décision** : les maquettes de page (ex. « System Summary » du site de monitoring) sont des pages HTML générées à partir des données réelles, dans `maquettes/`. Un fichier Figma n'est produit que sur demande (designer, passation à l'équipe du site), à partir d'une maquette stable.
- **Pourquoi** : choix de l'utilisateur, sur recommandation. Le HTML s'itère plus vite (rendu et vérification en local), garde les données réelles et vivantes (calcul par `src/`), permet l'interaction (survol traçable, zoom), utilise la technologie du livrable (HTML Plotly) et se versionne.
- **Options écartées** : Figma comme référence. Chaque modification y passe par l'API Plugin, et le graphique n'y est qu'une image vectorielle figée, sans survol ni zoom. Un premier fichier, produit puis non maintenu, reste dans les brouillons Figma de l'utilisateur : https://www.figma.com/design/S16eZ7PoAAutFJWcyqAHSm.
- **Conséquence** :
- les maquettes sont rangées en deux blocs : `maquettes/user/` (côté client) et `maquettes/support/` (côté support AIMsight). Chaque design a son script, ou directement son HTML s'il n'a pas besoin de données ;
- `python3 maquettes/user/energy.py [début] [fin]` écrit `out/maquette_user_energy.html` (ignoré par git, comme les autres pages générées) et l'ouvre. Il calcule lui-même la figure de D-021 (plotly, bascule seule sur `.venv`) ;
- la maquette « Energy » place en haut de la page System Summary une section « Diagnostic », un rectangle repliable par notification (ici Energy, avec Green, Orange ou Red pour le dernier jour de la fenêtre). Déplié : une phrase de très haut niveau, puis une échelle de batterie (niveau de ce matin, la fin de nuit, placé par la table OCV du collecteur dans des zones Off < 10 %, Low < 30 %, OK < 90 %, Full ; pas de % affiché, car sur le plateau la tension en dit peu ; la tension reste au survol), la tendance face à la veille en mots simples (better / same / worse), et deux dérouleurs : l'historique complet (figure de D-021) et « Guide », la partie 1 du manuel (lecture rapide, pour le client) rendue depuis le Markdown à chaque génération (marked.js). La partie 2, pour le support, ira côté support ;
- les jours Orange et Red, un bouton « Activate energy save mode » propose le remède attendu (veille profonde entre les mesures, `docs/domaine/comment-se-comporte-la-batterie.md`). C'est une action de la plateforme, déclenchée par le client : le diagnostic reste en lecture seule. Dans la maquette, le bouton n'envoie rien ;
- le bloc n'utilise pas le graphique de 48 h de D-024 (`focus_jour.py`) : l'utilisateur préfère des faits chiffrés. Un tableau des faits de J−1 et de J, côte à côte, puis le jour J avec ses variations chiffrées, ont été essayés, puis remplacés par l'échelle et la tendance : une tension ne dit rien à un non-spécialiste, et il n'a pas besoin de savoir que la tendance vient de la fin de nuit ;
- une première version, avec une bande d'une case par jour au-dessus de `BusVoltage` (option écartée par D-021), a été remplacée.
- points ouverts de la maquette « Energy » :
- le guide est la partie 1 du manuel, en français, alors que la page est en anglais (D-023) : il faudra une version anglaise ;
- le repère de l'échelle de batterie n'a pas de compensation IR : la nuit, la tension mesurée est ~0,14 V sous la tension à vide, donc le repère est un peu bas. Le collecteur, lui, compense avec le courant (0,34 Ω) ;
- le bouton « Activate energy save mode » reste à construire par l'équipe du site ;
- le jour affiché est le dernier jour de la fenêtre ; un jour en cours n'est pas encore signalé comme provisoire côté client.
## D-023 — 2026-10-12 — Site de monitoring en anglais, figure des analyses 03 et 04 comprise
- **Statut** : active. Complète D-021 et D-022.
- **Décision** : tout ce qui est destiné au site de monitoring est en anglais : la maquette System Summary et la figure des analyses 03 et 04 (`out/<STATION>_daily.json`), avec ses titres, légendes, axes et survols.
- **Pourquoi** : demande de l'utilisateur. Le site AIMsight est en anglais.
- **Conséquence** :
- les panneaux 03 et 04 étant partagés (D-021), ils sont aussi en anglais sur la page des analyses (`out/<STATION>_energy.html`), dont le reste (analyses 01 et 02, séries) reste en français ;
- le code, ses commentaires, les fiches et le manuel restent en français (convention du projet). Les identifiants (`FULL_CHARGE`, `DAILY_BATTERY_STATE`…) ne changent pas.
## D-024 — 2026-10-12 — Focus sur un jour : J et la veille seulement
- **Statut** : active. Complète D-020 et D-021.
- **Décision** :
- pour comprendre la couleur d'un jour (ex. « Red » le 27/09), on ne montre que le jour J et la veille J−1 : ce sont les seuls jours que lisent les analyses 03 et 04 pour cette couleur ;
- `python3 src/focus_jour.py JJ.MM[.AAAA]` affiche un résumé texte traçable (couleur, case de la matrice, état et condition de chaque jour, maximum, fin de nuit et son heure, heures mesurées, tendance et ce qui l'a décidée). Il écrit aussi un graphique de 48 h (`out/<STATION>_focus_<AAAA-MM-JJ>.html` + `.json`) : `BusVoltage` horaire, bandes grises sans mesure, seuils 14,0 et 12,8 V, maximum et fin de nuit de chaque jour, flèche de fin de nuit J−1 → J colorée par tendance ;
- la sélection des données (`day_color.focus(series, jour)`) est en bibliothèque standard, livrable à la plateforme ; le graphique est en anglais (D-023).
- **Pourquoi** : demande de l'utilisateur. Le client qui voit une couleur veut voir les données qui l'expliquent, sans tout l'historique.
- **Conséquence** :
- l'analyse 03 gagne le fait `night_end_h` (heure de la fin de nuit), sans changer les autres ;
- un jour en cours, ou le dernier jour d'un export, est signalé « provisional » : la couleur peut encore changer jusqu'à minuit UTC.
## D-025 — 2026-10-12 — Maquette support « Home » : section Status et lien vers la vue client
- **Statut** : active. Complète D-022.
- **Décision** :
- côté support, la maquette reprend la page d'accueil du site (une vignette par station : nom, dernière tension, courbe) et place en haut une section « Status » : une notification par station dont le dernier jour de la fenêtre est Orange ou Red (`src/day_color.py`), la plus grave d'abord. Green ne notifie rien ;
- une notification donne la couleur, la station, le domaine (Energy), le jour, la phrase de la vue client, et un lien « Open <station> » vers la vue client de la station (son menu principal, `out/maquette_user_energy.html`). La vignette de la station mène au même endroit ;
- `python3 maquettes/support/home.py [début] [fin]` écrit `out/maquette_support_home.html` et l'ouvre (bibliothèque standard, SVG en ligne, sans plotly).
- **Pourquoi** : demande de l'utilisateur. Le support doit voir l'ensemble des systèmes, et voir une alerte quand le client la voit ; le plus simple est de le notifier et de l'envoyer sur la vue client. Maquette validée telle quelle par l'utilisateur.
- **Conséquence** :
- la section Status remplace, en haut de page, le panneau « Notifications » du site ;
- seule VERMONT a des données (`data/`) : les autres vignettes, noms repris du site, restent vides et grisées (pas de données synthétiques) ;
- la vue client doit être générée avec les mêmes dates (`maquettes/user/energy.py`) ; le script le rappelle si elle manque.
## D-026 — 2026-10-12 — Structure par domaine ; analyses désignées par leur règle
- **Statut** : active. Remplace D-006 ; remplace en partie D-010 (chemin des fiches), D-012 (chemins des fiches, du modèle et de la règle `.claude`) et D-016 (un point d'entrée par analyse).
- **Décision** :
- **Chaque domaine a son sous-dossier dans chaque couche** : `src/energy/` et `docs/energy/` (analyses, domaine, guide, matrice). Le code commun est dans `src/common/` (`stations.py` : chargement des CSV ; `page.py` : bascule `.venv`, ouverture, `AUTOSCALE_Y_JS`). `maquettes/` reste découpé par public (D-022). Les notes communes restent dans `docs/domaine/`.
- **Les analyses ne sont plus numérotées** : chacune est désignée par sa règle et sa fiche porte son nom (`docs/energy/analyses/daily_battery_state.md`). Correspondance : 01 = `MOVING_AVERAGE_7_DAYS_DROP`, 02 = `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP`, 03 = `DAILY_BATTERY_STATE`, 04 = `DAILY_BATTERY_TREND`. Les entrées du journal antérieures à celle-ci gardent les numéros.
- **Deux scripts d'analyse pour Energy** : `src/energy/final.py` (`daily.py` jusqu'au 2026-10-13), les analyses livrées (état et tendance, D-020 et D-021), qui écrit `out/<STATION>_daily.html` et `.json` ; `src/energy/all_analyses.py`, les quatre analyses ensemble pour comparer (D-016), qui écrit `out/<STATION>_energy.html`. `src/energy/focus_jour.py` reste l'outil de focus (D-024). Le résumé texte d'`energy_check.py` (`out/<STATION>_energy.json`) est supprimé.
- **La documentation AIMsight d'origine passe de `doc/` à `docs/aimsight/`**, avec la copie du collecteur (`collecteur_system_info.py`, ex-`src/__main__ (3).py`). La roadmap perd le suffixe « (2) ». `cas-d-usage-03-04.drawio` devient `docs/energy/matrice-etat-tendance.drawio`. Les contenus ne changent pas.
- Le modèle de fiche passe dans le skill `nouvelle-analyse` (`modele-fiche.md`).
- **Pourquoi** : demande de l'utilisateur. Encapsuler Energy pour que le domaine suivant (D-002) se range à côté. Ranger les fichiers dispersés (racine, `doc/` à côté de `docs/`, code commun mêlé aux analyses). Energy a convergé vers les analyses livrées : un numéro d'ordre de création n'aide plus, le nom de la règle suffit.
- **Options écartées** :
- une tranche verticale `energy/{src,docs,maquettes}` à la racine : elle mêle des couches aux destinataires différents (station, humains, équipe du site), et la maquette support couvre tous les domaines ;
- ne réorganiser que le code : la documentation Energy resterait mêlée au reste ;
- garder un script `analyse_NN.py` par analyse (D-006) : trois des quatre ne faisaient que relancer le premier ;
- une numérotation par domaine : elle ne dit pas plus que le nom de la règle.
- **Conséquence** :
- les anciens chemins restent dans `docs/superpowers/` et dans le texte des entrées antérieures du journal (historique non réécrit) ;
- le code de calcul s'embarque en copiant `src/energy/` sans `final.py`, `all_analyses.py` ni `focus_jour.py`, qui demandent plotly.
## D-027 — 2026-10-12 — Couche d'agents de diagnostic côté serveur (exploratoire)
- **Statut** : active, exploratoire (rapport `docs/agents/rapport-exploratoire.md`, rien n'est construit). Remplace en partie D-003 : le refus du LLM ne vaut plus que pour la couche déterministe.
- **Décision** :
- à côté de la couche déterministe (inchangée : sans LLM, bibliothèque standard, embarquable), une **couche d'agents LLM** (Claude, via l'API d'Anthropic) tourne **côté serveur**. Elle lit les faits des règles et les données, avec deux missions : les **anomalies inconnues** (qu'aucune règle ne décrit) et les **cas limites des règles** (UNKNOWN, accoutumance, faux positifs) ;
- **l'agent annote, il ne réécrit pas** : il ne modifie jamais le verdict déterministe (couleur du jour). Son avis est une notification séparée, marquée « agent » ;
- il notifie le **client** et le **support** ;
- **harnais maison** : script Python, API Messages et *Tool Runner* du SDK `anthropic`, outils typés en lecture seule (sauf `notify`), base SQL jamais exposée. Un agent est un **dossier déclaratif** (instructions, pointeurs vers la connaissance de `docs/`, outils). Le **découpage des agents reste ouvert** ;
- **démarrage simple, par étapes** : (1) pilote manuel Energy sur l'historique de VERMONT (CSV), (2) SQL, cron et notifications au support seul, (3) ouverture au client, (4) élargissement. Chaque étape décide si la suivante est nécessaire.
- **Pourquoi** : demande de l'utilisateur. Les scripts sont justes « dans la majorité des cas » (D-005) ; l'interprétation d'un agent doit élargir la palette des problèmes captés. Les docs AIMsight prévoyaient cette couche (§18 et §21 du contexte support). L'utilisateur accepte d'envoyer les données à une API externe. Avec moins de 50 stations, le coût reste modéré (~0,30 $ par session, à mesurer). Les données sont accessibles par requêtes SQL.
- **Options écartées** :
- Managed Agents (Anthropic héberge la boucle, la planification et la mémoire) : service en bêta, et la base SQL serait à exposer ou à servir par un *worker* auto-hébergé. Reste la cible si l'orchestration maison devient pénible, car la définition en dossier est portable ;
- Claude Agent SDK : un harnais de codage, dont le Bash donne une surface d'action large et peu auditable pour un agent qui notifie des clients ;
- un modèle open-weights hébergé chez AIMsight : inutile, l'API externe étant acceptée ;
- un LLM sur la station : trop lourd pour l'embarqué ;
- un agent qui corrige lui-même la couleur du jour : on perdrait la reproductibilité du verdict ;
- SQL libre, Bash, accès web, RAG : non auditables ou inutiles à cette taille.
- **Conséquence** :
- pas de LLM dans `src/<domaine>/` : le code d'agent vivra à part (emplacement proposé : `agents/`) ;
- les règles non négociables (traçabilité, vocabulaire, lecture seule, pas de seuil inventé) s'appliquent aux agents ;
- les règles détaillées proposées (journal, contrôles de `notify`, politique de destinataire, affichage) sont des **pistes à revoir étape par étape**, pas des décisions (annexe A du rapport) ;
- prérequis de l'étape 1 : un compte et une clé API Anthropic.
## D-028 — 2026-10-12 — CLAUDE.md : carte complète du dépôt, état courant, lecture ciblée
- **Statut** : active. Précise D-012.
- **Décision** :
- `CLAUDE.md` nomme chaque dossier et chaque document du dépôt, avec sa taille en lignes, pour que l'agent sache ce qui existe sans l'ouvrir ;
- il dit comment lire sans saturer le contexte : plan d'un fichier long puis la seule section utile, index de ce journal, CSV par script, dossiers à ne pas lire ;
- « État et prochaine étape » donne l'état courant, pas un historique daté ;
- ce qui est déjà dans `.claude/rules/analyses.md` (contrat `run(series)`, disposition des graphiques) n'y est plus répété.
- **Pourquoi** : demande de l'utilisateur. Le CLAUDE.md doit révéler tout le projet sans forcer l'agent à le lire. L'historique daté grossissait à chaque étape alors qu'il est déjà dans `git log` et ce journal ; la doc AIMsight (~3 300 lignes) était à « lire avant de concevoir » sans dire comment la lire par section.
- **Options écartées** : un index des sections de chaque gros document dans `CLAUDE.md` : `grep -n '^#'` le donne à la demande, sans coût permanent.
## D-029 — 2026-10-13 — Données rangées par station
- **Statut** : active. Précise D-009 (emplacement du jeu de travail).
- **Décision** : les CSV d'une station vont dans `data/<STATION>/` ; VERMONT passe de `data/` à `data/VERMONT/`, défaut de tous les scripts. `metadata.md`, `d.md` et `archive/` restent dans `data/`.
- **Pourquoi** : demande de l'utilisateur, qui va ajouter de nouvelles données sans vouloir les mêler au jeu de travail.
- **Options écartées** : un chargement récursif de `data/` : il mêlerait `archive/` et les nouvelles données au jeu de travail.
- **Conséquence** : une nouvelle station s'analyse en passant son dossier en argument (`python3 src/energy/final.py data/<STATION>`).
## D-030 — 2026-10-13 — Nouveaux domaines Storage et Cellular ; procédure `nouveau-domaine` ; contrat de notification
- **Statut** : active. Complète D-026 (structure par domaine) et D-025 (notifications support) ; précise D-009 (jeu de travail par domaine).
- **Décision** :
- deux nouveaux domaines, rangés comme Energy : `storage` (espace disque) et `cellular` (signal 4G : niveau radio, enregistrement, lien). Chacun a `src/<domaine>/` et une note de départ, `docs/<domaine>/domaine/point-de-depart.md`. Les analyses attendent l'exploration des données ;
- leur jeu de travail est **WEISSHORN** : tout `data/WEISSHORN/`, sans restriction de dates (tous les champs de la caméra ; l'export du 2026-10-13 couvre 10 jours, un export plus long le remplacera) : VERMONT (D-009) n'a ni métrique de disque ni métrique de modem ;
- la procédure pour ajouter un domaine, donc une notification, est le skill `nouveau-domaine` (sept étapes, de la réception des données à la livraison). Il renvoie vers `nouvelle-analyse` pour chaque analyse ;
- **contrat de notification** : chaque domaine livré expose `day_color.run(series)`, un point par jour avec `facts.color` (`GREEN` / `ORANGE` / `RED` / `None`), et une `HEADLINE` en anglais par couleur notifiée ;
- le passage des maquettes à une liste de domaines se fait au premier nouveau domaine livré, pas avant.
- **Pourquoi** : demande de l'utilisateur, qui veut le même travail qu'Energy pour d'autres points d'attention, et pouvoir ajouter vite de nouvelles notifications. Le collecteur mesure déjà l'espace disque et le signal du modem.
- **Options écartées** : la procédure dans un document de `docs/` (Claude ne le trouve pas seul) ou dans `nouvelle-analyse` (deux échelles mêlées) ; le nom `network` (VPN et envois relèvent de « Communication ») ; le passage multi-domaines dès maintenant (une liste à un seul élément, contrat non vérifié).
- **Conséquence** :
- `HEADLINE` d'Energy quittera `maquettes/support/home.py` pour `src/energy/day_color.py` lors du passage multi-domaines ;
- le chargeur commun ne lit que des métriques numériques : il faudra l'adapter si l'on retient les métriques texte du modem (`link`, `registration`), qui sont des listes d'échantillons par heure ;
- les copies identiques et les `Zone.Identifier` de WEISSHORN sont supprimés, et `*:Zone.Identifier` est ignoré par git.
## D-031 — 2026-10-13 — Cellular : deux analyses d'état jour par jour, seuils absolus publiés ; métriques texte chargées
- **Statut** : active. Applique D-030 (domaine Cellular) ; reprend D-018 (état jour par jour, sans historique) pour la 4G.
- **Décision** :
- deux analyses d'état, sans verdict (`anomaly = None`, l'état dans `facts.state`), écrites l'une après l'autre avant les cas de l'expert : `DAILY_LINK_STATE` (envois reçus avec `link = up`) et `DAILY_SIGNAL_STATE` (médianes du jour du RSRP et du RSRQ) ;
- pour le signal, des **seuils absolus** : la grille « RF Quality » attribuée à Quectel par KORE Wireless (RSRP −80 / −90 / −100 dBm, RSRQ −10 / −15 / −20 dB), seule grille publiée trouvée avec une attribution ; ni la doc AIMsight ni la norme n'en donnent ;
- `common.stations` charge les métriques texte comme la liste des échantillons de l'heure ; les pages ne tracent que des séries choisies, jamais `SIM_CCID` ni `ip`.
- **Pourquoi** : choix de l'utilisateur. Les cas de l'expert viendront en cours de route ; l'export de WEISSHORN (10 jours) est trop court pour comparer la station à son passé.
- **Options écartées** : la comparaison au propre passé (aveugle à l'installation, historique court) ; attendre l'expert pour choisir la référence ; le minimum du jour (décrochages de nuit) ; RSSI et BER (plafond, redondance).
- **Conséquence** : la grille vient d'un autre modem et se présente comme indicative : à faire confirmer par l'expert. Le RSRQ de WEISSHORN est à 0,25 dB du plancher de `GOOD`. La couleur du jour (étape 6 de `nouveau-domaine`) reste à décider.
## D-032 — 2026-10-13 — NORDEND, deuxième jeu de travail de Cellular ; `link` facultatif
- **Statut** : active. Complète D-030 (jeu de travail par domaine) et D-031 (analyses Cellular).
- **Décision** :
- le jeu de travail de `cellular` devient **WEISSHORN et NORDEND** (`data/NORDEND/`, export du 2026-10-13, 109 jours, du 26/06 au 13/10) ; la page de comparaison tourne sur les deux par défaut ;
- `DAILY_LINK_STATE` accepte un export sans `link` (version plus ancienne du collecteur) : les envois se comptent sur `last_sync`, et ce qui dépend de `link` vaut `None` ;
- la grille de `DAILY_SIGNAL_STATE` reste telle quelle en attendant l'expert, bien qu'elle classe tous les jours de NORDEND en `CELL_EDGE`.
- **Pourquoi** : demande de l'utilisateur, qui voulait une station à la connexion moins bonne, sur une plage plus large. NORDEND a 11 coupures de la liaison (1 à 23 h), WEISSHORN aucune.
- **Options écartées** : une page ou une analyse propre aux exports sans `link` (deux codes pour une même question) ; déduire l'état du lien des champs du modem (une lecture ratée n'est pas un lien coupé) ; changer la grille sur une seule station.
- **Conséquence** : sans `link`, NORDEND ne montre jamais `DOWN` ni de message perdu. Le début d'historique (jusqu'au jour du premier envoi reçu) passe en UNKNOWN. Les métriques de stockage de NORDEND n'ont pas les noms de WEISSHORN (note de départ de `storage`).
## D-033 — 2026-10-13 — Notes brutes de l'expert et `data/archive/` retirées du dépôt
- **Statut** : active. Modifie D-029 (`metadata.md`, `d.md` et `archive/` ne restent plus dans `data/`) et D-009 (les stations mises de côté ne sont plus dans le dépôt).
- **Décision** : `data/metadata.md`, `data/d.md` et les 4 CSV de `data/archive/` (FLORIDA, JUNGFRAU, MISSISSIPPI, WILDSTRUBEL, `BusVoltage` seule) sont supprimés. Les documents renvoient désormais à leurs résumés : `docs/energy/domaine/cas-annotes-par-l-expert.md` pour les diagnostics, les notes de départ pour les instantanés.
- **Pourquoi** : choix de l'utilisateur.
- **Options écartées** : les garder (refusé par l'utilisateur).
- **Conséquence** : les fichiers restent dans l'historique git, identifiants compris. Le dépôt doit toujours rester privé (D-014) : les CSV de WEISSHORN et NORDEND contiennent aussi `SIM_CCID` et des adresses IP. Les specs et plans de `docs/superpowers/` (historique non maintenu) citent encore ces fichiers.