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

212 lines
15 KiB
Markdown

# 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.