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>
This commit is contained in:
1 parent
77c8f24d2f
commit
8a32f4d418
44 files changed
+1757
-771
No files matched your search
@@ -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 : `<STATION>_daily.html` + `.json`, `<STATION>_energy.html`, `<STATION>_focus_<AAAA-MM-JJ>.html` + `.json`, `maquette_user_energy.html` et `maquette_support_home.html`. `<STATION>_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 <noreply@anthropic.com>`.
|
||||
- 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/<STATION>_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/<STATION>_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/<STATION>_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/<STATION>_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/<STATION>_focus_<AAAA-MM-JJ>.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/<règle>.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/<STATION>_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/<STATION>_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/<STATION>_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/<STATION>_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/<STATION>_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 `<STATION>_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/<domaine>/analyses/<règle>.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/<domaine>/`) : 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>/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/<domaine>/` et `docs/<domaine>/` (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/<domaine>/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>/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/<domaine>/analyses/<règle en minuscules>.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/<domaine>/`. 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>/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/<domaine>/` ; 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/<STATION>_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/<STATION>_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/<STATION>_focus_<AAAA-MM-JJ>.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/<domaine>/analyses/<règle>.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>/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/<domaine>/analyses/<règle>.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/<fichier>.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/<règle>.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 <noreply@anthropic.com>
|
||||
EOF
|
||||
)"
|
||||
git log --stat -1 | head -60
|
||||
```
|
||||
@@ -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/<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.
|
||||
Reference in new issue
Block a user