D-025: the support side gets the site's home page (one tile per station: name, last voltage, curve) with a Status section on top. It holds one notification per station whose last day of the window is Orange or Red (src/day_color.py), the most serious first; Green notifies nothing. Each notification, like the station tile, links to the station's client view (out/maquette_user_energy.html). maquettes/support/home.py writes out/maquette_support_home.html with the standard library only (inline SVG, no plotly). Only VERMONT has data; the other tiles keep the site's names and stay empty. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
129 lines
15 KiB
Markdown
129 lines
15 KiB
Markdown
# 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_STATE` en place (phase C, état seul).
|
||
- **2026-10-12** : analyse 04 `DAILY_BATTERY_TREND` en 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.drawio` en une couleur par jour (vert / orange / rouge). Le manuel `docs/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).
|
||
- **2026-10-12 (D-022, D-023)** : maquettes du site en HTML sur données réelles (`maquettes/user/` pour le client, `maquettes/support/` pour le support ; Figma seulement sur demande). Maquette client « Energy » en place : section Diagnostic de la page System Summary. Tout ce qui va au site est en anglais, figure 03 × 04 comprise.
|
||
- **2026-10-12 (D-024)** : focus sur un jour, J et la veille seulement : `src/focus_jour.py` (résumé des faits + graphique de 48 h), sélection des données dans `day_color.focus()`.
|
||
- **2026-10-12 (D-025)** : maquette support « Home » en place : page d'accueil (toutes les stations) avec une section Status, une notification par station Orange ou Red, et un lien vers la vue client.
|
||
- **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 ; maquettes : poursuivre « Energy » côté client pas à pas, puis le côté support pas à pas (points ouverts dans D-022).
|
||
|
||
## 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 analyse `data/`, écrit `out/<STATION>_energy.html` (panneaux des analyses 01 à 04, D-016) et `out/<STATION>_daily.html` + `.json` (analyses 03 et 04 pour le site, D-021), puis les ouvre dans le navigateur (via `explorer.exe` sous WSL). Il bascule seul sur `.venv` si 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 dans `out/maquette_user_energy.html` et ouverte.
|
||
- `python3 maquettes/support/home.py [début] [fin]` : maquette support « Home » (toutes les stations, section Status, D-025), écrite dans `out/maquette_support_home.html` et ouverte.
|
||
- `python3 src/energy_check.py data/` : résumé texte + `out/<STATION>_energy.json` (`out/` est ignoré par git).
|
||
- `python3 src/focus_jour.py 27.09` : focus sur un jour et sa veille (D-024). Il affiche les faits de la couleur et écrit `out/<STATION>_focus_<AAAA-MM-JJ>.html` + `.json`, puis l'ouvre.
|
||
- `.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.
|
||
- `.claude/rules/analyses.md` se charge seul quand Claude touche `src/` ou `docs/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 fiche `docs/analyses/analyse_NN.md` ; le plan peut rester dans `docs/superpowers/plans/`.
|
||
|
||
## Fichiers
|
||
|
||
- `README.md` : point d'entrée pour un humain (lancer l'analyse, où trouver quoi). Tout le projet est versionné, sauf `out/`, `.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.pdf` et `AIMsight 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/` : `BusVoltage` seule 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, focus J−1 / J, idem) et `src/energy_plot.py` (plotly, poste de dev). `src/focus_jour.py` : focus sur un jour (plotly).
|
||
- `src/__main__ (3).py` : copie de référence du collecteur `system_info` embarqué (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) et `support/`. 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 = None` signifie UNKNOWN (exception : analyses 03 en phase C et 04, où `None` = pas de verdict ; l'UNKNOWN est dans `facts.state` ou `facts.trend`).
|
||
- Une analyse seule conclut au plus `consistent with`.
|
||
- **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 `inlier` binaire : RANSAC sera remplacé par un estimateur pondéré. Utiliser poids continus, `N_eff`, résidus, influence.
|
||
- `sigma0` seul 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
|
||
|
||
- `pandas` n'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.py` sur VERMONT.
|
||
|
||
## Conventions
|
||
|
||
- Échanges et documents projet en français ; la documentation AIMsight est en anglais (garder ses termes techniques).
|