Files
Support-Agent/docs/decisions.md
T
2026-10-13 12:42:54 +02:00

47 KiB
Raw Blame History

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 » 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.
  • 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.

D-034 — 2026-10-13 — Storage : niveau du jour et jours avant saturation ; seuils arbitraires ; WEISSHORN seul

  • Statut : active. Applique D-030 (domaine Storage) ; déroge à la règle « aucun seuil sans source » pour des seuils provisoires.
  • Décision :
    • deux analyses sans verdict (anomaly = None), codées avant les réponses de l'expert : DAILY_STORAGE_STATE (espace libre en fin de jour, en % de l'espace utilisable : OK, LOW, CRITICAL) et DAYS_UNTIL_STORAGE_FULL (espace libre ÷ médiane des consommations journalières sur 7 jours) ;
    • planchers de DAILY_STORAGE_STATE arbitraires, pour commencer : 20 % et 10 % libres. Ils sont marqués comme tels dans la fiche et dans le code ;
    • le jeu de travail reste WEISSHORN seul : NORDEND n'a pas les mesures de /data (*_disk_1k-blk, plat pendant 104 jours). Les analyses ne lisent que data_storage_* ;
    • les questions à l'expert (disque plein, purge, root, seuils, cas) restent en suspens dans docs/storage/domaine/questions-pour-l-expert.md.
  • Pourquoi : choix de l'utilisateur, qui veut notifier un disque bientôt plein et estimer le temps restant, sans attendre l'expert. Le remplissage de WEISSHORN est assez régulier (28,2 MiB par jour, à l'heure près) pour une première estimation.
  • Options écartées : ajouter NORDEND au jeu de travail (pas de données de /data) ; attendre l'expert avant de coder ; une régression linéaire ou une différence sur 7 jours pour le rythme (sensibles à une purge, fiche days_until_storage_full).
  • Conséquence : la couleur du jour (étape 6 de nouveau-domaine) reste à décider ; LOW et CRITICAL ne sont jamais observés sur WEISSHORN (57 % libre au 13/10, saturation estimée au 06/02/2027).

D-035 — 2026-10-13 — Storage : couleur du jour, matrice état × horizon ; seuils de jours arbitraires

  • Statut : active. Applique le contrat de notification de D-030 au domaine Storage ; complète D-034.
  • Décision :
    • src/storage/day_color.py : la couleur du jour se lit dans une matrice état × horizon, tenue par l'utilisateur dans docs/storage/matrice-etat-horizon.drawio et recopiée dans MATRIX, comme pour Energy (D-020). L'état vient de DAILY_STORAGE_STATE (OK, LOW, CRITICAL) ; l'horizon de DAYS_UNTIL_STORAGE_FULL : WITHIN_14_DAYS, WITHIN_60_DAYS, BEYOND_60_DAYS (60 jours ou plus, ou le disque ne se remplit pas), ou inconnu ;
    • la matrice actuelle revient à prendre la pire des deux analyses. Orange ou Red peut venir d'une seule ; Green demande les deux, sinon le jour est gris (inconnu) ;
    • seuils de jours arbitraires (14 et 60 jours), choix de l'utilisateur pour commencer, comme les planchers de D-034 ;
    • HEADLINE : Red « The station is about to run out of storage space. », Orange « The station's storage space is running low. ».
  • Pourquoi : choix de l'utilisateur, une matrice dessinée comme celle d'Energy. Les deux analyses voient des risques différents : le niveau voit un bloc ponctuel que l'estimation ne prévoit pas (1,3 GiB écrits en deux heures le 31/08 sur WEISSHORN) ; l'estimation voit un disque qui fond, même à un niveau encore confortable.
  • Options écartées : le gris dès qu'une analyse manque, comme Energy (il cacherait un disque CRITICAL dont l'estimation n'est pas encore possible) ; le Green sur le seul niveau (il ignorerait un remplissage rapide pas encore mesuré).
  • Conséquence : sur WEISSHORN, 52 jours Green et 14 gris (début d'historique jusqu'au 22/08, moins de 4 rythmes dans la fenêtre). Au rythme actuel, la station passerait Orange vers le 09/12 et Red vers le 17/01 (CRITICAL). La livraison (étape 7 : figure du site, maquettes, guide, passage des maquettes à une liste de domaines) se fera dans une autre conversation.

D-036 — 2026-10-13 — Pas de domaine Températures pour l'instant

  • Statut : active. Le domaine candidat « surchauffe » (sensor_*_deg_c) n'est pas créé (D-030).
  • Décision :
    • pas de domaine ni d'analyse de température pour l'instant ; l'exploration de VERMONT, WEISSHORN et NORDEND est rangée dans docs/domaine/temperatures-de-la-station.md, avec ses pistes et les questions pour le spécialiste ;
    • la température reste une preuve d'appoint pour Energy (signature d'une coupure, docs/domaine/pieges-des-donnees.md), à combiner avec la tension, pas codée.
  • Pourquoi : choix de l'utilisateur, sur proposition. Aucun épisode de chaleur dans les données (maximum 62,7 °C, NORDEND, le 13/08), aucun seuil du matériel ni de la documentation AIMsight, aucun cas de l'expert : un verdict serait vert tous les jours, ou rouge sur un seuil inventé.
  • Options écartées : un domaine surchauffe comparant la station à son propre passé (il signalerait les jours d'été chauds, pas un défaut) ; l'amplitude du jour comme indice d'ensoleillement pour Energy (corrélation avec la tension maximale du jour de −0,03 à 0,32) ; la température au retour d'un trou comme preuve seule d'une coupure (le trou commun du 19/08 revient aussi ~7 °C sous l'habitude).
  • Conséquence : à reprendre avec les seuils thermiques du matériel, un premier incident annoté, ou les données d'hiver (froid et charge de la batterie LiFePO4).