Files
Support-Agent/docs/superpowers/specs/2026-10-12-structure-energy-design.md
T
maximeandClaude Opus 5.5 8a32f4d418 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 <noreply@anthropic.com>
2026-10-12 17:12:37 +02:00

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.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/<STATION>_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/<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 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/<domaine>/analyses/<règle en minuscules>.md ;
    • le code va dans src/<domaine>/ 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/<STATION>_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/<STATION>_daily.html et .json ; src/energy/all_analyses.py, les quatre analyses ensemble pour comparer (D-016), qui écrit out/<STATION>_energy.html. src/energy/focus_jour.py reste 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.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.