Document the project: decisions log, analysis sheet, domain notes

- CLAUDE.md becomes a short map: status and next step, analyses index,
  documentation map, working rules.
- docs/decisions.md: ADR-style project decision log (D-001..D-014).
- docs/analyses/: living sheet per analysis (analyse_01) and template.
- docs/domaine/: domain knowledge, one note per question.
- .claude/rules/analyses.md: path-scoped rule loaded on src/ and
  docs/analyses/; .claude/skills/nouvelle-analyse: new-analysis workflow.
- README.md: human entry point.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
maximeandClaude Opus 5.5 committed 2026-10-09 23:29:42 +02:00
1 parent 0b950199b8
commit 8992bda17e
12 files changed
+588 -49

No files matched your search

+68 -49
View File
@@ -2,69 +2,86 @@
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**.
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 : phase de conception. Pas de code. Langage : **Python**. Relancer `/init` quand du code existe.
## É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).
- **Prochaine étape** : choisir l'analyse 02 parmi les pistes de la fiche 01 (classement des trous, taux de jours à charge complète, perte secteur rapide, autonomie), puis combiner les analyses.
## Analyses
| N° | Nom | Question | Statut | Fiche |
|---|---|---|---|---|
| 01 | `MA7D_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` |
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` et l'ouvre dans le navigateur (via `explorer.exe` sous WSL). Il bascule seul sur `.venv` si plotly manque.
- `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é.
- `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).
- **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/` : séries réelles et diagnostics experts (voir plus bas).
- `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` (bibliothèque standard uniquement, embarquable) et `src/energy_plot.py` (plotly, poste de dev).
- `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.
## Décisions prises (2026-10-09)
## 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 » (« pourquoi D-300-A a sauté ? ») viendra ensuite, sur le même socle.
- **Premier cas d'usage : santé énergétique des stations** (tension batterie, interruptions de mesure ; stations solaires et sur secteur). Ici, le trou de données *est* l'anomalie. L'interprétation des déplacements viendra ensuite.
- **Données** : des CSV simulent la future base de données ; Parquet/HDF5 viendront ensuite. Les schémas CSV historiques varient.
- **Pas de données synthétiques** : ne pas générer de CSV simulés ni de générateur de scénarios (refus explicite de l'utilisateur).
- **Pas de LLM** : détection, classement et explication par méthodes analytiques et règles. L'explication est générée à partir des faits calculés.
- **Embarqué** : le code doit pouvoir tourner sur la station, qui fonctionne souvent sur batterie et panneau solaire. Il faut donc un calcul léger et des dépendances minimales.
- **Ouvert** : architecture (à définir plus tard, ne pas la figer ici), destinataire du diagnostic (client final ou ingénieur support), unités des métriques système.
- **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.
- Une analyse seule conclut au plus `consistent with`.
- **Livrable** : un graphique HTML par station. En haut, l'analyse (courbes superposées) ; 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).
- **Ouvert** : architecture (à définir plus tard, ne pas la figer ici), destinataire du diagnostic (client final ou ingénieur support).
## Données (`data/`)
## L'essentiel du domaine (détail : `docs/domaine/`)
- Un CSV par station et par métrique : `<STATION>_<Metric>_<début> to <fin>.csv`. Colonnes `,time_utc,metric` (index sans nom, horodatage UTC, pas d'une heure). Une valeur `metric` vide = pas de mesure.
- Diagnostics experts (vérité de référence) dans `data/metadata.md` (avec le contexte matériel et un instantané de l'état système, unités `[unknown]`) et dans `data/d.md`.
- Cas annotés (tension batterie `BusVoltage`) :
| Station | Alimentation | Diagnostic expert | Signature observée |
|---|---|---|---|
| JUNGFRAU | solaire | sain | aucun trou, max quotidien ~14,1–14,2 V, jours nuageux sans montée diurne |
| VERMONT | solaire | interruptions nocturnes (déficit) | max quotidien plafonne ~13,2–13,5 V dès le 20/09, coupures nocturnes dès le 27/09 vers ~12,2 V |
| WILDSTRUBEL | solaire | décharge profonde sous 12 V (UVLO désactivé ?), coupure ~12 j, puis interruptions nocturnes | max quotidien en baisse dès le 04/09, 11,53 V le 09/09 puis 298 h sans mesure |
| FLORIDA | secteur | sain, sans interruption | ~14,2–14,4 V sans cycle jour/nuit (une baisse ponctuelle à 13,0 V le 10/07). Quelques trous courts à tension normale : ce ne sont pas des coupures d'alimentation |
| MISSISSIPPI | secteur | coupures secteur : la batterie sert d'UPS puis le système se déconnecte | chute 14,2 → ~13,1 V, lente baisse, coude vers 12,5 V, puis décrochage ; nombreuses coupures déc. 2025–juin 2026, lectures jusqu'à 10,3 V |
- Pièges :
- Des valeurs vides **en fin de fichier** peuvent être un retard de synchronisation (`last_sync`), pas une coupure (WILDSTRUBEL, MISSISSIPPI le 09/10).
- Des trous **simultanés sur plusieurs stations** (FLORIDA et MISSISSIPPI le 22/07 à 14:00 et le 22/08 à 17:00) pointent plutôt vers une cause commune hors station.
- Un trou avec une tension normale avant et après n'est pas un problème d'énergie.
## Domaine : l'essentiel
Énergie (metadata + manuel de la station) :
- Batterie LiFePO4 de 12,8 V nominal (environ 7 ou 21 Ah). Panneau solaire 12 V, ~100 W conseillé. Entrée max 26 V.
- Sur secteur, la batterie reste connectée et sert d'UPS.
- Après une décharge profonde (< 12 V), la station reste éteinte jusqu'à ~12,6 V avant de redémarrer. L'UVLO doit couper avant la décharge profonde.
- Mesure quasi statique typiquement toutes les 15 min. Remède attendu en cas de déficit : réactiver le mode veille profonde (sleep) entre les mesures. Le « Continuous mode » (LED allumées) augmente la consommation.
Colonnes CSV des déplacements (cas d'usage suivant), préfixées par la cible (ex. `target_06_rch`) :
- `rch` / `rcv` : déplacement corrigé du mouvement caméra [mm], le signal principal.
- `x` / `y` : position brute dans l'image [px].
- `rx` / `ry` : déplacement relatif avant correction caméra. **Ce n'est pas** `x - x0`.
- `error` : erreur de reconnaissance de la cible, **pas** une incertitude. Seuil par défaut 0.7.
- `camera_pan|tilt|rotation` [deg], `camera_scale`, `camera_sigma0` (résidu du fit du réseau de références).
- `inlier_{ch}`, `reproj_err_{ch}` : contribution et résidu de chaque référence.
- Sharpness, FWHM, Dominance, Peak Intensity, Flux, SNR : **uniquement dans l'export HDF5**.
Causes à départager pour une anomalie de déplacement : mouvement réel de l'ouvrage, mouvement de la caméra, instabilité de la compensation (cas Barcelone), dégradation locale d'une cible, parallaxe / modèle inadapté.
- **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é.
- **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
@@ -75,12 +92,14 @@ Causes à départager pour une anomalie de déplacement : mouvement réel de l'o
- 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 tests de régression.
- 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é dans l'environnement de dev ; la bibliothèque standard suffit pour explorer les CSV (`csv`, `datetime.fromisoformat`).
- `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