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 <noreply@anthropic.com>
15 KiB
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/<STATION>_energy.jsonn'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/etsrc/energy/sont des paquets Python avec un__init__.pyvide. Sans lui, un paquet d'espace de noms serait masqué parmaquettes/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.pyet les deux maquettes. Chacun ajoutesrc/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.pysans changement, plusgaps(v), repris d'energy_plot.py. -
page.py(poste de dev) :ROOT;- à l'import, la bascule sur
.venvsi 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,RULEetRULE_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 deenergy_plot.pySTATE_STYLE,TREND_STYLE,noon,daily_state_panel,daily_trend_paneletdaily_figure.main(paths)écrit, pour chaque station qui aBusVoltage,out/<STATION>_daily.htmlet.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 deenergy_plot.pyZONESetfigure, et importe les panneaux dedaily.py.main(paths)écritout/<STATION>_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 prendgapsdanscommon.stationset le reste dansenergy.daily. Le sous-titre affiché devientdashed: thresholds of the daily state · arrow: night end D-1 → D (trend). -
L'option
--outdisparaît :analyse_01.pyétait le seul à l'utiliser, et la sortie est toujoursout/.
Maquettes
maquettes/user/energy.pyetmaquettes/support/home.pyimportentcommon.page,common.stationsetenergy.*à la place d'analyse_01,energy_checketenergy_plot.energy.pylit le manuel à son nouveau chemin,docs/energy/guide/diagnostic-energetique.md.- Les commentaires de
energy_template.htmlqui 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_STATEetDAILY_BATTERY_TREND, comparaison seulement pour les deuxMOVING_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/**etdocs/*/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/<domaine>/analyses/<règle en minuscules>.md; - le code va dans
src/<domaine>/et réutilisecommon.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é duSKILL.md.
- 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
modele-fiche.md: en-tête « Script » et « Code » adapté (plus desrc/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.
- titre «
- Manuel (
docs/energy/guide/diagnostic-energetique.md) :- chemins et commandes (
daily.pypour la page livrée) ; - nom de la matrice
.drawio; - « analyse 03 / 04 » et « panneaux 01 et 02 » remplacés par les noms.
- chemins et commandes (
- 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.
-
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/). -
Après : lancer
daily.py,all_analyses.py,focus_jour.py 27.09et les deux maquettes, puis copierout/dansafter/. -
Comparer :
VERMONT_daily.jsondoit ê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.
-
Embarquable : avec le
python3système (sans plotly), lancerpython3 -I -c "import sys; sys.path.insert(0, 'src'); from energy import moving_average, battery_state, battery_trend, day_color". Ungrepdoit confirmer qu'aucun de ces quatre modules n'importecommon. -
Références périmées : un
grepdes motifsanalyse_0,energy_check,energy_plot,docs/analyses,docs/guide,`doc/,__main__ (3)etcas-d-usage-03-04ne doit plus rien trouver hors dedocs/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 particulierout/<STATION>_daily.html, la page à intégrer au site. data/, dont le nom ded.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/etdocs/energy/(analyses, domaine, guide, matrice). Le code commun est danssrc/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 dansdocs/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 écritout/<STATION>_daily.htmlet.json;src/energy/all_analyses.py, les quatre analyses ensemble pour comparer (D-016), qui écritout/<STATION>_energy.html.src/energy/focus_jour.pyreste l'outil de focus (D-024). Le résumé texte d'energy_check.py(out/<STATION>_energy.json) est supprimé.- La documentation AIMsight d'origine passe de
doc/àdocs/aimsight/, avec la copie du collecteur (collecteur_system_info.py, ex-src/__main__ (3).py). La roadmap perd le suffixe « (2) ».cas-d-usage-03-04.drawiodevientdocs/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é dedocs/, 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.pypar 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/sansdaily.py,all_analyses.pynifocus_jour.py, qui demandent plotly.