diff --git a/.claude/rules/analyses.md b/.claude/rules/analyses.md index 470d39f..90a94e8 100644 --- a/.claude/rules/analyses.md +++ b/.claude/rules/analyses.md @@ -1,12 +1,12 @@ --- paths: - "src/**" - - "docs/analyses/**" + - "docs/*/analyses/**" --- # Travailler sur une analyse -- **Avant de modifier** une analyse, lire sa fiche `docs/analyses/analyse_NN.md`. En particulier : +- **Avant de modifier** une analyse, lire sa fiche `docs//analyses/.md` (ex. `docs/energy/analyses/daily_battery_state.md`). En particulier : - le principe ; - les constantes et leurs sources ; - les limites connues ; @@ -14,16 +14,16 @@ paths: - **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`) ; + - `anomaly = None` signifie UNKNOWN (exception : `DAILY_BATTERY_STATE` en phase C et `DAILY_BATTERY_TREND`, où `None` = pas de verdict ; l'UNKNOWN est dans `facts.state` ou `facts.trend`) ; - une analyse seule conclut au plus `consistent with`. -- **Code de calcul** : bibliothèque standard uniquement, car il doit tourner sur la station. Plotly ne sert qu'aux graphiques, sur le poste de dev (`.venv`). +- **Code de calcul** (`src//`) : bibliothèque standard uniquement et aucun import de `src/common/`, car il doit tourner sur la station. Plotly ne sert qu'aux graphiques, sur le poste de dev (`.venv`). Le chargement des CSV est dans `common.stations`. - **Constantes** : chacune a sa source, en commentaire dans le code et dans le tableau de la fiche. Aucun seuil sans source. - **Graphique** : - - en haut, l'analyse avec ses courbes superposées ; dessous, un graphique par série temporelle (D-011). Des analyses à comparer partagent une page, un panneau chacune (D-016) ; - - zoom horizontal seulement, avec l'ordonnée recalée sur la plage visible (`post_script=energy_plot.AUTOSCALE_Y_JS`, ordonnées en `fixedrange`, D-013). + - en haut, l'analyse avec ses courbes superposées ; dessous, un graphique par série temporelle (D-011). Des analyses à comparer partagent une page, un panneau chacune (D-016) : pour Energy, `src/energy/all_analyses.py` ; + - zoom horizontal seulement, avec l'ordonnée recalée sur la plage visible (`post_script=common.page.AUTOSCALE_Y_JS`, ordonnées en `fixedrange`, D-013). - **Après modification** : - mettre à jour la fiche dans le même changement (résultats, limites, historique) ; - si c'est une décision projet, ajouter une entrée dans `docs/decisions.md` ; - - si c'est un savoir métier nouveau, l'ajouter dans `docs/domaine/`. -- **Vérifier à la main** avec `python3 src/analyse_NN.py` sur VERMONT (`data/`). Pas de tests automatisés en phase prototype (D-008). + - si c'est un savoir métier nouveau, l'ajouter dans `docs/domaine/` (commun) ou `docs//domaine/`. +- **Vérifier à la main** sur VERMONT (`data/`) : pour Energy, `python3 src/energy/all_analyses.py`, et `python3 src/energy/daily.py` si l'analyse est livrée. Pas de tests automatisés en phase prototype (D-008). - **Nouvelle analyse** : utiliser le skill `nouvelle-analyse`. diff --git a/.claude/skills/nouvelle-analyse/SKILL.md b/.claude/skills/nouvelle-analyse/SKILL.md index 5916f62..e6c2cc0 100644 --- a/.claude/skills/nouvelle-analyse/SKILL.md +++ b/.claude/skills/nouvelle-analyse/SKILL.md @@ -1,55 +1,52 @@ --- name: nouvelle-analyse -description: Créer une nouvelle analyse numérotée (analyse_NN) dans le projet de diagnostic AIMsight — script, fiche, index, journal. À utiliser dès que l'utilisateur veut ajouter, concevoir ou prototyper une nouvelle analyse des séries temporelles d'une station. +description: Créer une nouvelle analyse dans le projet de diagnostic AIMsight — règle, fiche, code dans son domaine, panneau de comparaison, index, journal. À utiliser dès que l'utilisateur veut ajouter, concevoir ou prototyper une nouvelle analyse des séries temporelles d'une station. --- # Créer une nouvelle analyse ## 1. Situer l'analyse -- Prendre le numéro suivant `NN` : voir le tableau « Analyses » de `CLAUDE.md` et `docs/analyses/`. +- **Domaine** : Energy (`src/energy/`, `docs/energy/`) ou un nouveau domaine, qui reçoit alors son propre `src//` et `docs//` (D-026). Le demander à l'utilisateur en cas de doute. +- **Nom de la règle** : en anglais, en majuscules, **en mots complets sans abréviation** (ex. `MOVING_AVERAGE_7_DAYS_DROP`, D-017). Les analyses ne sont pas numérotées : le nom de la règle les désigne (D-026). - Lire, sans tout charger : - - les « Pistes » et les « Limites connues » des fiches existantes. La nouvelle analyse en couvre souvent une ; + - les « Pistes » et les « Limites connues » des fiches du domaine (`docs//analyses/`). La nouvelle analyse en couvre souvent une ; - `docs/decisions.md`, en particulier les options écartées ; - - la note de `docs/domaine/` qui concerne la question posée. -- Si la conception demande des choix, en discuter avec l'utilisateur. Avec superpowers (brainstorming), **la spec s'écrit directement dans la fiche** `docs/analyses/analyse_NN.md`, pas dans `docs/superpowers/specs/` (D-010). + - la note de `docs/domaine/` ou de `docs//domaine/` qui concerne la question posée. +- Si la conception demande des choix, en discuter avec l'utilisateur. Avec superpowers (brainstorming), **la spec s'écrit directement dans la fiche**, pas dans `docs/superpowers/specs/` (D-010). ## 2. Écrire la fiche -- Copier `docs/analyses/_modele.md` vers `docs/analyses/analyse_NN.md` et remplir : +- Copier `modele-fiche.md` (à côté de ce fichier) vers `docs//analyses/.md` (ex. `daily_battery_state.md`) et remplir : - la question posée ; - le principe et le calcul exact ; - les constantes **avec leur source** ; - les options écartées. - Statut : « en conception ». -- Nom de la règle : en anglais, majuscules, **mots complets sans abréviation** (ex. `MOVING_AVERAGE_7_DAYS_DROP`, D-017). ## 3. Écrire le code - Le calcul respecte le contrat commun : `run(series) -> {analysis, rule, points: [{t, value, anomaly, facts}]}`. - Il est causal. - - Il utilise uniquement la bibliothèque standard. + - Il utilise uniquement la bibliothèque standard, sans importer `src/common/` : il doit pouvoir s'embarquer seul. - `value` est exprimé dans une unité physique, sans pseudo-probabilité. - Une analyse seule conclut au plus `consistent with`. -- Réutiliser `src/energy_check.py` (`load_stations`, grille horaire, traitement des `NaN`) plutôt que de le recopier. Extraire du code partagé seulement quand une deuxième analyse en a vraiment besoin. -- Point d'entrée `src/analyse_NN.py`, sur le modèle de `src/analyse_01.py` : - - il s'exécute sur `data/` par défaut ; - - il bascule sur `.venv` si plotly manque ; - - il écrit le graphique dans `out/` et l'ouvre dans le navigateur. -- Graphique (D-011) : en haut, l'analyse avec ses courbes superposées ; dessous, un graphique par série temporelle. Écrire le HTML avec `post_script=energy_plot.AUTOSCALE_Y_JS` et des ordonnées en `fixedrange`, pour que l'ordonnée se recale à chaque zoom. +- Le module va dans `src//`. Les séries arrivent par `common.stations.load_stations`. Extraire du code partagé seulement quand une deuxième analyse en a vraiment besoin. +- **Pas de point d'entrée par analyse** : ajouter le panneau de l'analyse à la page de comparaison du domaine (pour Energy, `figure()` et `main()` de `src/energy/all_analyses.py`). Si l'analyse devient livrée, elle rejoint aussi la page livrée (pour Energy, `src/energy/daily.py`). +- Graphique (D-011) : en haut, l'analyse avec ses courbes superposées ; dessous, un graphique par série temporelle. Écrire le HTML avec `post_script=common.page.AUTOSCALE_Y_JS` et des ordonnées en `fixedrange`, pour que l'ordonnée se recale à chaque zoom. - Pas de tests automatisés en phase prototype (D-008). ## 4. Vérifier -- Lancer `python3 src/analyse_NN.py` sur VERMONT. -- Comparer les résultats au diagnostic expert (`docs/domaine/cas-annotes-par-l-expert.md`). +- Lancer la page de comparaison du domaine sur VERMONT (pour Energy, `python3 src/energy/all_analyses.py`). +- Comparer les résultats au diagnostic expert (`docs/energy/domaine/cas-annotes-par-l-expert.md`). - Reporter les dates et valeurs observées dans la section « Résultats » de la fiche. ## 5. Documenter - Fiche : statut « prototype en place », résultats, limites, historique. - `CLAUDE.md` : - - ajouter une ligne au tableau « Analyses » et la commande dans « Commandes » ; + - ajouter une ligne au tableau des analyses du domaine ; - mettre à jour « État et prochaine étape ». -- `docs/decisions.md` : une entrée **seulement** si une décision de niveau projet a été prise (nouveau principe, changement de cap). Les choix propres à l'analyse restent dans sa fiche. -- Un savoir métier découvert en chemin va dans `docs/domaine/`. +- `docs/decisions.md` : une entrée **seulement** si une décision de niveau projet a été prise (nouveau principe, changement de cap, nouveau domaine). Les choix propres à l'analyse restent dans sa fiche. +- Un savoir métier découvert en chemin va dans `docs/domaine/` (commun) ou `docs//domaine/`. diff --git a/docs/analyses/_modele.md b/.claude/skills/nouvelle-analyse/modele-fiche.md similarity index 70% rename from docs/analyses/_modele.md rename to .claude/skills/nouvelle-analyse/modele-fiche.md index bae501c..c5768c3 100644 --- a/docs/analyses/_modele.md +++ b/.claude/skills/nouvelle-analyse/modele-fiche.md @@ -1,8 +1,8 @@ -# Analyse NN — `NOM_DE_LA_REGLE` : titre court +# `NOM_DE_LA_REGLE` : titre court -- **Statut** : idée | en conception | prototype en place | abandonnée (date). -- **Script** : `python3 src/analyse_NN.py [CSV ou dossiers]` (défaut : `data/`). Il écrit `out/_.html` et l'ouvre dans le navigateur. -- **Code** : les modules utilisés ; le calcul est en bibliothèque standard uniquement. +- **Statut** : idée | en conception | prototype en place | livrée | comparaison seulement | abandonnée (date). +- **Script** : la page qui montre l'analyse. Pour Energy : son panneau dans `python3 src/energy/all_analyses.py [CSV ou dossiers]` (défaut : `data/`), et dans `python3 src/energy/daily.py` si elle est livrée. La page est écrite dans `out/` et ouverte dans le navigateur. +- **Code** : les modules utilisés, dans `src//` ; le calcul est en bibliothèque standard uniquement. ## Question posée @@ -27,7 +27,7 @@ Préciser ce qui est affiché en plus : seuils, bandes, contenu du survol. ## Résultats sur VERMONT (jeu de travail) -Dates et valeurs observées, comparées au diagnostic expert (`docs/domaine/cas-annotes-par-l-expert.md`). +Dates et valeurs observées, comparées au diagnostic expert (`docs/energy/domaine/cas-annotes-par-l-expert.md`). ## Options écartées diff --git a/CLAUDE.md b/CLAUDE.md index 7f00760..70dc66f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,74 +10,74 @@ Agent de diagnostic proactif pour **AIMsight**, un système de surveillance opti ## É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-09** : `MOVING_AVERAGE_7_DAYS_DROP` est en place sur VERMONT et produit un graphique HTML. C'est un prototype expérimental, sans tests automatisés. +- **Point ouvert de `MOVING_AVERAGE_7_DAYS_DROP`** : l'accoutumance. Après plus de 30 jours de déficit, l'anomalie peut disparaître (voir sa fiche). +- **2026-10-12** : `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` (suggestion d'un collègue) en place, en panneau sous la précédente 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. - **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** : `DAILY_BATTERY_STATE` en place (phase C, état seul). +- **2026-10-12** : `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 `DAILY_BATTERY_STATE` et `DAILY_BATTERY_TREND`, combinées par la matrice état × tendance de `docs/energy/matrice-etat-tendance.drawio` en une couleur par jour (vert / orange / rouge). Le manuel `docs/energy/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, l'état en haut et la tendance dessous, écrite en page de démo et en JSON. La matrice est codée (`src/energy/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 état × tendance comprise. +- **2026-10-12 (D-024)** : focus sur un jour, J et la veille seulement : `src/energy/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. +- **2026-10-12 (D-026)** : projet rangé par domaine (`src/energy/`, `docs/energy/`, code commun dans `src/common/`, documentation AIMsight dans `docs/aimsight/`). Les analyses ne sont plus numérotées : chacune est désignée par sa règle. Deux scripts Energy : `daily.py` (analyses livrées) et `all_analyses.py` (comparaison). - **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 +## Analyses (domaine Energy) -| 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` | +| Règle | Question | Statut | Fiche | +|---|---|---|---| +| `DAILY_BATTERY_STATE` | Chaque jour : pleine charge, charge partielle (incertain), sous le plateau ou aucune charge ? | livrée (prototype, D-020) | `docs/energy/analyses/daily_battery_state.md` | +| `DAILY_BATTERY_TREND` | Chaque jour, face à la veille : mieux, stable ou pire (changement d'état, sinon écart de fin de nuit) ? | livrée (prototype, D-020) | `docs/energy/analyses/daily_battery_trend.md` | +| `MOVING_AVERAGE_7_DAYS_DROP` | La tension moyenne sur 7 jours décroche-t-elle de son propre passé récent (> 0,2 V) ? | comparaison seulement | `docs/energy/analyses/moving_average_7_days_drop.md` | +| `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` | Même question, sur la seule mesure de 00:00 UTC de chaque jour | comparaison seulement | `docs/energy/analyses/moving_average_7_days_midnight_utc_drop.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/_energy.html` (panneaux des analyses 01 à 04, D-016) et `out/_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 src/energy/daily.py [données]` : analyses livrées (`DAILY_BATTERY_STATE`, `DAILY_BATTERY_TREND`). Il écrit `out/_daily.html` + `.json` (figure pour le site, D-021) et les ouvre dans le navigateur (via `explorer.exe` sous WSL). Défaut : `data/`. Il bascule seul sur `.venv` si plotly manque, comme tous les scripts plotly. +- `python3 src/energy/all_analyses.py [données]` : les quatre analyses ensemble pour comparer (D-016), un panneau chacune, puis un graphique par série. Il écrit `out/_energy.html` et l'ouvre. +- `python3 src/energy/focus_jour.py 27.09` : focus sur un jour et sa veille (D-024). Il affiche les faits de la couleur et écrit `out/_focus_.html` + `.json`, puis l'ouvre. - `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/_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/_focus_.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. +- `docs//analyses/.md` : fiche vivante de chaque analyse (principe, constantes et sources, résultats, limites, options écartées, historique). Modèle : `.claude/skills/nouvelle-analyse/modele-fiche.md`. +- `docs/domaine/` : le savoir métier commun, une note par question. - `ce-que-mesure-la-station.md` : format CSV, métriques et unités, consommation mesurée mais pas l'apport. + - `pieges-des-donnees.md` : trou ≠ coupure, signatures d'une coupure, seuils absolus, cycle jour/nuit. + - `colonnes-des-deplacements.md` : colonnes des déplacements (cas d'usage suivant). +- `docs/energy/domaine/` : le savoir métier Energy. - `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. +- `docs/energy/guide/diagnostic-energetique.md` : manuel du diagnostic énergétique, pour le client (partie 1) et le support (partie 2). À tenir à jour avec la matrice (`docs/energy/matrice-etat-tendance.drawio`) et les fiches `DAILY_BATTERY_STATE` et `DAILY_BATTERY_TREND`. - **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 savoir métier nouveau va dans `docs/domaine/` (commun) ou `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/`. +- `.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/.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) ». +- `docs/aimsight/` : documentation AIMsight d'origine, à lire avant de concevoir. Ne pas re-demander à l'utilisateur ce qui y figure. Contenus non modifiés. + - `AIMsight_reference_quality_event_explainer_roadmap.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). - `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/.pdf" -`. + - `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 "docs/aimsight/.pdf" -`. + - `collecteur_system_info.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. - `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. +- `src/` : un sous-dossier par domaine, plus le code commun (D-026). + - `src/common/` : `stations.py` (chargement des CSV, trous de mesure ; bibliothèque standard) et `page.py` (poste de dev : bascule `.venv`, ouverture dans le navigateur, `AUTOSCALE_Y_JS`). + - `src/energy/` : calcul embarquable, en bibliothèque standard et sans import de `common/` : `moving_average.py`, `battery_state.py`, `battery_trend.py` et `day_color.py` (matrice, couleur du jour, focus J−1 / J). Scripts plotly du poste de dev : `daily.py`, `all_analyses.py` et `focus_jour.py`. - `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. @@ -88,7 +88,7 @@ Pour créer une analyse : skill `nouvelle-analyse` (`.claude/skills/nouvelle-ana - **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`). + - 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 : `DAILY_BATTERY_STATE` en phase C et `DAILY_BATTERY_TREND`, 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). @@ -121,7 +121,7 @@ Pour créer une analyse : skill `nouvelle-analyse` (`.claude/skills/nouvelle-ana - `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. +- Prototype expérimental : **pas de tests automatisés** (D-008). Vérifier les changements à la main en lançant `python3 src/energy/all_analyses.py` (et `daily.py` pour le livré) sur VERMONT. ## Conventions diff --git a/README.md b/README.md index 4f6b7ab..b27a710 100644 --- a/README.md +++ b/README.md @@ -5,16 +5,14 @@ Agent de diagnostic **100 % analytique (sans LLM)** pour les stations AIMsight. ## Lancer l'analyse ```bash -python3 src/analyse_01.py +python3 src/energy/daily.py ``` -Le script analyse `data/` (station VERMONT) et ouvre deux pages dans le navigateur : -- `out/VERMONT_daily.html` : l'état et la tendance de la batterie jour par jour (analyses 03 et 04), destinés au site de monitoring ; sa figure Plotly est aussi dans `out/VERMONT_daily.json` ; -- `out/VERMONT_energy.html` : le détail de toutes les analyses. +Le script analyse `data/` (station VERMONT) et ouvre dans le navigateur `out/VERMONT_daily.html`, l'état et la tendance de la batterie jour par jour : ce sont les analyses livrées, destinées au site de monitoring. La figure Plotly est aussi écrite dans `out/VERMONT_daily.json`. -Pour comprendre la couleur d'un jour, en ne regardant que ce jour et la veille : `python3 src/focus_jour.py 27.09`. +Pour comparer les quatre analyses Energy sur une même page (`out/VERMONT_energy.html`) : `python3 src/energy/all_analyses.py`. Pour comprendre la couleur d'un jour, en ne regardant que ce jour et la veille : `python3 src/energy/focus_jour.py 27.09`. -Le graphique se lit ainsi : +La page de comparaison se lit ainsi : - **en haut**, l'analyse ; - **dessous**, une courbe par mesure de la station ; - **zoom** : dans le temps, au rectangle ou à la molette ; double-clic pour revenir à la vue complète. @@ -27,13 +25,13 @@ Plotly est installé dans `.venv/`, et le script y bascule seul. Pour recréer c |---|---| | Vue d'ensemble, règles du projet, commandes | `CLAUDE.md` | | Pourquoi le projet est comme il est (décisions, options écartées) | `docs/decisions.md` | -| Lire le diagnostic énergétique (manuel client et support) | `docs/guide/diagnostic-energetique.md` | -| Ce que fait chaque analyse, ses seuils et ses limites | `docs/analyses/analyse_NN.md` | -| Savoir métier (mesures, batterie, pièges des données, cas experts) | `docs/domaine/` | -| Documentation AIMsight d'origine | `doc/` | +| Lire le diagnostic énergétique (manuel client et support) | `docs/energy/guide/diagnostic-energetique.md` | +| Ce que fait chaque analyse, ses seuils et ses limites | `docs/energy/analyses/.md` | +| Savoir métier (mesures, batterie, pièges des données, cas experts) | `docs/domaine/` (commun), `docs/energy/domaine/` | +| Documentation AIMsight d'origine | `docs/aimsight/` | | Données de travail (VERMONT) et diagnostics experts | `data/` | | Maquettes du site, côté client (`user/`) et support (`support/`) ; ex. `python3 maquettes/user/energy.py`, `python3 maquettes/support/home.py` | `maquettes/` | ## État -Prototype expérimental, sans tests automatisés. Quatre analyses sont en place : `MOVING_AVERAGE_7_DAYS_DROP`, la tendance de la tension batterie sur 7 jours ; `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP`, la même sur la seule mesure de 00:00 UTC ; `DAILY_BATTERY_STATE`, l'état de la batterie jour par jour ; `DAILY_BATTERY_TREND`, sa tendance d'un jour à l'autre. Les suivantes sont listées dans les fiches `docs/analyses/` (section « Pistes »). +Prototype expérimental, sans tests automatisés. Quatre analyses Energy sont en place. Deux sont livrées : `DAILY_BATTERY_STATE`, l'état de la batterie jour par jour, et `DAILY_BATTERY_TREND`, sa tendance d'un jour à l'autre. Les deux autres servent à la comparaison : `MOVING_AVERAGE_7_DAYS_DROP` et sa variante sur la seule mesure de 00:00 UTC. Les suivantes sont listées dans les fiches `docs/energy/analyses/` (section « Pistes »). diff --git a/doc/AIMsight FAQ.pdf b/docs/aimsight/AIMsight FAQ.pdf similarity index 100% rename from doc/AIMsight FAQ.pdf rename to docs/aimsight/AIMsight FAQ.pdf diff --git a/doc/AIMsight Test Manual.pdf b/docs/aimsight/AIMsight Test Manual.pdf similarity index 100% rename from doc/AIMsight Test Manual.pdf rename to docs/aimsight/AIMsight Test Manual.pdf diff --git a/doc/AIMsight_agentic_support_project_context.md b/docs/aimsight/AIMsight_agentic_support_project_context.md similarity index 100% rename from doc/AIMsight_agentic_support_project_context.md rename to docs/aimsight/AIMsight_agentic_support_project_context.md diff --git a/doc/AIMsight_reference_quality_event_explainer_roadmap (2).md b/docs/aimsight/AIMsight_reference_quality_event_explainer_roadmap.md similarity index 100% rename from doc/AIMsight_reference_quality_event_explainer_roadmap (2).md rename to docs/aimsight/AIMsight_reference_quality_event_explainer_roadmap.md diff --git a/src/__main__ (3).py b/docs/aimsight/collecteur_system_info.py similarity index 100% rename from src/__main__ (3).py rename to docs/aimsight/collecteur_system_info.py diff --git a/docs/decisions.md b/docs/decisions.md index 328b499..c5cfdaf 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -48,7 +48,7 @@ Règles du journal : - **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** : active. +- **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é). @@ -75,7 +75,7 @@ Règles du journal : - **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. +- **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. @@ -93,7 +93,7 @@ Règles du journal : - **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. +- **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. @@ -135,7 +135,7 @@ Règles du journal : - **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. +- **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/_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. @@ -254,3 +254,21 @@ Règles du journal : - 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/daily.py`, les analyses livrées (état et tendance, D-020 et D-021), qui écrit `out/_daily.html` et `.json` ; `src/energy/all_analyses.py`, les quatre analyses ensemble pour comparer (D-016), qui écrit `out/_energy.html`. `src/energy/focus_jour.py` reste l'outil de focus (D-024). Le résumé texte d'`energy_check.py` (`out/_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 `daily.py`, `all_analyses.py` ni `focus_jour.py`, qui demandent plotly. diff --git a/docs/domaine/ce-que-mesure-la-station.md b/docs/domaine/ce-que-mesure-la-station.md index 1f1b0a8..c92826c 100644 --- a/docs/domaine/ce-que-mesure-la-station.md +++ b/docs/domaine/ce-que-mesure-la-station.md @@ -10,7 +10,7 @@ ## Métriques système et unités -La source est le collecteur embarqué `src/__main__ (3).py` : bibliothèque INA219, shunt de 0,1 Ω. +La source est le collecteur embarqué `docs/aimsight/collecteur_system_info.py` : bibliothèque INA219, shunt de 0,1 Ω. | Métrique | Unité | Sens | |---|---|---| @@ -31,7 +31,7 @@ La source est le collecteur embarqué `src/__main__ (3).py` : bibliothèque INA2 Ces valeurs ne sont pas exportées dans les CSV actuels : - `BusVoltageOCV` : tension compensée de la chute dans la résistance interne, avec R = 0,34 Ω (mesure faite sur une station déployée) ; - `BusVoltageTrend` : pente en mV/min sur une fenêtre de 60 s ; -- `BatteryState` et `BatteryPercent` : état de charge estimé par la table OCV LiFePO4 (voir `comment-se-comporte-la-batterie.md`). +- `BatteryState` et `BatteryPercent` : état de charge estimé par la table OCV LiFePO4 (voir `docs/energy/domaine/comment-se-comporte-la-batterie.md`). ## Instantanés d'état système diff --git a/docs/domaine/colonnes-des-deplacements.md b/docs/domaine/colonnes-des-deplacements.md index e6b83ff..64d34c5 100644 --- a/docs/domaine/colonnes-des-deplacements.md +++ b/docs/domaine/colonnes-des-deplacements.md @@ -16,4 +16,4 @@ Causes à départager pour une anomalie de déplacement : - dégradation locale d'une cible ; - parallaxe ou modèle inadapté. -La référence qui fait autorité est `doc/AIMsight_reference_quality_event_explainer_roadmap (2).md`. Les règles non négociables qui s'y rapportent (`inlier` binaire, `sigma0`, mode commun) sont dans `CLAUDE.md`. +La référence qui fait autorité est `docs/aimsight/AIMsight_reference_quality_event_explainer_roadmap.md`. Les règles non négociables qui s'y rapportent (`inlier` binaire, `sigma0`, mode commun) sont dans `CLAUDE.md`. diff --git a/docs/analyses/analyse_03.md b/docs/energy/analyses/daily_battery_state.md similarity index 86% rename from docs/analyses/analyse_03.md rename to docs/energy/analyses/daily_battery_state.md index bc47c87..769ab71 100644 --- a/docs/analyses/analyse_03.md +++ b/docs/energy/analyses/daily_battery_state.md @@ -1,27 +1,27 @@ -# Analyse 03 — `DAILY_BATTERY_STATE` : état de la batterie jour par jour +# `DAILY_BATTERY_STATE` : état de la batterie jour par jour - **Statut** : prototype en place (2026-10-12). Phase C : l'état seul, sans verdict. La phase B (niveaux gradués) viendra ensuite (D-018). -- **Script** : `python3 src/analyse_03.py [CSV ou dossiers]` (défaut : `data/`). Il lance la page commune de `analyse_01.py` : `out/_energy.html`, où cette analyse est le troisième panneau d'analyse (D-016). +- **Script** : `python3 src/energy/daily.py [CSV ou dossiers]` (défaut : `data/`). Il écrit la page livrée, `out/_daily.html` + `.json`, dont cette analyse est le panneau du haut (D-021), et l'ouvre dans le navigateur. Elle est aussi le troisième panneau de `python3 src/energy/all_analyses.py` (comparaison, D-016). - **Code** : - - `src/battery_state.py` : calcul, bibliothèque standard uniquement (`run()`, `day_facts()`). Il reçoit les séries chargées par `energy_check.load_stations`, mais n'importe rien d'autre du projet : avec `src/battery_trend.py`, il se livre seul à la plateforme (D-021) ; - - `src/energy_plot.py` : graphique plotly. + - `src/energy/battery_state.py` : calcul, bibliothèque standard uniquement (`run()`, `day_facts()`). Il reçoit les séries chargées par `common.stations.load_stations`, mais n'importe rien d'autre du projet : avec `src/energy/battery_trend.py`, il se livre seul à la plateforme (D-021) ; + - `src/energy/daily.py` : graphique plotly. ## Question posée Dans quel état la batterie a-t-elle passé chaque journée : remplie, chargée sans se remplir, ou en décharge visible ? - **Lien avec D-004** : une journée où l'apport remplit la batterie est soutenable ce jour-là. Une décharge visible signale un apport qui ne couvre pas la consommation. -- **Ce que l'analyse ajoute aux analyses 01 et 02** : +- **Ce que l'analyse ajoute aux deux `MOVING_AVERAGE_*`** : - pas d'inertie : l'état d'un jour ne dépend que de ce jour ; - aucun historique nécessaire, donc utilisable **dès le premier jour d'installation**, pour repérer une alimentation absente ou un apport insuffisant. - **Elle signale les journées incertaines** : sur le plateau LiFePO4, une charge partielle ne dit pas si la batterie a gagné ou perdu. C'est le moment d'indiquer au client que la situation énergétique est incertaine. ## Principe -On lit chaque journée UTC avec des seuils physiques du matériel : la fin de charge du chargeur et le coude LiFePO4. Ces seuils valent dès le premier jour, sans comparaison au passé (D-018). Les tensions de référence sont dans `docs/domaine/tensions-selon-l-etat-de-la-batterie.md`. +On lit chaque journée UTC avec des seuils physiques du matériel : la fin de charge du chargeur et le coude LiFePO4. Ces seuils valent dès le premier jour, sans comparaison au passé (D-018). Les tensions de référence sont dans `docs/energy/domaine/tensions-selon-l-etat-de-la-batterie.md`. Calcul exact, pour chaque jour UTC d (de 00:00 à 23:00) ayant au moins une ligne `BusVoltage` : -1. Heures mesurées : valeurs `BusVoltage` non vides et finies. Une valeur vide, `NaN` ou `inf` compte comme « pas de mesure ». Un horodatage hors de la grille horaire lève une erreur, comme dans l'analyse 01. +1. Heures mesurées : valeurs `BusVoltage` non vides et finies. Une valeur vide, `NaN` ou `inf` compte comme « pas de mesure ». Un horodatage hors de la grille horaire lève une erreur, comme dans `MOVING_AVERAGE_7_DAYS_DROP`. 2. `max_v` et `min_v` = maximum et minimum du jour. 3. `rise_v` = la plus grande montée du jour depuis un minimum antérieur : max sur h de (tension à h − minimum des heures ≤ h). 4. `night_end_v` = le minimum dont part cette montée (la fin de nuit, avant la charge du jour) ; sans montée, `min_v`. Le maximum du jour ne sert pas de repère : il peut être la queue de la soirée précédente, à 00:00. @@ -53,9 +53,9 @@ Sortie (contrat commun) : un point par jour. | Constante | Valeur | Source | |---|---|---| | `FULL_CHARGE_V` | 14,0 V | VERMONT, du 2026-04-09 au 2026-10-09 : sur 173 jours d'au moins 20 h mesurées, le maximum du jour est sous 13,55 V pour 35 jours et entre 14,02 et 14,33 V pour 135 jours. Seuls 3 jours tombent entre les deux (13,59, 13,68 et 13,96 V). Note de domaine : ≥ 14,0 V signale une charge complète (absorption ~14,2 V). | -| `PLATEAU_FLOOR_V` | 12,8 V | Coude de la table OCV du collecteur (12,8 V = 30 %, `src/__main__ (3).py`). VERMONT : la pente de la baisse nocturne double sous 12,8 V (15 mV/h à 12,9 V, 29 mV/h à 12,8 V). | +| `PLATEAU_FLOOR_V` | 12,8 V | Coude de la table OCV du collecteur (12,8 V = 30 %, `docs/aimsight/collecteur_system_info.py`). VERMONT : la pente de la baisse nocturne double sous 12,8 V (15 mV/h à 12,9 V, 29 mV/h à 12,8 V). | | `MIN_RISE_V` | 0,05 V | Au-dessus des variations d'une heure à l'autre sur le plateau (≤ 15 mV/h la nuit), et sous la plus faible vraie montée observée sur VERMONT (+0,079 V le 2026-05-05, jour nuageux ; ensuite +0,18 V le 2026-04-11). | -| `MIN_COVERAGE` | 0,8 | Repris de l'analyse 01 : 20 heures mesurées sur 24. | +| `MIN_COVERAGE` | 0,8 | Repris de `MOVING_AVERAGE_7_DAYS_DROP` : 20 heures mesurées sur 24. | ## Graphique @@ -83,13 +83,13 @@ Sortie (contrat commun) : un point par jour. | Option | Pourquoi écartée | |---|---| -| Comparer le jour au propre passé de la station (ex. maximum du jour face aux 30 derniers jours) | Aveugle à l'installation, faute d'historique, et sujette à l'accoutumance de l'analyse 01. | +| Comparer le jour au propre passé de la station (ex. maximum du jour face aux 30 derniers jours) | Aveugle à l'installation, faute d'historique, et sujette à l'accoutumance de `MOVING_AVERAGE_7_DAYS_DROP`. | | Hybride : seuils absolus les N premiers jours, puis comparaison au passé | Deux règles à calibrer et un changement de comportement au jour N, trop pour une première version. | | Un état par heure, ou un état horaire résumé par jour | La frontière entre charge et décharge sur le plateau est fragile à l'heure près. L'utilisateur a choisi un état par jour. | | États du collecteur (`BatteryState`, pente sur 60 s, ±2,5 mV/min) | Mis de côté par l'utilisateur. Ils demandent les données brutes à 1 Hz, et leur seuil (±150 mV/h) classe « stable » la charge et la décharge sur le plateau. | | Verdict gradué dès cette version (phase B) | Reporté : d'abord l'état seul (phase C), choix de l'utilisateur. | -| Fin de nuit de la nuit qui suit le jour (matin de d+1) | Essayée le 2026-10-12, puis écartée par l'utilisateur, dans l'analyse 03 comme dans la 04 : l'analyse 03 reste sur les heures du jour lui-même (D-019). | -| Nouveau champ du contrat pour « pas de verdict » | Toucherait les analyses 01 et 02 ; `anomaly = None` documenté suffit en phase C. | +| Fin de nuit de la nuit qui suit le jour (matin de d+1) | Essayée le 2026-10-12, puis écartée par l'utilisateur, dans `DAILY_BATTERY_STATE` comme dans `DAILY_BATTERY_TREND` : `DAILY_BATTERY_STATE` reste sur les heures du jour lui-même (D-019). | +| Nouveau champ du contrat pour « pas de verdict » | Toucherait les deux `MOVING_AVERAGE_*` ; `anomaly = None` documenté suffit en phase C. | ## Limites connues @@ -117,3 +117,4 @@ Sortie (contrat commun) : un point par jour. - **2026-10-12** : sur le graphique, chaque point est placé à midi UTC de son jour, et non plus à 23:00, comme les barres de l'analyse 04 (D-019). Le calcul ne change pas. - **2026-10-12** : titres, légendes et survols du graphique en anglais, pour le site de monitoring (D-023). Le calcul ne change pas. - **2026-10-12** : nouveau fait `night_end_h` (heure de la fin de nuit), pour placer la fin de nuit sur le graphique focus J−1 / J (D-024). Les autres faits ne changent pas (vérifié sur les 184 jours de VERMONT). +- **2026-10-12** : fiche renommée d'après la règle (ex-`analyse_03.md`) et déplacée dans `docs/energy/analyses/` ; code dans `src/energy/` (D-026). Calcul inchangé. diff --git a/docs/analyses/analyse_04.md b/docs/energy/analyses/daily_battery_trend.md similarity index 80% rename from docs/analyses/analyse_04.md rename to docs/energy/analyses/daily_battery_trend.md index aee9796..fe23bbb 100644 --- a/docs/analyses/analyse_04.md +++ b/docs/energy/analyses/daily_battery_trend.md @@ -1,23 +1,23 @@ -# Analyse 04 — `DAILY_BATTERY_TREND` : tendance de la batterie d'un jour à l'autre +# `DAILY_BATTERY_TREND` : tendance de la batterie d'un jour à l'autre - **Statut** : prototype en place (2026-10-12). Pas de verdict : `anomaly = None`, la tendance est dans `facts.trend`. -- **Script** : `python3 src/analyse_04.py [CSV ou dossiers]` (défaut : `data/`). Il lance la page commune de `analyse_01.py` : `out/_energy.html`, où cette analyse est le quatrième panneau d'analyse (D-016). +- **Script** : `python3 src/energy/daily.py [CSV ou dossiers]` (défaut : `data/`). Il écrit la page livrée, `out/_daily.html` + `.json`, dont cette analyse est le panneau du bas (D-021), et l'ouvre dans le navigateur. Elle est aussi le quatrième panneau de `python3 src/energy/all_analyses.py` (comparaison, D-016). - **Code** : - - `src/battery_trend.py` : calcul, bibliothèque standard uniquement (`run()`). Il s'appuie sur `battery_state.run()` (analyse 03) ; - - `src/energy_plot.py` : graphique plotly. + - `src/energy/battery_trend.py` : calcul, bibliothèque standard uniquement (`run()`). Il s'appuie sur `battery_state.run()` (`DAILY_BATTERY_STATE`) ; + - `src/energy/daily.py` : graphique plotly. ## Question posée Chaque jour J, la batterie va-t-elle mieux, pareil ou moins bien que la veille J−1 ? - **Lien avec D-004** : un régime non soutenable se voit comme une suite de jours qui empirent. Une tendance d'un seul jour n'est pas une anomalie : un jour nuageux sur une station saine donne déjà `WORSE`. -- **Ce que l'analyse ajoute à l'analyse 03** : - - la 03 lit chaque jour isolément. La 04 compare deux jours, et voit une dégradation **à l'intérieur d'un même état**, comme une suite de `PARTIAL_CHARGE` dont la fin de nuit baisse chaque jour ; +- **Ce que l'analyse ajoute à `DAILY_BATTERY_STATE`** : + - `DAILY_BATTERY_STATE` lit chaque jour isolément. `DAILY_BATTERY_TREND` compare deux jours, et voit une dégradation **à l'intérieur d'un même état**, comme une suite de `PARTIAL_CHARGE` dont la fin de nuit baisse chaque jour ; - le modèle est **markovien** : seul le jour précédent compte. L'analyse reste donc utilisable dès le deuxième jour d'installation (D-018). ## Principe -On compare l'état du jour J (analyse 03) à celui de J−1. S'il a changé, le changement donne la tendance. Sinon, c'est l'écart de fin de nuit qui la donne. La fin de nuit du jour J est le minimum dont part la charge du jour : son écart avec celle de J−1 résume le bilan des 24 h écoulées (charge de J−1, puis la nuit). +On compare l'état du jour J (`DAILY_BATTERY_STATE`) à celui de J−1. S'il a changé, le changement donne la tendance. Sinon, c'est l'écart de fin de nuit qui la donne. La fin de nuit du jour J est le minimum dont part la charge du jour : son écart avec celle de J−1 résume le bilan des 24 h écoulées (charge de J−1, puis la nuit). Calcul exact, pour chaque point J de `DAILY_BATTERY_STATE` (un par jour UTC) : 1. `prev` = le point précédent, s'il est bien la veille calendaire de J ; sinon, pas de `prev`. @@ -29,9 +29,9 @@ Calcul exact, pour chaque point J de `DAILY_BATTERY_STATE` (un par jour UTC) : - sinon : `STABLE`. Sortie (contrat commun) : un point par jour. -- `t` = le `t` du jour J dans l'analyse 03 (dernière heure du jour présente dans la série). +- `t` = le `t` du jour J dans `DAILY_BATTERY_STATE` (dernière heure du jour présente dans la série). - `value` = `delta_night_end_v`, en V (`None` si l'un des deux jours n'a pas de fin de nuit). -- `anomaly` = `None` pour tous les jours : **pas de verdict**, comme l'analyse 03 en phase C. L'UNKNOWN de la tendance est porté par `trend = None`. +- `anomaly` = `None` pour tous les jours : **pas de verdict**, comme `DAILY_BATTERY_STATE` en phase C. L'UNKNOWN de la tendance est porté par `trend = None`. - `facts` = `{trend, decided_by, state_prev, state, delta_night_end_v, delta_max_v, delta_hours_full}`. Les écarts du maximum et des heures pleines sont seulement affichés : ils ne décident pas. **Causalité** : le jour J n'utilise que les heures de J et de J−1. Si J est le dernier jour, incomplet, d'un export, sa tendance est provisoire, comme son état. @@ -41,11 +41,11 @@ Sortie (contrat commun) : un point par jour. | Constante | Valeur | Source | |---|---|---| | `NIGHT_END_DEADBAND_V` | 0,05 V | VERMONT, du 2026-04-09 au 2026-10-09 : sur 125 paires de jours `FULL_CHARGE` enchaînés, l'écart de fin de nuit va de −0,026 à +0,043 V (5e et 95e centiles) ; seules 5 paires dépassent ±0,05 V. Les jours de déficit de septembre (`PARTIAL_CHARGE` enchaînés) baissent de −0,07 à −0,12 V. | -| `STATE_RANK` | `FULL_CHARGE` 3, `PARTIAL_CHARGE` 2, `NO_CHARGE` 1, `BELOW_PLATEAU` 0 | Choix de conception, tiré de la lecture des états (fiche analyse_03) : la batterie s'est remplie ; elle a chargé sans se remplir ; aucun apport visible, mais elle reste sur le plateau ; elle a quitté le plateau (< ~30 %). | +| `STATE_RANK` | `FULL_CHARGE` 3, `PARTIAL_CHARGE` 2, `NO_CHARGE` 1, `BELOW_PLATEAU` 0 | Choix de conception, tiré de la lecture des états (fiche `daily_battery_state.md`) : la batterie s'est remplie ; elle a chargé sans se remplir ; aucun apport visible, mais elle reste sur le plateau ; elle a quitté le plateau (< ~30 %). | ## Graphique -- **Place** : quatrième panneau d'analyse de la page commune, sous `DAILY_BATTERY_STATE` (D-016). Les états du jour se lisent dans le panneau 03, juste au-dessus, sur le même axe du temps. +- **Place** : quatrième panneau d'analyse de la page commune, sous `DAILY_BATTERY_STATE` (D-016). Les états du jour se lisent dans le panneau `DAILY_BATTERY_STATE`, juste au-dessus, sur le même axe du temps. - **Contenu** : - une barre par jour, centrée sur midi UTC de ce jour (D-019) : `delta_night_end_v`, en V, colorée selon la tendance (bleu : mieux ; gris : stable ; rouge : pire ; tendance inconnue : pas de barre). Ce sont la paire divergente et le gris neutre du skill dataviz. ; - la zone morte de ±0,05 V en tirets. Elle est tracée comme une courbe avec un point par jour, pour que le recalage au zoom (D-013) la garde visible. @@ -80,7 +80,7 @@ Sur 184 jours (du 2026-04-09 au 2026-10-09) : 2. **Dérive lente** : une baisse de moins de 0,05 V par jour reste `STABLE` (VERMONT : du 22 au 24/09, de −0,007 à −0,016 V par jour, alors que la station s'épuise). 3. **Un jour nuageux** donne `WORSE`, puis `BETTER` le lendemain. Ce qui comptera, c'est la série des tendances. 4. **Ordre de `NO_CHARGE` et `BELOW_PLATEAU`** : choix de conception. Le premier dit qu'il n'y a pas d'apport, le second que la batterie est basse ; les deux ne se comparent pas sur une même échelle. -5. **Limites héritées de l'analyse 03** : jour UTC, seuil de 14,0 V, résolution horaire. +5. **Limites héritées de `DAILY_BATTERY_STATE`** : jour UTC, seuil de 14,0 V, résolution horaire. 6. **La fin de nuit de J porte le bilan de J−1** : c'est celle du matin de J, avant sa charge. L'écart de fin de nuit de J résume donc la charge de J−1, alors que l'état est celui de J. Quand l'état change, la barre peut le contredire. Sur VERMONT, c'est le cas de 16 changements d'état sur 28, dont 3 au-delà de la zone morte : le 2026-04-12 passe de `PARTIAL_CHARGE` à `FULL_CHARGE`, avec −0,187 V après le 11/04 nuageux. Un décalage d'un jour a été écarté (voir « Options écartées »). ## Pistes @@ -94,3 +94,4 @@ Sur 184 jours (du 2026-04-09 au 2026-10-09) : - **2026-10-12** : implémentée (`src/battery_trend.py`, panneau dans `energy_plot.py`, point d'entrée `analyse_04.py`). Résultats conformes à l'essai de conception, à un UNKNOWN près (le premier jour, sans veille). Couleur de « mieux » : bleu au lieu de vert (skill dataviz). - **2026-10-12** : sur le graphique, chaque barre est centrée sur midi UTC de son jour, et non plus sur 23:00 : à 23:00, elle débordait sur le lendemain (le 12/04 a été lu « 13 avril »). Le calcul ne change pas : le décalage d'un jour de la fin de nuit a été essayé, puis écarté (D-019, limite 6). - **2026-10-12** : titres, légendes et survols du graphique en anglais, pour le site de monitoring (D-023). Le calcul ne change pas. +- **2026-10-12** : fiche renommée d'après la règle (ex-`analyse_04.md`) et déplacée dans `docs/energy/analyses/` ; code dans `src/energy/` (D-026). Calcul inchangé. diff --git a/docs/analyses/analyse_01.md b/docs/energy/analyses/moving_average_7_days_drop.md similarity index 83% rename from docs/analyses/analyse_01.md rename to docs/energy/analyses/moving_average_7_days_drop.md index 9baa28e..5e80959 100644 --- a/docs/analyses/analyse_01.md +++ b/docs/energy/analyses/moving_average_7_days_drop.md @@ -1,10 +1,10 @@ -# Analyse 01 — `MOVING_AVERAGE_7_DAYS_DROP` : tendance de la tension batterie +# `MOVING_AVERAGE_7_DAYS_DROP` : tendance de la tension batterie - **Statut** : prototype, en place (2026-10-09). -- **Script** : `python3 src/analyse_01.py [CSV ou dossiers]` (défaut : `data/`). Il écrit `out/_energy.html` et l'ouvre dans le navigateur. La page montre aussi l'analyse 02, juste dessous (D-016). +- **Script** : `python3 src/energy/all_analyses.py [CSV ou dossiers]` (défaut : `data/`). Il écrit `out/_energy.html` et l'ouvre dans le navigateur. Cette analyse est le premier panneau, et `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` est juste dessous (D-016). Elle sert à la comparaison seulement : elle n'est pas livrée (D-020). - **Code** : - - `src/energy_check.py` : chargement et calcul, bibliothèque standard uniquement. `run()` appelle `_ma_drop()`, commun avec l'analyse 02 ; - - `src/energy_plot.py` : graphique plotly. + - `src/energy/moving_average.py` : calcul, bibliothèque standard uniquement. `run()` appelle `_ma_drop()`, commun avec `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP`. Les séries sont chargées par `common.stations.load_stations` ; + - `src/energy/all_analyses.py` : graphique plotly. ## Question posée @@ -39,16 +39,16 @@ Disposition (D-011) : - la moyenne sur 7 jours (bleu) ; - le seuil = référence − 0,2 V (rouge) : l'anomalie commence là où la bleue passe sous la rouge ; - un fond rouge sur les périodes d'anomalie. -- **Juste dessous, le panneau de l'analyse 02** (`MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP`), mêmes conventions, pour comparer les deux méthodes (D-016). -- **Puis le panneau de l'analyse 03** (`DAILY_BATTERY_STATE`) : état de la batterie jour par jour (fiche `analyse_03.md`). -- **Puis le panneau de l'analyse 04** (`DAILY_BATTERY_TREND`) : tendance de la batterie d'un jour à l'autre (fiche `analyse_04.md`). -- **Dessous, un graphique par série temporelle**, chacun avec sa propre échelle : `BusVoltage` d'abord (bandes grises sur ses trous, et en fond les 3 zones d'état de la batterie : décharge 12,0–13,2 V, en charge 13,1–13,8 V, pleine charge 14,0–14,4 V, d'après `docs/domaine/tensions-selon-l-etat-de-la-batterie.md` ; `ZONES` dans `energy_plot.py`), puis les autres champs par ordre alphabétique. +- **Juste dessous, le panneau `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP`**, mêmes conventions, pour comparer les deux méthodes (D-016). +- **Puis le panneau `DAILY_BATTERY_STATE`** : état de la batterie jour par jour (fiche `daily_battery_state.md`). +- **Puis le panneau `DAILY_BATTERY_TREND`** : tendance de la batterie d'un jour à l'autre (fiche `daily_battery_trend.md`). +- **Dessous, un graphique par série temporelle**, chacun avec sa propre échelle : `BusVoltage` d'abord (bandes grises sur ses trous, et en fond les 3 zones d'état de la batterie : décharge 12,0–13,2 V, en charge 13,1–13,8 V, pleine charge 14,0–14,4 V, d'après `docs/energy/domaine/tensions-selon-l-etat-de-la-batterie.md` ; `ZONES` dans `src/energy/all_analyses.py`), puis les autres champs par ordre alphabétique. - **Abscisse** : les dates sont affichées sous chaque graphique, pas seulement sous le dernier. -- **Zoom** : il est horizontal seulement, dans le temps, et commun à tous les graphiques. On zoome en tirant un rectangle ou à la molette (`scrollZoom`). Après chaque zoom ou déplacement, l'ordonnée de chaque graphique est recalée sur les points visibles, avec 5 % de marge (`AUTOSCALE_Y_JS` dans `energy_plot.py`). La ligne de seuil reste toujours visible. Un double-clic revient à la vue complète. +- **Zoom** : il est horizontal seulement, dans le temps, et commun à tous les graphiques. On zoome en tirant un rectangle ou à la molette (`scrollZoom`). Après chaque zoom ou déplacement, l'ordonnée de chaque graphique est recalée sur les points visibles, avec 5 % de marge (`AUTOSCALE_Y_JS` dans `src/common/page.py`). La ligne de seuil reste toujours visible. Un double-clic revient à la vue complète. - Le script utilise l'API interne de plotly.js (`_fullLayout`, `d2l`, `r2l`). La version de plotly.js chargée depuis le CDN est celle du paquet Python, donc figée, mais une mise à jour majeure de plotly pourrait casser ce script. - **Survol** (sur la moyenne) : il affiche l'écart, le verdict et les faits du point (`ma_v`, `ref_v`, `ref_t`, couverture). -`python3 src/energy_check.py data/` produit en plus `out/_energy.json` (tous les points avec leurs faits) et un résumé texte. Ce résumé donne les périodes d'anomalie, les heures sans verdict et la plus longue plage UNKNOWN. +Le résumé texte et `out/_energy.json` ont été supprimés (D-026) ; les périodes d'anomalie restent visibles, en rouge, sur la page. ## Résultats sur VERMONT (jeu de travail) @@ -107,3 +107,4 @@ Disposition (D-011) : - tests supprimés (D-008) ; - jeu réduit à VERMONT (D-009). - **2026-10-12** : panneau d'analyse réduit à 2 courbes sur un seul axe (D-015) ; l'écart et la référence passent au survol. Le calcul passe dans `_ma_drop()`, partagé avec l'analyse 02 (résultats inchangés, vérifié sur VERMONT), et la page reçoit le panneau de l'analyse 02 (D-016). Renommée de `MA7D_DROP` en `MOVING_AVERAGE_7_DAYS_DROP` (D-017). Zones d'état de la batterie ajoutées en fond du graphique `BusVoltage` (affichage seulement, aucun effet sur le calcul). +- **2026-10-12** : fiche renommée d'après la règle (ex-`analyse_01.md`) et déplacée dans `docs/energy/analyses/` ; code dans `src/energy/` (D-026). Calcul inchangé. diff --git a/docs/analyses/analyse_02.md b/docs/energy/analyses/moving_average_7_days_midnight_utc_drop.md similarity index 67% rename from docs/analyses/analyse_02.md rename to docs/energy/analyses/moving_average_7_days_midnight_utc_drop.md index 5dc3c64..eaba519 100644 --- a/docs/analyses/analyse_02.md +++ b/docs/energy/analyses/moving_average_7_days_midnight_utc_drop.md @@ -1,14 +1,14 @@ -# Analyse 02 — `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` : tendance de la tension batterie à minuit +# `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` : tendance de la tension batterie à minuit - **Statut** : prototype, en place (2026-10-12). -- **Script** : `python3 src/analyse_02.py [CSV ou dossiers]` (défaut : `data/`). Il lance la page commune de `analyse_01.py` : `out/_energy.html`, où cette analyse est le panneau placé sous `MOVING_AVERAGE_7_DAYS_DROP` (D-016). +- **Script** : `python3 src/energy/all_analyses.py [CSV ou dossiers]` (défaut : `data/`). Il écrit `out/_energy.html`, où cette analyse est le panneau placé sous `MOVING_AVERAGE_7_DAYS_DROP` (D-016). Elle sert à la comparaison seulement : elle n'est pas livrée (D-020). - **Code** : - - `src/energy_check.py` : `run_midnight()` et `RULE_MIDNIGHT`, bibliothèque standard uniquement. Le calcul est celui de `MOVING_AVERAGE_7_DAYS_DROP` (`_ma_drop()`, commun aux deux analyses) ; - - `src/energy_plot.py` : graphique plotly. + - `src/energy/moving_average.py` : `run_midnight()` et `RULE_MIDNIGHT`, bibliothèque standard uniquement. Le calcul est celui de `MOVING_AVERAGE_7_DAYS_DROP` (`_ma_drop()`, commun aux deux analyses) ; + - `src/energy/all_analyses.py` : graphique plotly. ## Question posée -La tension batterie relevée chaque jour à 00:00 UTC décroche-t-elle de son propre passé récent ? C'est la méthode de l'analyse 01 appliquée à une seule mesure par jour. Suggestion d'un collègue (2026-10-12), pour comparer les deux méthodes. Le lien avec D-004 (régime non soutenable) est le même que pour l'analyse 01, avec une réserve (voir « Limites connues », point 1). +La tension batterie relevée chaque jour à 00:00 UTC décroche-t-elle de son propre passé récent ? C'est la méthode de `MOVING_AVERAGE_7_DAYS_DROP` appliquée à une seule mesure par jour. Suggestion d'un collègue (2026-10-12), pour comparer les deux méthodes. Le lien avec D-004 (régime non soutenable) est le même que pour `MOVING_AVERAGE_7_DAYS_DROP`, avec une réserve (voir « Limites connues », point 1). ## Principe @@ -28,16 +28,16 @@ Le calcul est **causal** : le point d n'utilise que les mesures de minuit ≤ d. | Constante | Valeur | Source | |---|---|---| | Heure d'échantillonnage | 00:00 UTC | Suggestion du collègue. Sur VERMONT, c'est la nuit : profil horaire moyen de `BusVoltage` (avril–octobre 2026) avec un maximum à 13:00 UTC (13,93 V) et un plateau nocturne de 13,11 à 13,13 V de 23:00 à 05:00 UTC. | -| `window_d` | 7 | `WINDOW_H` / 24 (analyse 01). | -| `ref_d` | 30 | `REF_H` / 24 (analyse 01). | -| `min_coverage` | 0,8 | Repris de l'analyse 01 : 6 jours remplis sur 7. | -| `min_ref_points` | 1 | `MIN_REF_POINTS` / 24 : au moins un jour de référence, comme dans l'analyse 01. | -| `threshold_v` | −0,2 | Repris de l'analyse 01 pour comparer les méthodes à seuil égal. **Non recalibré** : voir « Pistes ». | +| `window_d` | 7 | `WINDOW_H` / 24 (`MOVING_AVERAGE_7_DAYS_DROP`). | +| `ref_d` | 30 | `REF_H` / 24 (`MOVING_AVERAGE_7_DAYS_DROP`). | +| `min_coverage` | 0,8 | Repris de `MOVING_AVERAGE_7_DAYS_DROP` : 6 jours remplis sur 7. | +| `min_ref_points` | 1 | `MIN_REF_POINTS` / 24 : au moins un jour de référence, comme dans `MOVING_AVERAGE_7_DAYS_DROP`. | +| `threshold_v` | −0,2 | Repris de `MOVING_AVERAGE_7_DAYS_DROP` pour comparer les méthodes à seuil égal. **Non recalibré** : voir « Pistes ». | ## Graphique -- **Page commune** (D-016) : le panneau `MOVING_AVERAGE_7_DAYS_DROP` en haut, ce panneau juste dessous, puis le panneau de l'analyse 03 (`DAILY_BATTERY_STATE`), puis un graphique par série temporelle. -- Mêmes conventions que l'analyse 01 : +- **Page commune** (D-016) : le panneau `MOVING_AVERAGE_7_DAYS_DROP` en haut, ce panneau juste dessous, puis les panneaux `DAILY_BATTERY_STATE` et `DAILY_BATTERY_TREND`, puis un graphique par série temporelle. +- Mêmes conventions que `MOVING_AVERAGE_7_DAYS_DROP` : - moyenne sur 7 jours (bleu) et seuil = référence − 0,2 V (rouge), sur un seul axe en volts (D-015) ; - fond rouge sur les périodes d'anomalie ; - survol : écart, verdict et faits du point. @@ -47,7 +47,7 @@ Le calcul est **causal** : le point d n'utilise que les mesures de minuit ≤ d. - Anomalie **à partir du 2026-09-27 00:00**, jusqu'à la fin de l'export. La première coupure nocturne est le 2026-09-27 01:00 : **1 h d'avance seulement**. `MOVING_AVERAGE_7_DAYS_DROP` se déclenche le 2026-09-24 07:00, ~2,7 jours plus tôt. - Pire écart le 2026-10-09 00:00 : moyenne sur 7 jours 12,56 V, soit 0,61 V sous son maximum du 2026-09-15 (13,17 V). -- **Bruit bien plus faible** : avant le 20/09 (début du déficit selon l'expert), le pire écart est −0,04 V (2026-05-11). C'est le même épisode nuageux de mai qui donne le pire cas sain de l'analyse 01, à −0,16 V. +- **Bruit bien plus faible** : avant le 20/09 (début du déficit selon l'expert), le pire écart est −0,04 V (2026-05-11). C'est le même épisode nuageux de mai qui donne le pire cas sain de `MOVING_AVERAGE_7_DAYS_DROP`, à −0,16 V. - L'écart reste dans le bruit sain (≥ −0,05 V) jusqu'au 2026-09-23. Il vaut ensuite −0,06 V le 24/09, −0,09 V le 25/09 et −0,13 V le 26/09, sans atteindre le seuil de −0,2 V. - **Pourquoi ~2,7 jours d'écart avec `MOVING_AVERAGE_7_DAYS_DROP`** (valeurs de septembre 2026) : - la journée se dégrade d'abord : après le 08/09, seuls les 11, 18 et 19/09 atteignent 14 V, et la moyenne de 9 à 16 h UTC passe de 13,6–13,9 V à ~13,3 V. La nuit reste sur le plateau, entre 13,05 et 13,18 V, jusqu'au 22/09. `MOVING_AVERAGE_7_DAYS_DROP` voit l'apport baisser, cette analyse ne voit rien ; @@ -58,23 +58,24 @@ Le calcul est **causal** : le point d n'utilise que les mesures de minuit ≤ d. | Option | Pourquoi écartée | |---|---| -| Moyenne glissante horaire (analyse 01) évaluée seulement à 00:00 | Autre lecture de la suggestion. Elle donne exactement les valeurs de `MOVING_AVERAGE_7_DAYS_DROP` à minuit : rien de nouveau à comparer. | +| Moyenne glissante horaire (`MOVING_AVERAGE_7_DAYS_DROP`) évaluée seulement à 00:00 | Autre lecture de la suggestion. Elle donne exactement les valeurs de `MOVING_AVERAGE_7_DAYS_DROP` à minuit : rien de nouveau à comparer. | ## Limites connues -1. **Plus tardive** : la tension de nuit reste plate sur le plateau LiFePO4 (30–90 % de charge) et ne chute qu'au coude. La mesure de minuit ne bouge donc que lorsque la batterie est déjà basse. Elle décrit plutôt le niveau de charge que la soutenabilité (D-004), un peu comme le seuil absolu au coude écarté dans l'analyse 01. Sur VERMONT : 1 h d'avance sur la première coupure. +1. **Plus tardive** : la tension de nuit reste plate sur le plateau LiFePO4 (30–90 % de charge) et ne chute qu'au coude. La mesure de minuit ne bouge donc que lorsque la batterie est déjà basse. Elle décrit plutôt le niveau de charge que la soutenabilité (D-004), un peu comme le seuil absolu au coude écarté dans `MOVING_AVERAGE_7_DAYS_DROP`. Sur VERMONT : 1 h d'avance sur la première coupure. 2. **Une mesure par jour** : un minuit manquant fait perdre un jour entier, et deux minuits manquants sur 7 font passer le point en UNKNOWN. Le risque augmente avec le déficit : si les coupures nocturnes commencent avant minuit, l'analyse devient aveugle au moment où la situation s'aggrave. Sur VERMONT, la couverture est déjà à 6/7 depuis le 2026-10-01. 3. **Heure en UTC** : 00:00 UTC n'est la nuit que pour une station dont la longitude s'y prête. Ailleurs, on mesurerait en pleine charge. Ce n'est pas une règle transposable telle quelle. -4. **Seuil non recalibré** : −0,2 V vient de l'analyse 01, dont le pire écart sain est 4 fois plus grand (−0,16 V contre −0,04 V). Aucune station saine n'est dans le jeu de travail pour recalibrer (D-009). +4. **Seuil non recalibré** : −0,2 V vient de `MOVING_AVERAGE_7_DAYS_DROP`, dont le pire écart sain est 4 fois plus grand (−0,16 V contre −0,04 V). Aucune station saine n'est dans le jeu de travail pour recalibrer (D-009). 5. **Verdict une fois par jour** : jusqu'à 24 h de latence. -6. **Accoutumance** : comme pour l'analyse 01, la référence de 30 jours finit par s'aligner sur un déficit qui dure. -7. **Pas de résumé texte ni de JSON** : `python3 src/energy_check.py` ne traite que `MOVING_AVERAGE_7_DAYS_DROP`. +6. **Accoutumance** : comme pour `MOVING_AVERAGE_7_DAYS_DROP`, la référence de 30 jours finit par s'aligner sur un déficit qui dure. +7. **Pas de résumé texte ni de JSON** : supprimés pour les deux moyennes glissantes (D-026). ## Pistes - **Resserrer le seuil** : avec un pire cas sain à −0,04 V, un seuil à −0,1 V se serait déclenché le 2026-09-26 00:00 (~1 jour avant la coupure), et un seuil à −0,05 V le 2026-09-24 00:00, mais avec une marge de 0,01 V seulement. À vérifier sur des stations saines (`data/archive/` contient `BusVoltage` de FLORIDA et JUNGFRAU, à réintroduire seulement sur demande). -- **Minimum nocturne relatif** au lieu de la valeur de minuit : il ne dépend plus de l'heure UTC et un seul trou ne fait plus perdre le jour. À distinguer du seuil absolu sur le minimum nocturne, écarté dans l'analyse 01. +- **Minimum nocturne relatif** au lieu de la valeur de minuit : il ne dépend plus de l'heure UTC et un seul trou ne fait plus perdre le jour. À distinguer du seuil absolu sur le minimum nocturne, écarté dans `MOVING_AVERAGE_7_DAYS_DROP`. ## Historique - **2026-10-12** : création, sur la suggestion d'un collègue. Calcul commun avec l'analyse 01 (`_ma_drop()`), panneau placé sous `MOVING_AVERAGE_7_DAYS_DROP` dans la page commune (D-016). Le même jour, renommée de `MA7D_MIDNIGHT_DROP` en `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` (D-017). +- **2026-10-12** : fiche renommée d'après la règle (ex-`analyse_02.md`) et déplacée dans `docs/energy/analyses/` ; code dans `src/energy/` (D-026). Calcul inchangé. diff --git a/docs/domaine/cas-annotes-par-l-expert.md b/docs/energy/domaine/cas-annotes-par-l-expert.md similarity index 100% rename from docs/domaine/cas-annotes-par-l-expert.md rename to docs/energy/domaine/cas-annotes-par-l-expert.md diff --git a/docs/domaine/comment-se-comporte-la-batterie.md b/docs/energy/domaine/comment-se-comporte-la-batterie.md similarity index 100% rename from docs/domaine/comment-se-comporte-la-batterie.md rename to docs/energy/domaine/comment-se-comporte-la-batterie.md diff --git a/docs/domaine/tensions-selon-l-etat-de-la-batterie.md b/docs/energy/domaine/tensions-selon-l-etat-de-la-batterie.md similarity index 96% rename from docs/domaine/tensions-selon-l-etat-de-la-batterie.md rename to docs/energy/domaine/tensions-selon-l-etat-de-la-batterie.md index 9ec6a28..ca0d20f 100644 --- a/docs/domaine/tensions-selon-l-etat-de-la-batterie.md +++ b/docs/energy/domaine/tensions-selon-l-etat-de-la-batterie.md @@ -3,9 +3,9 @@ Rapport du 2026-10-12. Il répond à une question : quelle tension `BusVoltage` attendre dans chacun des 3 états de la batterie ? Sources, citées sur chaque chiffre : -- **[C]** collecteur embarqué `src/__main__ (3).py` ; -- **[M]** manuel de la station (`doc/AIMsight Test Manual.pdf`) ; -- **[F]** FAQ (`doc/AIMsight FAQ.pdf`) ; +- **[C]** collecteur embarqué `docs/aimsight/collecteur_system_info.py` ; +- **[M]** manuel de la station (`docs/aimsight/AIMsight Test Manual.pdf`) ; +- **[F]** FAQ (`docs/aimsight/AIMsight FAQ.pdf`) ; - **[E]** diagnostics experts (`data/metadata.md`, `cas-annotes-par-l-expert.md`) ; - **[V]** mesures de VERMONT (solaire), moyennes horaires du 2026-04-09 au 2026-10-09. Les plages [V] sont les 5e et 95e centiles ; - **[G]** chimie LiFePO4 générale, par cellule × 4. **Ces valeurs ne sont pas vérifiées sur le chargeur AIMsight**, dont le modèle et les réglages ne figurent pas dans la doc. @@ -40,7 +40,7 @@ Sources, citées sur chaque chiffre : ## 3. En décharge -- **La nuit, la consommation est le seul courant** : 360 à 440 mA [V], pour ~5 W constants (`ce-que-mesure-la-station.md`). +- **La nuit, la consommation est le seul courant** : 360 à 440 mA [V], pour ~5 W constants (`docs/domaine/ce-que-mesure-la-station.md`). - **Sur le plateau** : à 05 h UTC, après un jour plein, la tension est entre 13,08 et 13,21 V (médiane 13,15) [V]. - **Pente médiane de la baisse nocturne, selon la tension** [V] : diff --git a/docs/guide/diagnostic-energetique.md b/docs/energy/guide/diagnostic-energetique.md similarity index 87% rename from docs/guide/diagnostic-energetique.md rename to docs/energy/guide/diagnostic-energetique.md index 944f6ac..ed07a37 100644 --- a/docs/guide/diagnostic-energetique.md +++ b/docs/energy/guide/diagnostic-energetique.md @@ -1,6 +1,6 @@ # Manuel : lire le diagnostic énergétique d'une station AIMsight -- **Statut** : brouillon, 2026-10-12. La couleur du jour (partie 1) est calculée par `src/day_color.py`, selon la matrice de `cas-d-usage-03-04.drawio` (D-020), mais aucun graphique ne l'affiche encore (D-021). +- **Statut** : brouillon, 2026-10-12. La couleur du jour (partie 1) est calculée par `src/energy/day_color.py`, selon la matrice de `docs/energy/matrice-etat-tendance.drawio` (D-020), mais aucun graphique ne l'affiche encore (D-021). - **Lecteurs** : la partie 1 s'adresse au client final ; la partie 2 à l'ingénieur support AIMsight. --- @@ -74,14 +74,14 @@ Diagnostic de l'expert : interruptions nocturnes dues à un déficit d'énergie. # Partie 2 : annexe technique (support) La couleur du jour combine deux analyses de la tension batterie (`BusVoltage`, moyennes horaires) : -- l'**état** du jour (analyse 03, `DAILY_BATTERY_STATE`) ; -- la **tendance** face à la veille (analyse 04, `DAILY_BATTERY_TREND`). +- l'**état** du jour (`DAILY_BATTERY_STATE`) ; +- la **tendance** face à la veille (`DAILY_BATTERY_TREND`). -Le détail de chaque analyse (calcul exact, sources, résultats, options écartées) est dans sa fiche : `docs/analyses/analyse_03.md` et `docs/analyses/analyse_04.md`. +Le détail de chaque analyse (calcul exact, sources, résultats, options écartées) est dans sa fiche : `docs/energy/analyses/daily_battery_state.md` et `docs/energy/analyses/daily_battery_trend.md`. Une couleur reste une preuve imparfaite : elle conclut au plus `consistent with`. Elle signale une journée à regarder, elle ne remplace pas le diagnostic. -## 5. L'état du jour (analyse 03) +## 5. L'état du jour (`DAILY_BATTERY_STATE`) Chaque journée UTC (00:00 à 23:00) est lue avec deux seuils du matériel, valables dès le premier jour d'installation, sans historique (D-018) : - **14,0 V** : fin de charge du chargeur. Une heure à 14,0 V ou plus signale une recharge complète. @@ -103,7 +103,7 @@ L'état se lit dans cet ordre ; la première condition vraie l'emporte : - 12,8 V : table OCV du collecteur ; - 0,05 V : au-dessus du bruit d'une heure sur le plateau, sous la plus faible vraie recharge observée (+0,079 V un jour nuageux). -## 6. La tendance (analyse 04) +## 6. La tendance (`DAILY_BATTERY_TREND`) On compare le jour J à la veille J−1 : 1. **Si l'état a changé, l'état décide.** Rang : `FULL_CHARGE` > `PARTIAL_CHARGE` > `NO_CHARGE` > `BELOW_PLATEAU`. Un état plus haut donne `BETTER` (↗), un état plus bas donne `WORSE` (↘). @@ -147,21 +147,21 @@ Lecture de chaque case, avec le nombre de jours observés sur VERMONT (184 jours ## 8. Lire les pages HTML -Commande : `python3 src/analyse_03.py`. Elle écrit deux pages dans `out/` et les ouvre dans le navigateur. +Commandes : `python3 src/energy/daily.py` écrit la page livrée, `python3 src/energy/all_analyses.py` la page de comparaison ; chacune est écrite dans `out/` et ouverte dans le navigateur. - `_daily.html` : le graphique destiné au site de monitoring (D-021), soit les panneaux `DAILY_BATTERY_STATE` et `DAILY_BATTERY_TREND` décrits ci-dessous, sur le même axe du temps. Sa figure Plotly est aussi écrite en JSON (`_daily.json`), pour `Plotly.newPlot`. -- `_energy.html` : la page de toutes les analyses, avec ces deux panneaux, et une courbe par mesure dessous. -- `_focus_.html` : le focus sur un jour et sa veille (D-024), pour comprendre une couleur. Commande : `python3 src/focus_jour.py 27.09`. Le terminal affiche les faits qui ont produit la couleur ; le graphique montre les 48 h de `BusVoltage`, avec les heures sans mesure en gris, les seuils de 14,0 et 12,8 V, le maximum et la fin de nuit de chaque jour, et une flèche de la fin de nuit de la veille à celle du jour (bleue ↗, grise →, rouge ↘). +- `_energy.html` : la page de comparaison des quatre analyses (`all_analyses.py`), avec ces deux panneaux, et une courbe par mesure dessous. +- `_focus_.html` : le focus sur un jour et sa veille (D-024), pour comprendre une couleur. Commande : `python3 src/energy/focus_jour.py 27.09`. Le terminal affiche les faits qui ont produit la couleur ; le graphique montre les 48 h de `BusVoltage`, avec les heures sans mesure en gris, les seuils de 14,0 et 12,8 V, le maximum et la fin de nuit de chaque jour, et une flèche de la fin de nuit de la veille à celle du jour (bleue ↗, grise →, rouge ↘). **Attention aux couleurs** : celles des panneaux ne sont pas celles de la matrice. Elles distinguent les états et les tendances ; elles ne disent pas le niveau de préoccupation. Par exemple, `BELOW_PLATEAU` y est en bleu. -- **Langue** : les titres, légendes et survols des panneaux 03 et 04 sont en anglais, comme le site (D-023). Par exemple, le maximum du jour est `daily maximum`, la fin de nuit `night end`, et les tendances `better`, `stable` et `worse`. -- **Les panneaux 01 et 02** (moyennes sur 7 jours), en haut de la page, ne font pas partie de ce diagnostic : les ignorer. -- **Panneau `DAILY_BATTERY_STATE`** (analyse 03), un point par jour, placé à midi UTC : +- **Langue** : les titres, légendes et survols des panneaux `DAILY_BATTERY_STATE` et `DAILY_BATTERY_TREND` sont en anglais, comme le site (D-023). Par exemple, le maximum du jour est `daily maximum`, la fin de nuit `night end`, et les tendances `better`, `stable` et `worse`. +- **Les panneaux `MOVING_AVERAGE_*`** (moyennes sur 7 jours), en haut de la page de comparaison, ne font pas partie de ce diagnostic : les ignorer. +- **Panneau `DAILY_BATTERY_STATE`**, un point par jour, placé à midi UTC : - courbe foncée : le maximum du jour ; courbe claire : la fin de nuit ; - tirets : les seuils de 14,0 V (vert) et de 12,8 V (bleu) ; - marqueurs sur le maximum, selon l'état : ● vert `FULL_CHARGE`, ◆ jaune orangé `PARTIAL_CHARGE`, ▼ bleu `BELOW_PLATEAU`, ✕ violet `NO_CHARGE`. -- **Panneau `DAILY_BATTERY_TREND`** (analyse 04), une barre par jour : +- **Panneau `DAILY_BATTERY_TREND`**, une barre par jour : - hauteur : l'écart de fin de nuit face à la veille, en V ; - couleur : bleu ↗, gris →, rouge ↘ ; - tirets : la zone morte de ±0,05 V ; diff --git a/cas-d-usage-03-04.drawio b/docs/energy/matrice-etat-tendance.drawio similarity index 100% rename from cas-d-usage-03-04.drawio rename to docs/energy/matrice-etat-tendance.drawio diff --git a/docs/superpowers/plans/2026-10-12-structure-energy.md b/docs/superpowers/plans/2026-10-12-structure-energy.md new file mode 100644 index 0000000..8ea8071 --- /dev/null +++ b/docs/superpowers/plans/2026-10-12-structure-energy.md @@ -0,0 +1,845 @@ +# Structure Energy — plan d'implémentation + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Ranger le projet par domaine (`src/energy/`, `docs/energy/`, `src/common/`, `docs/aimsight/`), désigner les analyses par leur règle et ne garder que deux scripts d'analyse Energy (`daily.py` livré, `all_analyses.py` comparaison), sans changer les calculs ni les pages produites. + +**Architecture:** On déplace avec `git mv`, puis on recâble les imports : imports absolus, et `src/` ajouté au chemin par chaque script lancé directement. Le code non propre à un domaine passe dans `src/common/`. On vérifie en comparant les pages de `out/` avant et après. + +**Tech Stack:** Python 3 (bibliothèque standard pour le calcul), plotly dans `.venv/` pour les pages, git. + +**Spec:** `docs/superpowers/specs/2026-10-12-structure-energy-design.md` + +## Global Constraints + +- Aucune constante, aucune règle, aucun résultat de calcul ne change. +- Noms des fichiers de `out/` inchangés : `_daily.html` + `.json`, `_energy.html`, `_focus_.html` + `.json`, `maquette_user_energy.html` et `maquette_support_home.html`. `_energy.json` n'est plus produit. +- `moving_average.py`, `battery_state.py`, `battery_trend.py` et `day_color.py` : bibliothèque standard uniquement, sans aucun import de `common`. +- Contenu intact : `architecture.drawio`, les documents AIMsight, le collecteur, la matrice `.drawio`, `data/` et `docs/superpowers/` (hors ce plan et la spec). +- `docs/decisions.md` : on ajoute D-026 et on ne modifie que la ligne **Statut** de D-006, D-010 et D-012. +- Dans les fiches, les entrées « Historique » existantes ne changent pas ; on en ajoute une datée du 2026-10-12. +- `CLAUDE.md` reste sous 200 lignes. +- Un seul commit à la fin, comprenant la spec et ce plan. Il se termine par `Co-Authored-By: Claude Opus 5.5 `. +- Pas de tests automatisés (D-008). La vérification se fait par comparaison avant/après (tâches 1 et 2). + +## Review Focus + +- **Lancement depuis un autre dossier** (`cd /tmp && python3 ~/Support-Agent/src/energy/daily.py`) : les imports et `out/` doivent se résoudre depuis `__file__`, pas depuis le dossier courant. Vérifié à l'étape 2.9. +- **`python3` système sans plotly** : la bascule sur `.venv` doit encore marcher, avec `ROOT` calculé depuis `src/common/page.py`. Exercé par chaque lancement de la tâche 2, tous faits avec `python3`. +- **Copie embarquée de `src/energy/` seul** : les quatre modules de calcul doivent s'importer sans `common` ni plotly. Vérifié à l'étape 2.8. +- **Plusieurs stations ou un autre dossier en argument** (`daily.py data/archive`) : une page par station qui a `BusVoltage`, sans plantage. Vérifié à l'étape 2.9. +- **Lien périmé dans un document vivant** (ancien chemin, « analyse 03 ») : un lecteur suivrait un chemin mort. Vérifié à l'étape 3.9. + +--- + +### Task 1 : Référence avant le déplacement + +**Files:** +- Create : `$S/fakebin/explorer.exe`, `$S/compare.py`, `$S/before/` (scratchpad, hors dépôt) + +`$S` = `/tmp/claude-1000/-home-maxime-Support-Agent/6099095d-2188-40c8-b309-77844d71d619/scratchpad` + +**Interfaces:** +- Produit : `$S/before/` (les pages actuelles) et `python3 $S/compare.py AVANT APRÈS`, qui affiche `identique`, `DIFFÉRENT` (avec un extrait de chaque ligne différente) ou `absent avant/après` pour chaque fichier. + +- [ ] **Step 1 : faux `explorer.exe` (aucun onglet ouvert pendant les essais)** + +```bash +S=/tmp/claude-1000/-home-maxime-Support-Agent/6099095d-2188-40c8-b309-77844d71d619/scratchpad +mkdir -p $S/fakebin && printf '#!/bin/sh\nexit 0\n' > $S/fakebin/explorer.exe && chmod +x $S/fakebin/explorer.exe +``` + +- [ ] **Step 2 : script de comparaison `$S/compare.py`** + +```python +"""Compare deux dossiers de pages générées ; neutralise les UUID des figures Plotly.""" +import re +import sys +from itertools import zip_longest +from pathlib import Path + +UUID = re.compile(r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}") +before, after = Path(sys.argv[1]), Path(sys.argv[2]) +for name in sorted({p.name for p in before.iterdir()} | {p.name for p in after.iterdir()}): + a, b = before / name, after / name + if not (a.exists() and b.exists()): + print(f"{name} : absent {'avant' if not a.exists() else 'après'}") + continue + x, y = (UUID.sub("UUID", p.read_text()) for p in (a, b)) + if x == y: + print(f"{name} : identique") + continue + print(f"{name} : DIFFÉRENT") + for la, lb in zip_longest(x.splitlines(), y.splitlines(), fillvalue=""): + if la != lb: + i = next((k for k, (c, d) in enumerate(zip(la, lb)) if c != d), min(len(la), len(lb))) + print(f" avant : {la[max(0, i - 60):i + 140]}\n après : {lb[max(0, i - 60):i + 140]}") +``` + +- [ ] **Step 3 : générer les pages actuelles** + +Le `out/` existant (pages générées, ignoré par git) est mis de côté, pas supprimé. + +```bash +cd /home/maxime/Support-Agent && mv out $S/out-orig +export PATH="$S/fakebin:$PATH" +python3 src/analyse_01.py && python3 src/focus_jour.py 27.09 && python3 maquettes/user/energy.py && python3 maquettes/support/home.py +cp -r out $S/before && ls $S/before +``` + +Attendu : 7 fichiers, `VERMONT_daily.html`, `VERMONT_daily.json`, `VERMONT_energy.html`, `VERMONT_focus_2026-09-27.html`, `VERMONT_focus_2026-09-27.json`, `maquette_support_home.html` et `maquette_user_energy.html`. + +- [ ] **Step 4 : contrôle du script de comparaison** + +Run : `python3 $S/compare.py $S/before $S/before` +Attendu : 7 lignes `identique`. + +--- + +### Task 2 : Code dans `src/common/` et `src/energy/`, maquettes recâblées + +**Files:** +- Move : `src/energy_check.py` → `src/energy/moving_average.py` ; `src/energy_plot.py` → `src/energy/daily.py` ; `src/battery_state.py`, `src/battery_trend.py`, `src/day_color.py`, `src/focus_jour.py` → `src/energy/` +- Create : `src/common/stations.py`, `src/common/page.py`, `src/energy/all_analyses.py` +- Delete : `src/analyse_01.py`, `src/analyse_02.py`, `src/analyse_03.py`, `src/analyse_04.py` +- Modify : `maquettes/user/energy.py`, `maquettes/user/energy_template.html` (commentaires), `maquettes/support/home.py` + +**Interfaces:** +- Consomme : `$S/fakebin`, `$S/compare.py` et `$S/before/` (tâche 1). +- Produit : + - `common.stations` : `NAME_RE`, `parse_name(path)`, `load_csv(path)`, `load_stations(paths) -> {station: {metric: {datetime: float|None}}}`, `gaps(v) -> [(début, fin)]` ; + - `common.page` : `ROOT: Path`, `VENV`, `AUTOSCALE_Y_JS: str`, `open_html(path)` (bascule `.venv` à l'import) ; + - `energy.moving_average` : `run`, `run_midnight`, `_ma_drop`, `periods`, `RULE`, `RULE_MIDNIGHT` et les constantes ; + - `energy.daily` : `STATE_STYLE`, `TREND_STYLE`, `noon(day)`, `daily_state_panel(fig, result, row)`, `daily_trend_panel(fig, result, row)`, `daily_figure(station, series)`, `main(paths) -> [Path]` ; + - `energy.all_analyses` : `ZONES`, `figure(station, series, results)`, `main(paths) -> [Path]`. + +- [ ] **Step 1 : copier les sources à découper, puis déplacer** + +```bash +cd /home/maxime/Support-Agent && mkdir -p $S/old && cp src/energy_check.py src/energy_plot.py src/analyse_01.py $S/old/ +mkdir -p src/common src/energy +git mv src/energy_check.py src/energy/moving_average.py +git mv src/energy_plot.py src/energy/daily.py +git mv src/battery_state.py src/battery_trend.py src/day_color.py src/focus_jour.py src/energy/ +git rm -q src/analyse_01.py src/analyse_02.py src/analyse_03.py src/analyse_04.py +``` + +- [ ] **Step 2 : vérifier les bornes des blocs à découper** + +Run : +```bash +sed -n '17p;49,51p;92p;95p;175p' $S/old/energy_check.py; echo ==; sed -n '15p;49p;52p;59,61p;142p;145p;156p;159p;206p' $S/old/energy_plot.py +``` +Attendu : +- `energy_check.py` : `HOUR = timedelta(hours=1)`, `}`, ligne vide, `NAME_RE = …`, ` return stations`, `def run(series):` et ` return out` ; +- `energy_plot.py` : `# Plotly ne recale pas…`, `"""`, `# Zones de BusVoltage…`, `]`, ligne vide, `# États de DAILY_BATTERY_STATE…`, ` return fig`, `def gaps(v):`, ` return out`, `def figure(…` et ` return fig`. + +Si une borne a bougé, corriger les plages de l'étape 3 avant de lancer quoi que ce soit. + +- [ ] **Step 3 : assembler les nouveaux fichiers (`$S/assemble.py`)** + +```python +"""Découpe energy_check.py et energy_plot.py (copies dans $S/old) en modules ; plages 1-indexées, bornes incluses.""" +import sys +from pathlib import Path + +OLD, SRC = Path(sys.argv[1]), Path(sys.argv[2]) +check = (OLD / "energy_check.py").read_text().splitlines() +plot = (OLD / "energy_plot.py").read_text().splitlines() +cut = lambda lines, a, b: "\n".join(lines[a - 1:b]) # noqa: E731 + +SCRIPT_HEAD = '''import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) # src/ : paquets common et energy +''' + +(SRC / "common" / "stations.py").write_text('''"""Chargement des exports CSV des stations, commun à tous les domaines. + +Format des CSV : docs/domaine/ce-que-mesure-la-station.md. Bibliothèque standard uniquement. +""" +import csv +import glob +import os +import re +import sys +from datetime import datetime + +''' + cut(check, 51, 92) + "\n\n\n" + cut(plot, 145, 156).replace("sans BusVoltage", "sans mesure") + "\n") + +(SRC / "common" / "page.py").write_text('''"""Pages HTML du poste de dev : bascule sur .venv si plotly manque, ouverture dans le navigateur, zoom (D-013). + +À importer avant plotly : si plotly n'est pas installé, l'import relance le script sous .venv/bin/python. +""" +import importlib.util +import os +import shutil +import subprocess +import sys +import webbrowser +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +VENV = ROOT / ".venv" / "bin" / "python" +if importlib.util.find_spec("plotly") is None and VENV.exists(): + os.execv(VENV, [str(VENV), *sys.argv]) # plotly n'est installé que dans .venv + +''' + cut(plot, 15, 49) + ''' + + +def open_html(path): + if shutil.which("explorer.exe") and shutil.which("wslpath"): # WSL : navigateur Windows + subprocess.run(["explorer.exe", subprocess.check_output(["wslpath", "-w", path], text=True).strip()]) + else: + webbrowser.open(Path(path).resolve().as_uri()) +''') + +(SRC / "energy" / "moving_average.py").write_text('''"""Tendance de BusVoltage en moyenne glissante sur 7 jours (comparaison seulement, non livrée : D-020). + +- MOVING_AVERAGE_7_DAYS_DROP (docs/energy/analyses/moving_average_7_days_drop.md) : sur toutes les heures ; +- MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP (docs/energy/analyses/moving_average_7_days_midnight_utc_drop.md) : + le même calcul sur la seule mesure de 00:00 UTC. +Bibliothèque standard uniquement (cible : système embarqué de la station). +""" +import math +from datetime import timedelta + +''' + cut(check, 17, 50) + "\n\n" + cut(check, 95, 175) + "\n") + +(SRC / "energy" / "daily.py").write_text('''"""Analyses livrées (D-020) : DAILY_BATTERY_STATE et DAILY_BATTERY_TREND, en une figure pour le site (D-021). + +Usage : python3 src/energy/daily.py [CSV ou dossiers...] (défaut : data/) +Écrit out/_daily.html (page de démo) et .json (figure Plotly pour le site, Plotly.newPlot), puis les ouvre. +Documentation : docs/energy/analyses/daily_battery_state.md et daily_battery_trend.md +""" +''' + SCRIPT_HEAD + '''from datetime import datetime, time, timezone # noqa: E402 + +from common.page import AUTOSCALE_Y_JS, ROOT, open_html # noqa: E402 (bascule seule sur .venv si plotly manque) +from common.stations import load_stations # noqa: E402 +from plotly.subplots import make_subplots # noqa: E402 +from energy import battery_state as bs, battery_trend as bt # noqa: E402 + +''' + cut(plot, 61, 142) + ''' + + +def main(paths): + """Pour chaque station qui a BusVoltage : out/_daily.html et .json. -> chemins écrits.""" + (ROOT / "out").mkdir(exist_ok=True) + written = [] + for station, series in sorted(load_stations(paths).items()): + if "BusVoltage" not in series: + print(f"{station} : ignorée, pas de BusVoltage") + continue + path = ROOT / "out" / f"{station}_daily.html" + fig = daily_figure(station, series) + fig.write_html(path, include_plotlyjs="cdn", post_script=AUTOSCALE_Y_JS, config={"scrollZoom": True}) + fig.write_json(path.with_suffix(".json")) + print(path) + written.append(path) + return written + + +if __name__ == "__main__": + for p in main(sys.argv[1:] or [str(ROOT / "data")]): + open_html(p) +''') + +(SRC / "energy" / "all_analyses.py").write_text('''"""Les quatre analyses Energy ensemble, pour les comparer (D-016) : un panneau chacune, puis un graphique par série. + +Usage : python3 src/energy/all_analyses.py [CSV ou dossiers...] (défaut : data/) +Écrit out/_energy.html et l'ouvre. Documentation : docs/energy/analyses/ (une fiche par analyse) +""" +''' + SCRIPT_HEAD + '''from common.page import AUTOSCALE_Y_JS, ROOT, open_html # noqa: E402 (bascule seule sur .venv si plotly manque) +from common.stations import gaps, load_stations # noqa: E402 +from plotly.subplots import make_subplots # noqa: E402 +from energy import battery_state as bs, battery_trend as bt, moving_average as ma # noqa: E402 +from energy.daily import daily_state_panel, daily_trend_panel # noqa: E402 + +''' + cut(plot, 52, 59) + "\n\n\n" + cut(plot, 159, 206).replace("ec.periods(", "ma.periods(") + ''' + + +def main(paths): + """Pour chaque station qui a BusVoltage : out/_energy.html. -> chemins écrits.""" + (ROOT / "out").mkdir(exist_ok=True) + written = [] + for station, series in sorted(load_stations(paths).items()): + if "BusVoltage" not in series: + print(f"{station} : ignorée, pas de BusVoltage") + continue + path = ROOT / "out" / f"{station}_energy.html" + results = [ma.run(series), ma.run_midnight(series), bs.run(series), bt.run(series)] + figure(station, series, results).write_html(path, include_plotlyjs="cdn", post_script=AUTOSCALE_Y_JS, + config={"scrollZoom": True}) + print(path) + written.append(path) + return written + + +if __name__ == "__main__": + for p in main(sys.argv[1:] or [str(ROOT / "data")]): + open_html(p) +''') +``` + +Run : `python3 $S/assemble.py $S/old src && git add src/common src/energy` + +`daily.py` reçoit `STATE_STYLE` … `daily_figure` (lignes 61-142). `ZONES`, `gaps`, `figure`, `main` et `AUTOSCALE_Y_JS` vont ailleurs, et l'ancien en-tête (lignes 1-14) disparaît. Le contenu que `git mv` avait placé dans `daily.py` et `moving_average.py` est remplacé par l'assemblage ; git suit quand même le renommage s'il reste assez de contenu commun. + +- [ ] **Step 4 : imports et références des modules de calcul** + +Dans `src/energy/battery_trend.py`, remplacer `import battery_state as bs` par `from energy import battery_state as bs`. + +Dans `src/energy/day_color.py`, remplacer : +```python +import battery_state as bs +import battery_trend as bt +``` +par : +```python +from energy import battery_state as bs, battery_trend as bt +``` + +Puis appliquer les chemins et les noms (commentaires, docstrings, champs `"doc"`) aux quatre modules de calcul et à `focus_jour.py` : +```bash +cd /home/maxime/Support-Agent/src/energy && sed -i \ + -e 's#docs/analyses/analyse_01.md#docs/energy/analyses/moving_average_7_days_drop.md#g' \ + -e 's#docs/analyses/analyse_02.md#docs/energy/analyses/moving_average_7_days_midnight_utc_drop.md#g' \ + -e 's#docs/analyses/analyse_03.md#docs/energy/analyses/daily_battery_state.md#g' \ + -e 's#docs/analyses/analyse_04.md#docs/energy/analyses/daily_battery_trend.md#g' \ + -e 's#docs/guide/diagnostic-energetique.md#docs/energy/guide/diagnostic-energetique.md#g' \ + -e 's#fiche analyse_01#fiche moving_average_7_days_drop#g;s#fiche analyse_02#fiche moving_average_7_days_midnight_utc_drop#g' \ + -e 's#fiche analyse_03#fiche daily_battery_state#g;s#fiche analyse_04#fiche daily_battery_trend#g' \ + -e 's#(fiche 04)#(fiche daily_battery_trend)#g' \ + -e 's#cas-d-usage-03-04.drawio#docs/energy/matrice-etat-tendance.drawio#g' \ + -e 's#docs/domaine/\(comment-se-comporte-la-batterie\|tensions-selon-l-etat-de-la-batterie\|cas-annotes-par-l-expert\)#docs/energy/domaine/\1#g' \ + moving_average.py battery_state.py battery_trend.py day_color.py focus_jour.py daily.py all_analyses.py +``` + +Remplacements exacts restants : +- `battery_state.py` : + - ligne 1 : `"""Analyse 03 DAILY_BATTERY_STATE : état…` → `"""DAILY_BATTERY_STATE : état…` ; + - `(sans import d'energy_check : 03 et 04 se livrent seules)` → `(aucun import du projet : DAILY_BATTERY_STATE et DAILY_BATTERY_TREND se livrent seules)` ; + - `# repris de l'analyse 01 : 20 h mesurées sur 24` → `# repris de MOVING_AVERAGE_7_DAYS_DROP : 20 h mesurées sur 24`. +- `battery_trend.py`, ligne 1 : `"""Analyse 04 DAILY_BATTERY_TREND :` → `"""DAILY_BATTERY_TREND :`. +- `day_color.py` : + - `matrice état (analyse 03) × tendance (analyse 04)` → `matrice état (DAILY_BATTERY_STATE) × tendance (DAILY_BATTERY_TREND)` ; + - `causale comme les analyses 03 et 04` → `causale comme DAILY_BATTERY_STATE et DAILY_BATTERY_TREND`. +- `moving_average.py` : `# Analyse 02 : les mêmes constantes` → `# MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP : les mêmes constantes`. +- `daily.py` : + - `(analyses 03 et 04)` → `(DAILY_BATTERY_STATE et DAILY_BATTERY_TREND)` ; + - `analyse 03 en haut, analyse 04 dessous` → `DAILY_BATTERY_STATE en haut, DAILY_BATTERY_TREND dessous`. + +Run : `grep -n "analyse\|energy_check\|energy_plot\|import battery\|import day_color" src/energy/*.py src/common/*.py` +Attendu : seulement des mots courants (« analyses énergétiques », `Analyse {…}` dans un titre affiché), aucun ancien nom de fichier, aucun import relatif. + +- [ ] **Step 5 : `focus_jour.py`** + +Remplacer les lignes 1 à 16 (docstring et imports) par : +```python +"""Focus sur un jour : sa couleur (matrice état × tendance) et ce qui l'explique, sur le jour J et la veille seulement (D-024). + +Usage : python3 src/energy/focus_jour.py JJ.MM[.AAAA] [CSV ou dossiers...] (défaut : data/ ; sans année, celle des données) +Affiche le résumé des faits, écrit out/_focus_.html (+ .json, la figure Plotly pour le site) +et l'ouvre dans le navigateur. Textes du résumé et du graphique en anglais : destinés au site (D-023). +""" +import sys +from datetime import date, timedelta +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) # src/ : paquets common et energy +from common.page import ROOT, open_html # noqa: E402 (bascule seule sur .venv si plotly manque) +from common.stations import gaps, load_stations # noqa: E402 +import plotly.graph_objects as go # noqa: E402 +from energy import battery_state as bs, battery_trend as bt, day_color as dc # noqa: E402 +from energy.daily import STATE_STYLE, TREND_STYLE, noon # noqa: E402 +``` + +Puis : +```bash +cd /home/maxime/Support-Agent && sed -i -e 's/ep\.gaps(/gaps(/g;s/ep\.STATE_STYLE/STATE_STYLE/g;s/ep\.TREND_STYLE/TREND_STYLE/g;s/ep\.noon(/noon(/g;s/ec\.load_stations(/load_stations(/g' \ + -e 's/seuils de l.analyse 03/seuils de DAILY_BATTERY_STATE/;s/(comparaison de l.analyse 04)/(comparaison de DAILY_BATTERY_TREND)/' \ + -e 's/dashed: thresholds of the state (analysis 03)/dashed: thresholds of the daily state/;s/arrow: night end D-1 → D (trend, analysis 04)/arrow: night end D-1 → D (trend)/' \ + src/energy/focus_jour.py +grep -n "ep\.\|ec\.\|analys" src/energy/focus_jour.py +``` +Attendu : aucune ligne. + +- [ ] **Step 6 : maquettes** + +Dans `maquettes/user/energy.py`, remplacer : +```python +from analyse_01 import open_html # noqa: E402 (bascule seule sur .venv si plotly manque) +import battery_state as bs # noqa: E402 +import battery_trend as bt # noqa: E402 +import day_color as dc # noqa: E402 +import energy_check as ec # noqa: E402 +import energy_plot as ep # noqa: E402 +``` +par : +```python +from common.page import AUTOSCALE_Y_JS, open_html # noqa: E402 (bascule seule sur .venv si plotly manque) +from common.stations import load_stations # noqa: E402 +from energy import battery_state as bs, battery_trend as bt, day_color as dc # noqa: E402 +from energy.daily import daily_figure # noqa: E402 +``` + +Dans `maquettes/support/home.py`, remplacer : +```python +from analyse_01 import open_html # noqa: E402 +import day_color as dc # noqa: E402 +import energy_check as ec # noqa: E402 +``` +par : +```python +from common.page import open_html # noqa: E402 +from common.stations import load_stations # noqa: E402 +from energy import day_color as dc # noqa: E402 +``` + +Puis : +```bash +cd /home/maxime/Support-Agent && sed -i -e 's/ec\.load_stations(/load_stations(/;s/ep\.daily_figure(/daily_figure(/;s/ep\.AUTOSCALE_Y_JS/AUTOSCALE_Y_JS/' \ + -e 's#ROOT / "docs" / "guide" / "diagnostic-energetique.md"#ROOT / "docs" / "energy" / "guide" / "diagnostic-energetique.md"#' \ + -e 's#(src/day_color.py)#(src/energy/day_color.py)#;s#(energy_plot.daily_figure, D-021)#(energy.daily.daily_figure, D-021)#' maquettes/user/energy.py +sed -i -e 's/ec\.load_stations(/load_stations(/;s#(src/day_color.py, D-020)#(src/energy/day_color.py, D-020)#' maquettes/support/home.py +sed -i -e 's#figure des analyses 03 et 04 (D-021)#figure de DAILY_BATTERY_STATE et DAILY_BATTERY_TREND (D-021)#' \ + -e 's#docs/domaine/comment-se-comporte-la-batterie.md#docs/energy/domaine/comment-se-comporte-la-batterie.md#g' \ + -e 's#src/__main__ (3).py#docs/aimsight/collecteur_system_info.py#' maquettes/user/energy_template.html +grep -n "ec\.\|ep\.\|analyse_01\|energy_check\|energy_plot\|docs/guide\|docs/domaine/comment\|__main__ (3)" maquettes/*/* +``` +Attendu : aucune ligne. + +- [ ] **Step 7 : générer et comparer** + +```bash +cd /home/maxime/Support-Agent && rm -r out # pages de l'étape 1.3, déjà copiées dans $S/before +export PATH="$S/fakebin:$PATH" +python3 src/energy/daily.py && python3 src/energy/all_analyses.py && python3 src/energy/focus_jour.py 27.09 \ + && python3 maquettes/user/energy.py && python3 maquettes/support/home.py +cp -r out $S/after && python3 $S/compare.py $S/before $S/after +``` +Attendu : +- `identique` pour `VERMONT_daily.html`, `VERMONT_daily.json`, `VERMONT_energy.html` et `maquette_support_home.html` ; +- `DIFFÉRENT` pour `VERMONT_focus_2026-09-27.html` et `.json`, sur le seul sous-titre (`thresholds of the daily state`, `(trend)`) ; +- `DIFFÉRENT` pour `maquette_user_energy.html`, sur les seuls commentaires JS du template (figure DAILY_…, `docs/energy/domaine/…`, `docs/aimsight/collecteur_system_info.py`). + +Toute autre différence : s'arrêter et en trouver la cause. + +- [ ] **Step 8 : le code de calcul s'importe seul (embarquable)** + +```bash +cd /home/maxime/Support-Agent && /usr/bin/python3 -I -c "import sys; sys.path.insert(0, 'src'); from energy import moving_average, battery_state, battery_trend, day_color; print('ok', 'plotly' in sys.modules, 'common' in sys.modules)" +grep -n "common\|plotly" src/energy/moving_average.py src/energy/battery_state.py src/energy/battery_trend.py src/energy/day_color.py +``` +Attendu : `ok False False`, et aucune ligne trouvée par `grep`. + +- [ ] **Step 9 : Review Focus (autre dossier, autres données)** + +```bash +cd /tmp && python3 /home/maxime/Support-Agent/src/energy/daily.py /home/maxime/Support-Agent/data/archive +ls /home/maxime/Support-Agent/out/*_daily.json +cd /home/maxime/Support-Agent && rm out/FLORIDA_daily.* out/JUNGFRAU_daily.* out/MISSISSIPPI_daily.* out/WILDSTRUBEL_daily.* +``` +Attendu : 4 pages écrites dans `/home/maxime/Support-Agent/out/` (FLORIDA, JUNGFRAU, MISSISSIPPI, WILDSTRUBEL), et pas dans `/tmp/out`. Aucun plantage. Les fichiers créés sont ensuite retirés. + +--- + +### Task 3 : Documents déplacés et mis à jour + +**Files:** +- Move : + - `doc/*` → `docs/aimsight/` (la roadmap sans « (2) ») ; + - `docs/analyses/analyse_0N.md` → `docs/energy/analyses/.md` ; + - `docs/analyses/_modele.md` → `.claude/skills/nouvelle-analyse/modele-fiche.md` ; + - `docs/guide/` → `docs/energy/guide/` ; + - 3 notes de `docs/domaine/` → `docs/energy/domaine/` ; + - `cas-d-usage-03-04.drawio` → `docs/energy/matrice-etat-tendance.drawio` ; + - `src/__main__ (3).py` → `docs/aimsight/collecteur_system_info.py`. +- Modify : `CLAUDE.md`, `README.md`, `.claude/rules/analyses.md`, `.claude/skills/nouvelle-analyse/SKILL.md`, `.claude/skills/nouvelle-analyse/modele-fiche.md`, les 4 fiches, le manuel, les notes de `docs/domaine/` et `docs/energy/domaine/`, `docs/decisions.md`. + +**Interfaces:** +- Consomme : les chemins du code de la tâche 2 (`src/energy/daily.py`, `all_analyses.py`, `focus_jour.py`, `src/common/`). + +- [ ] **Step 1 : déplacements** + +```bash +cd /home/maxime/Support-Agent && mkdir -p docs/aimsight docs/energy/analyses docs/energy/domaine +git mv "doc/AIMsight FAQ.pdf" "doc/AIMsight Test Manual.pdf" doc/AIMsight_agentic_support_project_context.md docs/aimsight/ +git mv "doc/AIMsight_reference_quality_event_explainer_roadmap (2).md" docs/aimsight/AIMsight_reference_quality_event_explainer_roadmap.md +git mv "src/__main__ (3).py" docs/aimsight/collecteur_system_info.py +git mv docs/analyses/analyse_01.md docs/energy/analyses/moving_average_7_days_drop.md +git mv docs/analyses/analyse_02.md docs/energy/analyses/moving_average_7_days_midnight_utc_drop.md +git mv docs/analyses/analyse_03.md docs/energy/analyses/daily_battery_state.md +git mv docs/analyses/analyse_04.md docs/energy/analyses/daily_battery_trend.md +git mv docs/analyses/_modele.md .claude/skills/nouvelle-analyse/modele-fiche.md +git mv docs/guide docs/energy/guide +git mv docs/domaine/comment-se-comporte-la-batterie.md docs/domaine/tensions-selon-l-etat-de-la-batterie.md docs/domaine/cas-annotes-par-l-expert.md docs/energy/domaine/ +git mv cas-d-usage-03-04.drawio docs/energy/matrice-etat-tendance.drawio +ls doc docs/analyses 2>&1; git status --short | head -40 +``` +Attendu : `doc` et `docs/analyses` n'existent plus, et toutes les lignes de `git status` sont des `R` (renommages). + +- [ ] **Step 2 : chemins dans les documents vivants** + +Ni `docs/decisions.md`, ni `docs/superpowers/`, ni `docs/aimsight/` : ce sont des historiques ou des originaux. +```bash +cd /home/maxime/Support-Agent && FILES="CLAUDE.md README.md .claude/rules/analyses.md .claude/skills/nouvelle-analyse/SKILL.md .claude/skills/nouvelle-analyse/modele-fiche.md $(ls docs/energy/analyses/*.md docs/energy/guide/*.md docs/energy/domaine/*.md docs/domaine/*.md)" +sed -i \ + -e 's#docs/analyses/analyse_01.md#docs/energy/analyses/moving_average_7_days_drop.md#g' \ + -e 's#docs/analyses/analyse_02.md#docs/energy/analyses/moving_average_7_days_midnight_utc_drop.md#g' \ + -e 's#docs/analyses/analyse_03.md#docs/energy/analyses/daily_battery_state.md#g' \ + -e 's#docs/analyses/analyse_04.md#docs/energy/analyses/daily_battery_trend.md#g' \ + -e 's#docs/analyses/_modele.md#.claude/skills/nouvelle-analyse/modele-fiche.md#g' \ + -e 's#docs/guide/diagnostic-energetique.md#docs/energy/guide/diagnostic-energetique.md#g' \ + -e 's#docs/domaine/comment-se-comporte-la-batterie.md#docs/energy/domaine/comment-se-comporte-la-batterie.md#g' \ + -e 's#docs/domaine/tensions-selon-l-etat-de-la-batterie.md#docs/energy/domaine/tensions-selon-l-etat-de-la-batterie.md#g' \ + -e 's#docs/domaine/cas-annotes-par-l-expert.md#docs/energy/domaine/cas-annotes-par-l-expert.md#g' \ + -e 's#src/__main__ (3).py#docs/aimsight/collecteur_system_info.py#g' \ + -e 's#doc/AIMsight_reference_quality_event_explainer_roadmap (2).md#docs/aimsight/AIMsight_reference_quality_event_explainer_roadmap.md#g' \ + -e 's#\bdoc/#docs/aimsight/#g' \ + -e 's#`cas-d-usage-03-04.drawio`#`docs/energy/matrice-etat-tendance.drawio`#g' \ + $FILES +``` + +- [ ] **Step 3 : `docs/decisions.md`** + +- Dans l'entrée D-006, la ligne Statut `- **Statut** : active.` devient `- **Statut** : remplacée par D-026.` +- Dans D-010, `- **Statut** : active, complétée par D-012.` devient `- **Statut** : active, complétée par D-012 ; remplacée en partie par D-026 (chemin des fiches).` +- Dans D-012, `- **Statut** : active. Complète D-010.` devient `- **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`).` +- Ajouter en fin de fichier l'entrée D-026, recopiée de la section « Texte de D-026 » de la spec, sans les `> ` de citation et précédée d'une ligne vide. + +- [ ] **Step 4 : les quatre fiches** + +Dans chaque fiche : +- **Titre** : `# Analyse 0N — \`RÈGLE\` : …` devient `# \`RÈGLE\` : …`. +- **Lignes `- **Script** :` et `- **Code** :`** (avec leurs sous-points) : elles sont remplacées par les blocs ci-dessous. +- **Texte vivant** (tout sauf « Historique ») : remplacer les numéros, en accordant la phrase. + - « l'analyse 01 » ou « analyse 01 » devient `MOVING_AVERAGE_7_DAYS_DROP` ; même chose pour 02 (`MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP`), 03 (`DAILY_BATTERY_STATE`) et 04 (`DAILY_BATTERY_TREND`) ; + - « fiche `analyse_03.md` » et « fiche analyse_03 » deviennent « fiche `daily_battery_state.md` », et ainsi de suite. +- **Historique** : ajouter la ligne `- **2026-10-12** : fiche renommée d'après la règle (ex-\`analyse_0N.md\`) et déplacée dans \`docs/energy/analyses/\` ; code dans \`src/energy/\` (D-026). Calcul inchangé.` + +`moving_average_7_days_drop.md` : +```markdown +- **Script** : `python3 src/energy/all_analyses.py [CSV ou dossiers]` (défaut : `data/`). Il écrit `out/_energy.html` et l'ouvre dans le navigateur. Cette analyse est le premier panneau, et `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` est juste dessous (D-016). Elle sert à la comparaison seulement : elle n'est pas livrée (D-020). +- **Code** : + - `src/energy/moving_average.py` : calcul, bibliothèque standard uniquement. `run()` appelle `_ma_drop()`, commun avec `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP`. Les séries sont chargées par `common.stations.load_stations` ; + - `src/energy/all_analyses.py` : graphique plotly. +``` +Le paragraphe qui commence par `` `python3 src/energy_check.py data/` produit en plus `` devient : `Le résumé texte et \`out/_energy.json\` ont été supprimés (D-026) ; les périodes d'anomalie restent visibles, en rouge, sur la page.` + +`moving_average_7_days_midnight_utc_drop.md` : +```markdown +- **Script** : `python3 src/energy/all_analyses.py [CSV ou dossiers]` (défaut : `data/`). Il écrit `out/_energy.html`, où cette analyse est le panneau placé sous `MOVING_AVERAGE_7_DAYS_DROP` (D-016). Elle sert à la comparaison seulement : elle n'est pas livrée (D-020). +- **Code** : + - `src/energy/moving_average.py` : `run_midnight()` et `RULE_MIDNIGHT`, bibliothèque standard uniquement. Le calcul est celui de `MOVING_AVERAGE_7_DAYS_DROP` (`_ma_drop()`, commun aux deux analyses) ; + - `src/energy/all_analyses.py` : graphique plotly. +``` +La limite `**Pas de résumé texte ni de JSON** : …` devient : `**Pas de résumé texte ni de JSON** : supprimés pour les deux moyennes glissantes (D-026).` + +`daily_battery_state.md` : +```markdown +- **Script** : `python3 src/energy/daily.py [CSV ou dossiers]` (défaut : `data/`). Il écrit la page livrée, `out/_daily.html` + `.json`, dont cette analyse est le panneau du haut (D-021), et l'ouvre dans le navigateur. Elle est aussi le troisième panneau de `python3 src/energy/all_analyses.py` (comparaison, D-016). +- **Code** : + - `src/energy/battery_state.py` : calcul, bibliothèque standard uniquement (`run()`, `day_facts()`). Il reçoit les séries chargées par `common.stations.load_stations`, mais n'importe rien d'autre du projet : avec `src/energy/battery_trend.py`, il se livre seul à la plateforme (D-021) ; + - `src/energy/daily.py` : graphique plotly. +``` + +`daily_battery_trend.md` : +```markdown +- **Script** : `python3 src/energy/daily.py [CSV ou dossiers]` (défaut : `data/`). Il écrit la page livrée, `out/_daily.html` + `.json`, dont cette analyse est le panneau du bas (D-021), et l'ouvre dans le navigateur. Elle est aussi le quatrième panneau de `python3 src/energy/all_analyses.py` (comparaison, D-016). +- **Code** : + - `src/energy/battery_trend.py` : calcul, bibliothèque standard uniquement (`run()`). Il s'appuie sur `battery_state.run()` (`DAILY_BATTERY_STATE`) ; + - `src/energy/daily.py` : graphique plotly. +``` + +Contrôle : +```bash +grep -n "analyse 0\|analyse_0\|fiche 0\|energy_check\|energy_plot\|src/analyse" docs/energy/analyses/*.md +``` +Attendu : des lignes dans « Historique » seulement. + +- [ ] **Step 5 : le manuel (`docs/energy/guide/diagnostic-energetique.md`)** + +- **Ligne 3** : `calculée par \`src/day_color.py\`` devient `calculée par \`src/energy/day_color.py\``. Le chemin `.drawio` a déjà été traité à l'étape 2. +- **§ 4** : + - `- l'**état** du jour (analyse 03, \`DAILY_BATTERY_STATE\`) ;` devient `- l'**état** du jour (\`DAILY_BATTERY_STATE\`) ;` ; + - même chose pour la tendance (`DAILY_BATTERY_TREND`). +- **Titres** : + - `## 5. L'état du jour (analyse 03)` devient `` ## 5. L'état du jour (`DAILY_BATTERY_STATE`) `` ; + - `## 6. La tendance (analyse 04)` devient `` ## 6. La tendance (`DAILY_BATTERY_TREND`) ``. +- **§ 8** : `Commande : \`python3 src/analyse_03.py\`. Elle écrit deux pages dans \`out/\` et les ouvre dans le navigateur.` devient : + `Commandes : \`python3 src/energy/daily.py\` écrit la page livrée, \`python3 src/energy/all_analyses.py\` la page de comparaison ; chacune est écrite dans \`out/\` et ouverte dans le navigateur.` +- **Puce `_energy.html`** : `la page de toutes les analyses, avec ces deux panneaux, et une courbe par mesure dessous.` devient `la page de comparaison des quatre analyses (\`all_analyses.py\`), avec ces deux panneaux, et une courbe par mesure dessous.` +- **Focus** : `python3 src/focus_jour.py 27.09` devient `python3 src/energy/focus_jour.py 27.09`. +- **Langue et panneaux** : + - `des panneaux 03 et 04` devient `des panneaux \`DAILY_BATTERY_STATE\` et \`DAILY_BATTERY_TREND\`` ; + - `**Les panneaux 01 et 02** (moyennes sur 7 jours), en haut de la page,` devient `**Les panneaux \`MOVING_AVERAGE_*\`** (moyennes sur 7 jours), en haut de la page de comparaison,` ; + - `**Panneau \`DAILY_BATTERY_STATE\`** (analyse 03),` devient `**Panneau \`DAILY_BATTERY_STATE\`**,` ; + - `**Panneau \`DAILY_BATTERY_TREND\`** (analyse 04),` devient `**Panneau \`DAILY_BATTERY_TREND\`**,`. + +Contrôle : `grep -n "analyse 0\|analyses 0\|panneaux 0\|src/analyse\|src/focus\|src/day" docs/energy/guide/diagnostic-energetique.md` +Attendu : aucune ligne. + +- [ ] **Step 6 : `.claude/rules/analyses.md`** (texte complet) + +```markdown +--- +paths: + - "src/**" + - "docs/*/analyses/**" +--- + +# Travailler sur une analyse + +- **Avant de modifier** une analyse, lire sa fiche `docs//analyses/.md` (ex. `docs/energy/analyses/daily_battery_state.md`). En particulier : + - le principe ; + - les constantes et leurs sources ; + - les limites connues ; + - les **options écartées** (ne pas les reproposer sans raison nouvelle). +- **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 : `DAILY_BATTERY_STATE` en phase C et `DAILY_BATTERY_TREND`, où `None` = pas de verdict ; l'UNKNOWN est dans `facts.state` ou `facts.trend`) ; + - une analyse seule conclut au plus `consistent with`. +- **Code de calcul** (`src//`) : bibliothèque standard uniquement et aucun import de `src/common/`, car il doit tourner sur la station. Plotly ne sert qu'aux graphiques, sur le poste de dev (`.venv`). Le chargement des CSV est dans `common.stations`. +- **Constantes** : chacune a sa source, en commentaire dans le code et dans le tableau de la fiche. Aucun seuil sans source. +- **Graphique** : + - en haut, l'analyse avec ses courbes superposées ; dessous, un graphique par série temporelle (D-011). Des analyses à comparer partagent une page, un panneau chacune (D-016) : pour Energy, `src/energy/all_analyses.py` ; + - zoom horizontal seulement, avec l'ordonnée recalée sur la plage visible (`post_script=common.page.AUTOSCALE_Y_JS`, ordonnées en `fixedrange`, D-013). +- **Après modification** : + - mettre à jour la fiche dans le même changement (résultats, limites, historique) ; + - si c'est une décision projet, ajouter une entrée dans `docs/decisions.md` ; + - si c'est un savoir métier nouveau, l'ajouter dans `docs/domaine/` (commun) ou `docs//domaine/`. +- **Vérifier à la main** sur VERMONT (`data/`) : pour Energy, `python3 src/energy/all_analyses.py`, et `python3 src/energy/daily.py` si l'analyse est livrée. Pas de tests automatisés en phase prototype (D-008). +- **Nouvelle analyse** : utiliser le skill `nouvelle-analyse`. +``` + +- [ ] **Step 7 : skill `nouvelle-analyse`** + +Texte complet de `SKILL.md` : +```markdown +--- +name: nouvelle-analyse +description: Créer une nouvelle analyse dans le projet de diagnostic AIMsight — règle, fiche, code dans son domaine, panneau de comparaison, index, journal. À utiliser dès que l'utilisateur veut ajouter, concevoir ou prototyper une nouvelle analyse des séries temporelles d'une station. +--- + +# Créer une nouvelle analyse + +## 1. Situer l'analyse + +- **Domaine** : Energy (`src/energy/`, `docs/energy/`) ou un nouveau domaine, qui reçoit alors son propre `src//` et `docs//` (D-026). Le demander à l'utilisateur en cas de doute. +- **Nom de la règle** : en anglais, en majuscules, **en mots complets sans abréviation** (ex. `MOVING_AVERAGE_7_DAYS_DROP`, D-017). Les analyses ne sont pas numérotées : le nom de la règle les désigne (D-026). +- Lire, sans tout charger : + - les « Pistes » et les « Limites connues » des fiches du domaine (`docs//analyses/`). La nouvelle analyse en couvre souvent une ; + - `docs/decisions.md`, en particulier les options écartées ; + - la note de `docs/domaine/` ou de `docs//domaine/` qui concerne la question posée. +- Si la conception demande des choix, en discuter avec l'utilisateur. Avec superpowers (brainstorming), **la spec s'écrit directement dans la fiche**, pas dans `docs/superpowers/specs/` (D-010). + +## 2. Écrire la fiche + +- Copier `modele-fiche.md` (à côté de ce fichier) vers `docs//analyses/.md` (ex. `daily_battery_state.md`) et remplir : + - la question posée ; + - le principe et le calcul exact ; + - les constantes **avec leur source** ; + - les options écartées. +- Statut : « en conception ». + +## 3. Écrire le code + +- Le calcul respecte le contrat commun : `run(series) -> {analysis, rule, points: [{t, value, anomaly, facts}]}`. + - Il est causal. + - Il utilise uniquement la bibliothèque standard, sans importer `src/common/` : il doit pouvoir s'embarquer seul. + - `value` est exprimé dans une unité physique, sans pseudo-probabilité. + - Une analyse seule conclut au plus `consistent with`. +- Le module va dans `src//`. Les séries arrivent par `common.stations.load_stations`. Extraire du code partagé seulement quand une deuxième analyse en a vraiment besoin. +- **Pas de point d'entrée par analyse** : ajouter le panneau de l'analyse à la page de comparaison du domaine (pour Energy, `figure()` et `main()` de `src/energy/all_analyses.py`). Si l'analyse devient livrée, elle rejoint aussi la page livrée (pour Energy, `src/energy/daily.py`). +- Graphique (D-011) : en haut, l'analyse avec ses courbes superposées ; dessous, un graphique par série temporelle. Écrire le HTML avec `post_script=common.page.AUTOSCALE_Y_JS` et des ordonnées en `fixedrange`, pour que l'ordonnée se recale à chaque zoom. +- Pas de tests automatisés en phase prototype (D-008). + +## 4. Vérifier + +- Lancer la page de comparaison du domaine sur VERMONT (pour Energy, `python3 src/energy/all_analyses.py`). +- Comparer les résultats au diagnostic expert (`docs/energy/domaine/cas-annotes-par-l-expert.md`). +- Reporter les dates et valeurs observées dans la section « Résultats » de la fiche. + +## 5. Documenter + +- Fiche : statut « prototype en place », résultats, limites, historique. +- `CLAUDE.md` : + - ajouter une ligne au tableau des analyses du domaine ; + - mettre à jour « État et prochaine étape ». +- `docs/decisions.md` : une entrée **seulement** si une décision de niveau projet a été prise (nouveau principe, changement de cap, nouveau domaine). Les choix propres à l'analyse restent dans sa fiche. +- Un savoir métier découvert en chemin va dans `docs/domaine/` (commun) ou `docs//domaine/`. +``` + +Dans `modele-fiche.md`, remplacer les quatre premières lignes (titre, Statut, Script, Code) par : +```markdown +# `NOM_DE_LA_REGLE` : titre court + +- **Statut** : idée | en conception | prototype en place | livrée | comparaison seulement | abandonnée (date). +- **Script** : la page qui montre l'analyse. Pour Energy : son panneau dans `python3 src/energy/all_analyses.py [CSV ou dossiers]` (défaut : `data/`), et dans `python3 src/energy/daily.py` si elle est livrée. La page est écrite dans `out/` et ouverte dans le navigateur. +- **Code** : les modules utilisés, dans `src//` ; le calcul est en bibliothèque standard uniquement. +``` +Contrôle : `grep -n "NN\|analyse_\|src/analyse" .claude/skills/nouvelle-analyse/*.md`. Attendu : aucune ligne. Toute occurrence restante doit être corrigée dans le même esprit. + +- [ ] **Step 8 : `CLAUDE.md` et `README.md`** + +Dans `CLAUDE.md` : + +**« État et prochaine étape »** : réécrire les puces avec les noms des règles, en gardant les dates et les faits : +- `l'analyse 01 est en place` devient `` `MOVING_AVERAGE_7_DAYS_DROP` est en place `` ; +- `Point ouvert de l'analyse 01` devient `` Point ouvert de `MOVING_AVERAGE_7_DAYS_DROP` `` ; +- `analyse 02 (\`MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP\`, suggestion d'un collègue) en place, en panneau sous la 01 pour comparer` devient `` `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` (suggestion d'un collègue) en place, en panneau sous la précédente pour comparer `` ; +- `contre ~2,7 jours pour la 01` devient `contre ~2,7 jours` ; +- `analyse 03 \`DAILY_BATTERY_STATE\` en place` devient `` `DAILY_BATTERY_STATE` en place `` ; +- `analyse 04 \`DAILY_BATTERY_TREND\` en place` devient `` `DAILY_BATTERY_TREND` en place `` ; +- `ne retient que les analyses 03 et 04` devient `` ne retient que `DAILY_BATTERY_STATE` et `DAILY_BATTERY_TREND` `` ; +- `panneau 03 en haut et 04 dessous` devient `l'état en haut et la tendance dessous` ; +- `figure 03 × 04 comprise` devient `figure état × tendance comprise` ; +- les chemins `src/day_color.py` et `src/focus_jour.py` passent sous `src/energy/`. + +Ajouter, avant « Prochaine étape » : +`- **2026-10-12 (D-026)** : projet rangé par domaine (\`src/energy/\`, \`docs/energy/\`, code commun dans \`src/common/\`, documentation AIMsight dans \`docs/aimsight/\`). Les analyses ne sont plus numérotées : chacune est désignée par sa règle. Deux scripts Energy : \`daily.py\` (analyses livrées) et \`all_analyses.py\` (comparaison).` + +**Section « Analyses »**, en entier : +```markdown +## Analyses (domaine Energy) + +| Règle | Question | Statut | Fiche | +|---|---|---|---| +| `DAILY_BATTERY_STATE` | Chaque jour : pleine charge, charge partielle (incertain), sous le plateau ou aucune charge ? | livrée (prototype, D-020) | `docs/energy/analyses/daily_battery_state.md` | +| `DAILY_BATTERY_TREND` | Chaque jour, face à la veille : mieux, stable ou pire (changement d'état, sinon écart de fin de nuit) ? | livrée (prototype, D-020) | `docs/energy/analyses/daily_battery_trend.md` | +| `MOVING_AVERAGE_7_DAYS_DROP` | La tension moyenne sur 7 jours décroche-t-elle de son propre passé récent (> 0,2 V) ? | comparaison seulement | `docs/energy/analyses/moving_average_7_days_drop.md` | +| `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` | Même question, sur la seule mesure de 00:00 UTC de chaque jour | comparaison seulement | `docs/energy/analyses/moving_average_7_days_midnight_utc_drop.md` | + +Pour créer une analyse : skill `nouvelle-analyse` (`.claude/skills/nouvelle-analyse/`). +``` + +**Section « Commandes »**, en entier : +```markdown +## Commandes + +- `python3 src/energy/daily.py [données]` : analyses livrées (`DAILY_BATTERY_STATE`, `DAILY_BATTERY_TREND`). Il écrit `out/_daily.html` + `.json` (figure pour le site, D-021) et les ouvre dans le navigateur (via `explorer.exe` sous WSL). Défaut : `data/`. Il bascule seul sur `.venv` si plotly manque, comme tous les scripts plotly. +- `python3 src/energy/all_analyses.py [données]` : les quatre analyses ensemble pour comparer (D-016), un panneau chacune, puis un graphique par série. Il écrit `out/_energy.html` et l'ouvre. +- `python3 src/energy/focus_jour.py 27.09` : focus sur un jour et sa veille (D-024). Il affiche les faits de la couleur et écrit `out/_focus_.html` + `.json`, puis l'ouvre. +- `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. +``` + +**Section « Documentation »** : +- la puce `docs/analyses/analyse_NN.md` devient `- \`docs//analyses/.md\` : fiche vivante de chaque analyse (principe, constantes et sources, résultats, limites, options écartées, historique). Modèle : \`.claude/skills/nouvelle-analyse/modele-fiche.md\`.` ; +- la puce `docs/domaine/` et ses sous-puces deviennent : +```markdown +- `docs/domaine/` : le savoir métier commun, une note par question. + - `ce-que-mesure-la-station.md` : format CSV, métriques et unités, consommation mesurée mais pas l'apport. + - `pieges-des-donnees.md` : trou ≠ coupure, signatures d'une coupure, seuils absolus, cycle jour/nuit. + - `colonnes-des-deplacements.md` : colonnes des déplacements (cas d'usage suivant). +- `docs/energy/domaine/` : le savoir métier Energy. + - `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). + - `cas-annotes-par-l-expert.md` : diagnostics experts des 5 stations. +``` +- la puce du manuel devient `- \`docs/energy/guide/diagnostic-energetique.md\` : manuel du diagnostic énergétique, pour le client (partie 1) et le support (partie 2). À tenir à jour avec la matrice (\`docs/energy/matrice-etat-tendance.drawio\`) et les fiches \`DAILY_BATTERY_STATE\` et \`DAILY_BATTERY_TREND\`.` ; +- dans la règle de travail, `un savoir métier nouveau va dans \`docs/domaine/\`` devient `un savoir métier nouveau va dans \`docs/domaine/\` (commun) ou \`docs//domaine/\`` ; +- `quand Claude touche \`src/\` ou \`docs/analyses/\`` devient `quand Claude touche \`src/\` ou \`docs/*/analyses/\`` ; +- dans la puce `docs/superpowers/`, la fiche devient `docs//analyses/.md`. + +**Section « Fichiers »** : +- la puce `doc/` et ses sous-puces deviennent : +```markdown +- `docs/aimsight/` : documentation AIMsight d'origine, à lire avant de concevoir. Ne pas re-demander à l'utilisateur ce qui y figure. Contenus non modifiés. + - `AIMsight_reference_quality_event_explainer_roadmap.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). + - `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 "docs/aimsight/.pdf" -`. + - `collecteur_system_info.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. +``` +- les puces `src/analyse_NN.py` et `src/__main__ (3).py` sont remplacées par : +```markdown +- `src/` : un sous-dossier par domaine, plus le code commun (D-026). + - `src/common/` : `stations.py` (chargement des CSV, trous de mesure ; bibliothèque standard) et `page.py` (poste de dev : bascule `.venv`, ouverture dans le navigateur, `AUTOSCALE_Y_JS`). + - `src/energy/` : calcul embarquable, en bibliothèque standard et sans import de `common/` : `moving_average.py`, `battery_state.py`, `battery_trend.py` et `day_color.py` (matrice, couleur du jour, focus J−1 / J). Scripts plotly du poste de dev : `daily.py`, `all_analyses.py` et `focus_jour.py`. +``` + +**Sections « Principes » et « Environnement »** : +- `exception : analyses 03 en phase C et 04` devient `` exception : `DAILY_BATTERY_STATE` en phase C et `DAILY_BATTERY_TREND` `` ; +- `en lançant \`python3 src/analyse_01.py\` sur VERMONT` devient `en lançant \`python3 src/energy/all_analyses.py\` (et \`daily.py\` pour le livré) sur VERMONT`. + +Dans `README.md` : +- la section « Lancer l'analyse » est remplacée par : +```markdown +## Lancer l'analyse + +```bash +python3 src/energy/daily.py +``` + +Le script analyse `data/` (station VERMONT) et ouvre dans le navigateur `out/VERMONT_daily.html`, l'état et la tendance de la batterie jour par jour : ce sont les analyses livrées, destinées au site de monitoring. La figure Plotly est aussi écrite dans `out/VERMONT_daily.json`. + +Pour comparer les quatre analyses Energy sur une même page (`out/VERMONT_energy.html`) : `python3 src/energy/all_analyses.py`. Pour comprendre la couleur d'un jour, en ne regardant que ce jour et la veille : `python3 src/energy/focus_jour.py 27.09`. +``` + `Le graphique se lit ainsi :` devient `La page de comparaison se lit ainsi :` (en haut les analyses, dessous les mesures, ce qui ne décrit pas la page livrée) ; le reste de ce paragraphe et celui sur Plotly restent tels quels. +- dans le tableau « Où trouver quoi » : + - `` `docs/guide/diagnostic-energetique.md` `` devient `` `docs/energy/guide/diagnostic-energetique.md` `` ; + - `` `docs/analyses/analyse_NN.md` `` devient `` `docs/energy/analyses/.md` `` ; + - `` `docs/domaine/` `` devient `` `docs/domaine/` (commun), `docs/energy/domaine/` `` ; + - `` `doc/` `` devient `` `docs/aimsight/` `` ; +- dans la section « État », `Quatre analyses sont en place : …` devient : `Quatre analyses Energy sont en place. Deux sont livrées : \`DAILY_BATTERY_STATE\`, l'état de la batterie jour par jour, et \`DAILY_BATTERY_TREND\`, sa tendance d'un jour à l'autre. Les deux autres servent à la comparaison : \`MOVING_AVERAGE_7_DAYS_DROP\` et sa variante sur la seule mesure de 00:00 UTC. Les suivantes sont listées dans les fiches \`docs/energy/analyses/\` (section « Pistes »).` + +Contrôle : `wc -l CLAUDE.md`. Attendu : moins de 200. + +- [ ] **Step 9 : références périmées** + +```bash +cd /home/maxime/Support-Agent && grep -rn "analyse_0\|analyse_NN\|energy_check\|energy_plot\|docs/analyses\|docs/guide\|\`doc/\|\"doc/\|__main__ (3)\|cas-d-usage-03-04\|src/battery\|src/day_color\|src/focus_jour\|docs/domaine/comment\|docs/domaine/tensions\|docs/domaine/cas-annotes\|analyse 0[1-4]\|analyses 0[1-4]" \ + --include=*.md --include=*.py --include=*.html . | grep -v "^./.venv\|^./docs/superpowers/\|^./docs/decisions.md\|^./docs/aimsight/" +``` +Attendu : rien, sauf des lignes « Historique » des fiches. Chaque ligne restante est corrigée, ou justifiée comme historique. + +Run : `grep -n "analyse 0\|analyse_0\|src/" docs/decisions.md | awk -F: '$1 > 250'` +Attendu : seule D-026 apparaît parmi les nouvelles lignes, et ses chemins sont les nouveaux. + +--- + +### Task 4 : Vérification finale et commit + +**Files:** +- Modify : rien (vérification), puis commit de l'ensemble. + +- [ ] **Step 1 : relancer les pages après les modifications de documents** + +Le manuel est lu par la maquette client : sa partie 1 a pu changer à la tâche 3. +```bash +cd /home/maxime/Support-Agent && rm -r out && export PATH="$S/fakebin:$PATH" +python3 src/energy/daily.py && python3 src/energy/all_analyses.py && python3 src/energy/focus_jour.py 27.09 && python3 maquettes/user/energy.py && python3 maquettes/support/home.py +rm -rf $S/final && cp -r out $S/final && python3 $S/compare.py $S/after $S/final +``` +Attendu : tout `identique`, sauf `maquette_user_energy.html` si la partie 1 du manuel a été touchée. La partie 1 ne cite ni chemin ni numéro, donc elle devrait rester identique ; toute différence doit venir du seul texte du guide. + +- [ ] **Step 2 : rendre l'ancien `out/` ?** + +Non : `$S/out-orig` contient les anciennes pages, régénérables. Le `out/` actuel les remplace, avec les mêmes noms. + +- [ ] **Step 3 : revue du diff** + +Run : `git status --short && git diff --cached --stat -M && git diff --stat` +Attendu : des renommages (`R`) pour les déplacements, 3 nouveaux fichiers (`src/common/stations.py`, `src/common/page.py`, `src/energy/all_analyses.py`), 4 suppressions (`analyse_0N.py`) et aucun fichier de `data/`, `docs/aimsight/` (contenus), `docs/superpowers/` (hors spec et plan) ou `architecture.drawio`. + +- [ ] **Step 4 : commit unique** + +```bash +cd /home/maxime/Support-Agent && git add -A src docs .claude CLAUDE.md README.md maquettes && git status --short +git commit -m "$(cat <<'EOF' +Organize the project by domain and name analyses by their rule + +Energy code moves to src/energy/ and its docs to docs/energy/; shared code +(CSV loading, venv switch, browser, zoom script) goes to src/common/, and the +AIMsight originals to docs/aimsight/. Analyses are no longer numbered: two +Energy scripts remain, daily.py (delivered state and trend) and +all_analyses.py (comparison of the four). Calculations and pages unchanged (D-026). + +Co-Authored-By: Claude Opus 5.5 +EOF +)" +git log --stat -1 | head -60 +``` diff --git a/docs/superpowers/specs/2026-10-12-structure-energy-design.md b/docs/superpowers/specs/2026-10-12-structure-energy-design.md new file mode 100644 index 0000000..1811755 --- /dev/null +++ b/docs/superpowers/specs/2026-10-12-structure-energy-design.md @@ -0,0 +1,211 @@ +# Structure du projet : Energy encapsulé, analyses désignées par leur règle + +- **Date** : 2026-10-12 +- **Statut** : design validé en conversation, spec à relire. +- **Décision projet qui en découle** : D-026 (texte en fin de document). + +## Objectif + +- Faire d'Energy un **domaine autonome** : le domaine suivant (déplacements, D-002) se range à côté, sans rien déplacer. +- Donner à chaque fichier une **place évidente** : + - le code commun hors des analyses ; + - la documentation AIMsight d'origine sous `docs/` ; + - plus de fichiers Energy à la racine. +- **Ne plus numéroter les analyses.** Energy a convergé : une analyse se désigne par sa règle (`DAILY_BATTERY_STATE`…). Il ne reste que deux scripts d'analyse : + - l'un met les quatre analyses ensemble, pour comparer ; + - l'autre ne montre que les deux analyses livrées (`DAILY_BATTERY_STATE`, `DAILY_BATTERY_TREND`, D-020). + +## Ce qui ne change pas + +- **Les calculs.** Aucune constante, aucune règle, aucun résultat ne change : on déplace et on recâble. +- **Les pages produites**, à deux exceptions près : + - le sous-titre du focus ne cite plus « analysis 03 / 04 » ; + - `out/_energy.json` n'est plus produit. + + Les noms des fichiers de `out/` sont inchangés. +- **Le code de calcul reste embarquable** : bibliothèque standard, et il ne dépend pas de `src/common/`. +- **Contenus intacts** : + - `architecture.drawio` (racine) ; + - les documents AIMsight et la copie du collecteur, qui sont déplacés ou renommés sans être modifiés ; + - `data/` ; + - `maquettes/`, dont seuls les imports et un chemin changent ; + - `docs/superpowers/`, un historique dont les anciens chemins restent tels quels. +- **Le journal des décisions** : on ajoute D-026 et on change seulement le statut des entrées remplacées. Le texte des anciennes entrées garde les numéros et les anciens chemins ; la table de correspondance de D-026 permet de les relire. + +## Arborescence cible + +| Avant | Après | +|---|---| +| `src/energy_check.py` (chargement des CSV) | `src/common/stations.py` | +| `src/energy_plot.py` : `gaps()` | `src/common/stations.py` | +| `src/analyse_01.py` (ROOT, bascule `.venv`, `open_html`) | `src/common/page.py` | +| `src/energy_plot.py` : `AUTOSCALE_Y_JS` | `src/common/page.py` | +| `src/energy_check.py` (analyses 01 et 02, `periods`) | `src/energy/moving_average.py` | +| `src/battery_state.py` | `src/energy/battery_state.py` | +| `src/battery_trend.py` | `src/energy/battery_trend.py` | +| `src/day_color.py` | `src/energy/day_color.py` | +| `src/energy_plot.py` : `STATE_STYLE`, `TREND_STYLE`, `noon`, panneaux état et tendance, `daily_figure` | `src/energy/daily.py` (script livré) | +| `src/energy_plot.py` : `ZONES`, `figure`, `main` | `src/energy/all_analyses.py` (script de comparaison) | +| `src/focus_jour.py` | `src/energy/focus_jour.py` | +| `src/analyse_01.py` … `analyse_04.py` | supprimés | +| `src/energy_check.py` : `summary`, `_unknown_line`, `_d`, `_v`, `main` (résumé texte) | supprimés | +| `src/__main__ (3).py` | `docs/aimsight/collecteur_system_info.py` | +| `doc/AIMsight FAQ.pdf`, `doc/AIMsight Test Manual.pdf`, `doc/AIMsight_agentic_support_project_context.md` | `docs/aimsight/` (mêmes noms) | +| `doc/AIMsight_reference_quality_event_explainer_roadmap (2).md` | `docs/aimsight/AIMsight_reference_quality_event_explainer_roadmap.md` (le doc de contexte la cite déjà sans « (2) ») | +| `docs/analyses/analyse_01.md` | `docs/energy/analyses/moving_average_7_days_drop.md` | +| `docs/analyses/analyse_02.md` | `docs/energy/analyses/moving_average_7_days_midnight_utc_drop.md` | +| `docs/analyses/analyse_03.md` | `docs/energy/analyses/daily_battery_state.md` | +| `docs/analyses/analyse_04.md` | `docs/energy/analyses/daily_battery_trend.md` | +| `docs/analyses/_modele.md` | `.claude/skills/nouvelle-analyse/modele-fiche.md` | +| `docs/guide/diagnostic-energetique.md` | `docs/energy/guide/diagnostic-energetique.md` | +| `docs/domaine/comment-se-comporte-la-batterie.md` | `docs/energy/domaine/` | +| `docs/domaine/tensions-selon-l-etat-de-la-batterie.md` | `docs/energy/domaine/` | +| `docs/domaine/cas-annotes-par-l-expert.md` | `docs/energy/domaine/` (tous les diagnostics experts portent sur l'énergie) | +| `cas-d-usage-03-04.drawio` (racine) | `docs/energy/matrice-etat-tendance.drawio` (le nom ne porte plus de numéros ; contenu intact) | + +Restent dans `docs/domaine/`, car ils sont communs : `ce-que-mesure-la-station.md`, `pieges-des-donnees.md` et `colonnes-des-deplacements.md`. Il n'y a pas encore de dossier `docs/deplacements/`, puisque ce domaine n'existe pas encore. + +Résultat : + +``` +architecture.drawio CLAUDE.md README.md +data/ inchangé +src/ + common/ stations.py page.py + energy/ moving_average.py battery_state.py battery_trend.py day_color.py + daily.py all_analyses.py focus_jour.py +docs/ + decisions.md + aimsight/ documents AIMsight d'origine + collecteur_system_info.py + domaine/ notes communes + energy/ analyses/ domaine/ guide/ matrice-etat-tendance.drawio + superpowers/ +maquettes/ user/ support/ +.claude/ rules/analyses.md skills/nouvelle-analyse/{SKILL.md, modele-fiche.md} +``` + +## Code + +### Paquets et imports + +- `src/common/` et `src/energy/` sont des paquets Python avec un `__init__.py` vide. Sans lui, un paquet d'espace de noms serait masqué par `maquettes/user/energy.py`, qui porte le même nom (constaté à l'exécution). +- Les imports sont absolus partout : `from energy import battery_state as bs`, `from common import stations`. +- Les scripts lancés directement sont `src/energy/daily.py`, `all_analyses.py`, `focus_jour.py` et les deux maquettes. Chacun ajoute `src/` au chemin d'import, en tête de fichier, en une ligne. C'est déjà l'idiome des maquettes. Quand l'un de ces scripts est importé par un autre, la ligne s'exécute une seconde fois, ce qui est sans effet. + +### `src/common/` + +- **`stations.py`** (bibliothèque standard) : `NAME_RE`, `parse_name`, `load_csv`, `load_stations`, repris d'`energy_check.py` sans changement, plus `gaps(v)`, repris d'`energy_plot.py`. +- **`page.py`** (poste de dev) : + - `ROOT` ; + - à l'import, la bascule sur `.venv` si plotly manque (le comportement actuel d'`analyse_01.py`) ; + - `open_html` ; + - `AUTOSCALE_Y_JS` (D-013 vaut pour toutes les pages). + + Il doit être importé **avant** plotly. + +### `src/energy/` + +- **Modules embarquables** (bibliothèque standard, aucun import de `common/`) : + - `moving_average.py` : `run`, `run_midnight`, `_ma_drop`, `periods`, `RULE` et `RULE_MIDNIGHT` ; + - `battery_state.py`, `battery_trend.py`, `day_color.py`. + + Seuls changent leurs imports internes, leur docstring et le champ `"doc"` de chaque règle, qui pointe vers la nouvelle fiche. +- **`daily.py`, le script livré**. Il reprend de `energy_plot.py` `STATE_STYLE`, `TREND_STYLE`, `noon`, `daily_state_panel`, `daily_trend_panel` et `daily_figure`. + - `main(paths)` écrit, pour chaque station qui a `BusVoltage`, `out/_daily.html` et `.json`, et renvoie leurs chemins. + - Usage : `python3 src/energy/daily.py [CSV ou dossiers]` (défaut : `data/`). Les pages sont ouvertes dans le navigateur. +- **`all_analyses.py`, le script de comparaison**. Il reprend de `energy_plot.py` `ZONES` et `figure`, et importe les panneaux de `daily.py`. + - `main(paths)` écrit `out/_energy.html`. + - Usage : `python3 src/energy/all_analyses.py [CSV ou dossiers]`. La page est ouverte. +- **`focus_jour.py`** : même usage qu'avant (`python3 src/energy/focus_jour.py 27.09`). Il prend `gaps` dans `common.stations` et le reste dans `energy.daily`. Le sous-titre affiché devient `dashed: thresholds of the daily state · arrow: night end D-1 → D (trend)`. +- **L'option `--out` disparaît** : `analyse_01.py` était le seul à l'utiliser, et la sortie est toujours `out/`. + +### Maquettes + +- `maquettes/user/energy.py` et `maquettes/support/home.py` importent `common.page`, `common.stations` et `energy.*` à la place d'`analyse_01`, `energy_check` et `energy_plot`. +- `energy.py` lit le manuel à son nouveau chemin, `docs/energy/guide/diagnostic-energetique.md`. +- Les commentaires de `energy_template.html` qui citent un ancien chemin sont mis à jour. + +## Documents + +- **`CLAUDE.md`** (il reste sous 200 lignes) : + - commandes ; + - tableau des analyses sans colonne N°, avec le nom de la règle, la question, le statut et la fiche. Statuts : livrée (D-020) pour `DAILY_BATTERY_STATE` et `DAILY_BATTERY_TREND`, comparaison seulement pour les deux `MOVING_AVERAGE_*` ; + - sections Documentation et Fichiers ; + - « État et prochaine étape », avec une ligne D-026 ; + - « analyse 03 » devient le nom de la règle partout. +- **`README.md`** : commandes et tableau « Où trouver quoi ». +- **`.claude/rules/analyses.md`** : + - `paths` : `src/**` et `docs/*/analyses/**` ; + - chemin des fiches ; + - `common.page.AUTOSCALE_Y_JS` ; + - vérification avec `all_analyses.py` ; + - l'exception du contrat commun cite les noms des règles. +- **Skill `nouvelle-analyse`** : + - il ne parle plus de numéro. Il situe d'abord le **domaine**, puis fixe le **nom de la règle**, qui donne la fiche `docs//analyses/.md` ; + - le code va dans `src//` et réutilise `common.stations` ; + - au lieu d'un point d'entrée par analyse, la nouvelle analyse reçoit son panneau dans la page de comparaison du domaine (pour Energy, `all_analyses.py`) ; + - le gabarit est `modele-fiche.md`, à côté du `SKILL.md`. +- **`modele-fiche.md`** : en-tête « Script » et « Code » adapté (plus de `src/analyse_NN.py`). +- **Les quatre fiches** : + - titre « `NOM_DE_RÈGLE` : … » ; + - en-têtes « Script » et « Code » ; + - dans le texte vivant, « analyse 01 » devient `MOVING_AVERAGE_7_DAYS_DROP`, et ainsi de suite ; + - les entrées « Historique » existantes restent telles quelles ; une nouvelle entrée datée du 2026-10-12 est ajoutée. +- **Manuel** (`docs/energy/guide/diagnostic-energetique.md`) : + - chemins et commandes (`daily.py` pour la page livrée) ; + - nom de la matrice `.drawio` ; + - « analyse 03 / 04 » et « panneaux 01 et 02 » remplacés par les noms. +- **Notes de domaine** : chemins mis à jour, vers `docs/aimsight/`, le collecteur et les notes déplacées. +- **`docs/decisions.md`** : + - nouvelle entrée D-026 (ci-dessous) ; + - D-006 passe à « remplacée par D-026 » ; + - D-010 et D-012 passent à « remplacée en partie par D-026 », pour le chemin des fiches, du modèle et de la règle `.claude`. + +## Vérification + +Il n'y a pas de tests automatisés (D-008). La comparaison se fait avant et après le déplacement. Pendant les lancements, un faux `explorer.exe` muet est placé en tête du `PATH`, pour ne pas ouvrir d'onglets. + +1. **Avant** : + - `python3 src/analyse_01.py` ; + - `python3 src/focus_jour.py 27.09` ; + - `python3 maquettes/user/energy.py` ; + - `python3 maquettes/support/home.py`. + + Copier ensuite `out/` dans le scratchpad (`before/`). +2. **Après** : lancer `daily.py`, `all_analyses.py`, `focus_jour.py 27.09` et les deux maquettes, puis copier `out/` dans `after/`. +3. **Comparer** : + - `VERMONT_daily.json` doit être identique ; + - les HTML (`VERMONT_daily.html`, `VERMONT_energy.html`, les deux maquettes) doivent être identiques une fois les identifiants aléatoires des figures Plotly (UUID) neutralisés ; + - le focus doit être identique, au sous-titre près ; + - toute autre différence doit être expliquée avant de conclure. +4. **Embarquable** : avec le `python3` système (sans plotly), lancer `python3 -I -c "import sys; sys.path.insert(0, 'src'); from energy import moving_average, battery_state, battery_trend, day_color"`. Un `grep` doit confirmer qu'aucun de ces quatre modules n'importe `common`. +5. **Références périmées** : un `grep` des motifs `analyse_0`, `energy_check`, `energy_plot`, `docs/analyses`, `docs/guide`, `` `doc/ ``, `__main__ (3)` et `cas-d-usage-03-04` ne doit plus rien trouver hors de `docs/superpowers/` et des anciennes entrées du journal. + +Tout est livré en un seul commit, fait avec `git mv`, pour que git suive les renommages. + +## Hors périmètre + +- Les noms des fichiers de `out/`, en particulier `out/_daily.html`, la page à intégrer au site. +- `data/`, dont le nom de `d.md`. +- Un dossier ou un code pour les déplacements, tant que ce domaine n'a pas commencé. +- Une interface commune aux domaines (registre d'analyses, CLI unique) : rien ne la demande encore. + +## Texte de D-026 + +> ## 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 et D-012 (chemins des fiches, du modèle et de la règle `.claude`). +> - **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/daily.py`, les analyses livrées (état et tendance, D-020 et D-021), qui écrit `out/_daily.html` et `.json` ; `src/energy/all_analyses.py`, les quatre analyses ensemble pour comparer (D-016), qui écrit `out/_energy.html`. `src/energy/focus_jour.py` reste l'outil de focus (D-024). Le résumé texte d'`energy_check.py` (`out/_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 `daily.py`, `all_analyses.py` ni `focus_jour.py`, qui demandent plotly. diff --git a/maquettes/support/home.py b/maquettes/support/home.py index cc3eedc..89d565c 100644 --- a/maquettes/support/home.py +++ b/maquettes/support/home.py @@ -1,5 +1,5 @@ """Maquette côté support « Home » : page d'accueil du site de monitoring (toutes les stations), avec en haut une section -Status. Elle porte une notification par station dont le dernier jour de la fenêtre est Orange ou Red (src/day_color.py, D-020). +Status. Elle porte une notification par station dont le dernier jour de la fenêtre est Orange ou Red (src/energy/day_color.py, D-020). La notification, comme la vignette de la station, mène à la vue client de la station (son menu principal) : out/maquette_user_energy.html, écrite par maquettes/user/energy.py (à lancer avec les mêmes dates). @@ -14,9 +14,9 @@ from pathlib import Path HERE = Path(__file__).resolve().parent ROOT = HERE.parent.parent sys.path.insert(0, str(ROOT / "src")) -from analyse_01 import open_html # noqa: E402 -import day_color as dc # noqa: E402 -import energy_check as ec # noqa: E402 +from common.page import open_html # noqa: E402 +from common.stations import load_stations # noqa: E402 +from energy import day_color as dc # noqa: E402 START = date.fromisoformat(sys.argv[1]) if len(sys.argv) > 1 else date(2026, 9, 18) END = date.fromisoformat(sys.argv[2]) if len(sys.argv) > 2 else date(2026, 9, 28) @@ -32,7 +32,7 @@ NAME = {"RED": "Red", "ORANGE": "Orange"} # couleurs notifiées, la plus grave HEADLINE = {"RED": "The station is not receiving enough energy.", # mêmes phrases que la vue client "ORANGE": "The station's energy supply is uncertain."} -series = ec.load_stations([str(ROOT / "data")]) +series = load_stations([str(ROOT / "data")]) def spark(v): diff --git a/maquettes/user/energy.py b/maquettes/user/energy.py index 8fd929f..5e744b9 100644 --- a/maquettes/user/energy.py +++ b/maquettes/user/energy.py @@ -1,7 +1,7 @@ """Maquette côté client « Energy » : page System Summary du site de monitoring, avec une section Diagnostic (D-020 à D-023). Données réelles VERMONT. Bloc Energy : couleur du dernier jour de la fenêtre, échelle de batterie et tendance face à la veille -(src/day_color.py), puis historique complet (energy_plot.daily_figure, D-021) et guide (partie 1 du manuel), repliés. +(src/energy/day_color.py), puis historique complet (energy.daily.daily_figure, D-021) et guide (partie 1 du manuel), repliés. Écrit out/maquette_user_energy.html et l'ouvre dans le navigateur. Usage : python3 maquettes/user/energy.py [AAAA-MM-JJ début] [AAAA-MM-JJ fin] (défaut : 2026-09-18 à 2026-09-28) """ @@ -14,17 +14,15 @@ from pathlib import Path HERE = Path(__file__).resolve().parent ROOT = HERE.parent.parent sys.path.insert(0, str(ROOT / "src")) -from analyse_01 import open_html # noqa: E402 (bascule seule sur .venv si plotly manque) -import battery_state as bs # noqa: E402 -import battery_trend as bt # noqa: E402 -import day_color as dc # noqa: E402 -import energy_check as ec # noqa: E402 -import energy_plot as ep # noqa: E402 +from common.page import AUTOSCALE_Y_JS, open_html # noqa: E402 (bascule seule sur .venv si plotly manque) +from common.stations import load_stations # noqa: E402 +from energy import battery_state as bs, battery_trend as bt, day_color as dc # noqa: E402 +from energy.daily import daily_figure # noqa: E402 START = date.fromisoformat(sys.argv[1]) if len(sys.argv) > 1 else date(2026, 9, 18) END = date.fromisoformat(sys.argv[2]) if len(sys.argv) > 2 else date(2026, 9, 28) -series = ec.load_stations([str(ROOT / "data")])["VERMONT"] +series = load_stations([str(ROOT / "data")])["VERMONT"] v = series["BusVoltage"] in_window = lambda t: START <= t.date() <= END # noqa: E731 @@ -44,7 +42,7 @@ for metric in sorted(series): facts = {p["t"].date(): p["facts"] for p in dc.run(series)["points"]} # Guide : partie 1 du manuel (lecture rapide, pour le client), relue à chaque génération ; titres décalés de deux niveaux. -manual = (ROOT / "docs" / "guide" / "diagnostic-energetique.md").read_text() +manual = (ROOT / "docs" / "energy" / "guide" / "diagnostic-energetique.md").read_text() part1 = manual[manual.index("# Partie 1"):manual.index("# Partie 2")].split("\n", 1)[1] # sans son titre guide = re.sub(r"^#", "###", part1.rstrip().removesuffix("---"), flags=re.M) data = {"hours": hours, "daily": list(daily.values()), "table": table, "guide": guide, @@ -54,8 +52,8 @@ data = {"hours": hours, "daily": list(daily.values()), "table": table, "guide": "deadband_v": bt.NIGHT_END_DEADBAND_V}} html = (HERE / "energy_template.html").read_text() for key, value in (("/*DATA*/null", json.dumps(data)), - ("/*DAILY*/null", ep.daily_figure("VERMONT", series).to_json()), - ("/*AUTOSCALE*/", ep.AUTOSCALE_Y_JS.replace("{plot_id}", "daily"))): + ("/*DAILY*/null", daily_figure("VERMONT", series).to_json()), + ("/*AUTOSCALE*/", AUTOSCALE_Y_JS.replace("{plot_id}", "daily"))): html = html.replace(key, value) out = ROOT / "out" / "maquette_user_energy.html" out.parent.mkdir(exist_ok=True) diff --git a/maquettes/user/energy_template.html b/maquettes/user/energy_template.html index 266faf9..0e6e528 100644 --- a/maquettes/user/energy_template.html +++ b/maquettes/user/energy_template.html @@ -167,7 +167,7 @@