D-022: page mockups are HTML built from real data, in maquettes/user/ (client) and maquettes/support/; Figma only on request. maquettes/user/energy.py renders the System Summary page with a Diagnostic section: an Energy box with the day's color, a one-line headline, a battery scale (zones from the collector's LiFePO4 OCV table, no percentage shown), the trend against the day before, an "Activate energy save mode" button on orange and red days (mockup only, sends nothing), and two collapsibles: the full history (D-021 figure) and the guide (part 1 of the manual, rendered from Markdown). D-023: everything meant for the monitoring site is in English, including the titles, legends, axes and hovers of the 03/04 panels. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
14 KiB
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Ce fichier est une carte, chargée à chaque session : il doit rester court (< 200 lignes). Le détail est dans docs/ et se lit quand on en a besoin.
Projet
Agent de diagnostic proactif pour AIMsight, un système de surveillance optique de déplacements : une caméra suit des cibles (prismes, réflecteurs) sur un ouvrage, et le mouvement de la caméra est compensé grâce à des cibles de référence. L'agent analyse les séries temporelles avec des méthodes analytiques (pas de LLM), détecte les anomalies et explique chacune d'elles (preuves calculées + ce qui reste non établi) avant que le client ne pose la question. Cible d'exécution idéale : le système embarqué de la station. Langage : Python.
État et prochaine étape
- 2026-10-09 : l'analyse 01 est en place sur VERMONT et produit un graphique HTML. C'est un prototype expérimental, sans tests automatisés.
- Point ouvert de l'analyse 01 : l'accoutumance. Après plus de 30 jours de déficit, l'anomalie peut disparaître (voir sa fiche).
- 2026-10-12 : analyse 02 (
MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP, suggestion d'un collègue) en place, en panneau sous la 01 pour comparer. Elle est bien moins bruitée (pire cas sain −0,04 V contre −0,16 V), mais plus tardive sur VERMONT : 1 h avant la première coupure, contre ~2,7 jours pour la 01. - 2026-10-12, changement d'échelle (D-018) : les analyses suivantes donnent l'état de la batterie jour par jour, avec des seuils physiques du matériel, pour être utilisables dès l'installation. Phase C (état seul), puis phase B (niveaux gradués).
- 2026-10-12 : analyse 03
DAILY_BATTERY_STATEen place (phase C, état seul). - 2026-10-12 : analyse 04
DAILY_BATTERY_TRENDen place (tendance markovienne : chaque jour face à la veille, mieux / stable / pire). - 2026-10-12, recentrage (D-020) : le diagnostic énergétique livré ne retient que les analyses 03 et 04, combinées par la matrice état × tendance de
cas-d-usage-03-04.drawioen une couleur par jour (vert / orange / rouge). Le manueldocs/guide/diagnostic-energetique.md(brouillon) l'explique au client et au support. - 2026-10-12 (D-021) : graphique pour le site de monitoring (Plotly) : une seule figure, panneau 03 en haut et 04 dessous, écrite en page de démo et en JSON. La matrice est codée (
src/day_color.py, jours inconnus en gris), mais pas tracée (la bande de couleurs a été écartée). - Prochaine étape : mise en forme du manuel avec le plugin Interactive Docs (dans une autre conversation) ; choisir avec l'équipe du site le format d'intégration du graphique.
Analyses
| N° | Nom | Question | Statut | Fiche |
|---|---|---|---|---|
| 01 | MOVING_AVERAGE_7_DAYS_DROP |
La tension moyenne sur 7 jours décroche-t-elle de son propre passé récent (> 0,2 V) ? | prototype en place | docs/analyses/analyse_01.md |
| 02 | MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP |
Même question, sur la seule mesure de 00:00 UTC de chaque jour | prototype en place | docs/analyses/analyse_02.md |
| 03 | DAILY_BATTERY_STATE |
Chaque jour : pleine charge, charge partielle (incertain), sous le plateau ou aucune charge ? | prototype en place | docs/analyses/analyse_03.md |
| 04 | DAILY_BATTERY_TREND |
Chaque jour, face à la veille : mieux, stable ou pire (changement d'état, sinon écart de fin de nuit) ? | prototype en place | docs/analyses/analyse_04.md |
Pour créer une analyse : skill nouvelle-analyse (.claude/skills/nouvelle-analyse/).
Commandes
python3 src/analyse_01.py: point d'entrée de l'analyse 01. Il analysedata/, écritout/<STATION>_energy.html(panneaux des analyses 01 à 04, D-016) etout/<STATION>_daily.html+.json(analyses 03 et 04 pour le site, D-021), puis les ouvre dans le navigateur (viaexplorer.exesous WSL). Il bascule seul sur.venvsi plotly manque.python3 src/analyse_02.py: point d'entrée de l'analyse 02 ; il lance la même page.python3 src/analyse_03.py: point d'entrée de l'analyse 03 ; il lance la même page.python3 src/analyse_04.py: point d'entrée de l'analyse 04 ; il lance la même page.python3 maquettes/user/energy.py [début] [fin]: maquette client « Energy » (page System Summary, section Diagnostic, D-022), écrite dansout/maquette_user_energy.htmlet ouverte.python3 src/energy_check.py data/: résumé texte +out/<STATION>_energy.json(out/est ignoré par git)..venv/bin/python src/energy_plot.py data/: graphique seul (plotly.js est chargé depuis le CDN).
Documentation (à lire à la demande)
docs/decisions.md: journal des décisions projet, au format ADR allégé (statut, décision, pourquoi, options écartées, conséquence). Le lire avant de changer d'orientation ou de reproposer une option : elle a peut-être déjà été écartée.docs/analyses/analyse_NN.md: fiche vivante de chaque analyse (principe, constantes et sources, résultats, limites, options écartées, historique). Modèle :docs/analyses/_modele.md.docs/domaine/: le savoir métier, une note par question.ce-que-mesure-la-station.md: format CSV, métriques et unités, consommation mesurée mais pas l'apport.comment-se-comporte-la-batterie.md: LiFePO4, plateau et coude, table OCV, redémarrage à 12,6 V, capacité.tensions-selon-l-etat-de-la-batterie.md: tensions et pentes en charge, pleine charge et décharge (VERMONT, collecteur, chimie).pieges-des-donnees.md: trou ≠ coupure, signatures d'une coupure, seuils absolus, cycle jour/nuit.cas-annotes-par-l-expert.md: diagnostics experts des 5 stations.colonnes-des-deplacements.md: colonnes des déplacements (cas d'usage suivant).
docs/guide/diagnostic-energetique.md: manuel du diagnostic énergétique, pour le client (partie 1) et le support (partie 2). À tenir à jour avec la matrice et les fiches 03 et 04.- Règle de travail :
- une décision projet prise en conversation donne une entrée dans
docs/decisions.md; - toute modification d'une analyse met à jour sa fiche dans le même changement ;
- un savoir métier nouveau va dans
docs/domaine/; - un changement de cap met à jour « État et prochaine étape » ci-dessus.
- une décision projet prise en conversation donne une entrée dans
.claude/rules/analyses.mdse charge seul quand Claude touchesrc/oudocs/analyses/.docs/superpowers/: documents de travail superpowers (specs, plans). C'est un historique, non maintenu après coup, et ce n'est pas une référence. La spec d'une nouvelle analyse s'écrit directement dans sa fichedocs/analyses/analyse_NN.md; le plan peut rester dansdocs/superpowers/plans/.
Fichiers
README.md: point d'entrée pour un humain (lancer l'analyse, où trouver quoi). Tout le projet est versionné, saufout/,.venv/et__pycache__/(D-014).doc/: documentation AIMsight, à lire avant de concevoir. Ne pas re-demander à l'utilisateur ce qui y figure.AIMsight_reference_quality_event_explainer_roadmap (2).md: référence qui fait autorité. Elle couvre la couche diagnostique commune, l'explainer d'événements, les classifications (§4.3) et l'API indépendante de l'estimateur (§10). Le doc de contexte la cite sans le suffixe « (2) ».AIMsight_agentic_support_project_context.md: extension support. Contenu : chaîne de dépendance (§4), domaines dont la santé système (§5.1), règles épistémiques (§10), familles d'hypothèses (§12), format de sortie (§14-15), cas de régression (§16-17), cas d'usage (§23).- Les deux docs prévoient un LLM/agent pour la synthèse : ne pas suivre ce point, le projet est 100 % analytique.
AIMsight FAQ.pdfetAIMsight Test Manual.pdf(ce dernier est en réalité le manuel de la station) : définitions des signaux et des colonnes CSV, alimentation, schedules. Pour les lire :pdftotext -layout "doc/<fichier>.pdf" -.
data/: jeu de travail = VERMONT seule, le seul dataset complet (les 7 métriques système, telles qu'extraites de la plateforme) + diagnostics experts (metadata.md,d.md). Les analyses tournent uniquement sur ce jeu.data/archive/:BusVoltageseule des autres stations (incomplètes), mises de côté le 2026-10-09. Non analysées ; ne pas les réintroduire sans demande.src/analyse_NN.py: point d'entrée de chaque analyse. Code partagé :src/energy_check.py(analyses 01 et 02, bibliothèque standard uniquement, embarquable),src/battery_state.py(analyse 03, idem),src/battery_trend.py(analyse 04, idem),src/day_color.py(matrice 03 × 04, couleur du jour, idem) etsrc/energy_plot.py(plotly, poste de dev).src/__main__ (3).py: copie de référence du collecteursystem_infoembarqué (INA219, table OCV LiFePO4, compensation IR 0,34 Ω). Source des unités. Ne pas modifier.architecture.drawio: schéma d'architecture tenu par l'utilisateur. Ne pas le modifier sans demande.maquettes/: maquettes de page en HTML, sur données réelles (D-022), en deux blocs :user/(client) etsupport/. Un script par design, ou directement le HTML. Figma seulement sur demande.
Principes (raisons, statuts et options écartées : docs/decisions.md)
- Point d'entrée du POC : scan proactif d'un export. L'agent détecte les événements, les classe et explique chacun. Le mode « question de support » viendra ensuite, sur le même socle.
- Premier cas d'usage : santé énergétique des stations. Ici, le trou de données est l'anomalie. L'interprétation des déplacements viendra ensuite.
- Pas de LLM, pas de données synthétiques (ni CSV simulés, ni générateur de scénarios : refus explicite de l'utilisateur). Le code d'analyse est embarquable : bibliothèque standard, calcul léger.
- Anomalie énergétique = régime non soutenable (l'apport ne couvre pas la consommation), pas une batterie basse. Une station débranchée avec une batterie pleine est déjà en anomalie.
- Analyses combinées : chaque analyse est une preuve imparfaite, juste « dans la majorité des cas » ; la combinaison fait le diagnostic. Préférer des fenêtres larges (plusieurs jours, multiples de 24 h).
- Contrat commun :
run(series) -> {analysis, rule, points: [{t, value, anomaly, facts}]}. Calcul causal (le point t n'utilise que les données ≤ t).anomaly = Nonesignifie UNKNOWN (exception : analyses 03 en phase C et 04, oùNone= pas de verdict ; l'UNKNOWN est dansfacts.stateoufacts.trend). - Une analyse seule conclut au plus
consistent with.
- Contrat commun :
- Livrable : un graphique HTML par station. En haut, les analyses, un panneau chacune (courbes superposées, D-016) ; dessous, un graphique par série temporelle. Zoom dans le temps seulement, avec l'ordonnée recalée sur la plage visible (D-011, D-013).
- Destinataire du diagnostic : le client final et l'ingénieur support, en couches (D-020).
- Ouvert : architecture (à définir plus tard, ne pas la figer ici).
L'essentiel du domaine (détail : docs/domaine/)
- Données : un CSV par station et par métrique,
<STATION>_<Metric>_<début> to <fin>.csv, colonnes,time_utc,metric, moyennes horaires en UTC. Une valeur vide signifie qu'il n'y a pas de mesure. - Unités :
BusVoltage[V],BusCurrent[mA],Power[mW],ShuntVoltage[mV]. Ces trois dernières sont une seule mesure : la consommation. L'apport (panneau ou secteur) n'est pas mesuré. - Batterie LiFePO4 de 12,8 V :
- entre 30 et 90 % de charge, la tension de nuit reste plate ; elle ne chute qu'au coude (~12,8 V, puis ~12,5 V) ;
- sous 12 V, la station s'éteint et ne redémarre que vers ~12,6 V ;
- ≥ 14,0 V dans la journée signale une charge complète.
- Les seuils de tension absolus ne se transposent pas d'une station à l'autre : comparer la station à son propre passé. Exception : les seuils du matériel (fin de charge ~14,0 V, coude 12,8 V), admis pour les analyses d'état (D-018).
- Un trou n'est pas forcément une coupure : retard de synchronisation en fin de fichier, début d'historique, cause commune si plusieurs stations ont un trou en même temps.
Règles non négociables
- Chaque conclusion est traçable. Elle cite les faits calculés et la règle qui l'a produite. Aucun chiffre ni seuil sans source.
- Ne pas confondre « pas de donnée visible » et « station arrêtée » : acquisition, transmission, ingestion et affichage sont des couches distinctes.
- Ne rien construire sur
inlierbinaire : RANSAC sera remplacé par un estimateur pondéré. Utiliser poids continus,N_eff, résidus, influence. sigma0seul et le nombre de références ne sont jamais des critères suffisants.- Ne pas confondre qualité image d'une cible et qualité du réseau de références, ni petit résidu et transformation bien contrainte.
- Ne pas confondre mouvement en mode commun et mouvement structurel, ni références cohérentes et références physiquement fixes.
- Séparer fait observé, fait dérivé, contexte opérateur, hypothèse et inconnu. Pas de pseudo-probabilités ; vocabulaire :
confirmed/strongly supported/consistent with/possible/insufficient evidence/not observed. - Pas de règle spécifique à un site : les cas résolus deviennent des cas de régression.
- Lecture seule : aucune action sur les stations, la configuration ou le retraitement.
Environnement
pandasn'est pas installé ; la bibliothèque standard suffit pour explorer les CSV (csv,datetime.fromisoformat)..venv/(Python 3.14) ne contient que plotly, pour le poste de dev. Le code d'analyse reste en bibliothèque standard.- Prototype expérimental : pas de tests automatisés (D-008). Vérifier les changements à la main en lançant
python3 src/analyse_01.pysur VERMONT.
Conventions
- Échanges et documents projet en français ; la documentation AIMsight est en anglais (garder ses termes techniques).