# Maquette Explore avec l'onglet Diagnosis : 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 :** une maquette HTML de la page Explore de la plateforme (Carrière TROYDO (B), cas NORDEND), avec ses deux onglets en décor et un troisième, `Diagnosis` : image de la caméra à l'instant T et grille capteurs × temps reliées, détail d'un capteur minimal.
**Architecture :** un script Python (`explore.py`, bibliothèque standard) lit l'export « advanced » avec l'outil `donnees.py` de l'agent, calcule l'écart de chaque mesure et injecte un JSON dans un gabarit HTML (`explore_template.html`) ; la page dessine tout en plotly.js, avec un peu de JS pour la liaison. Même schéma que `maquettes/user/summary.py`.
**Tech Stack :** Python 3 (bibliothèque standard), plotly.js 4.1.1 par CDN, Chrome headless (Windows, depuis WSL) pour les captures de vérification, `node --check` pour la syntaxe JS.
**Spec :** `vues-deplacements/maquette/spec.md` (D-053). La lire avant chaque tâche.
## Global Constraints
- Python : bibliothèque standard seulement ; ni pandas ni nouvelle dépendance. Les scripts du dépôt importent `src/common/page.py`, qui relance le script sous `.venv/bin/python` si plotly manque : lancer les vérifications Python avec `.venv/bin/python`.
- plotly.js : ``, comme `maquettes/user/summary_template.html`.
- Texte affiché par la page en anglais (D-023) ; commentaires, docstrings et documents en français ; messages de commit en anglais, terminés par `Co-Authored-By: Claude Opus 5.5 `.
- Toute heure en UTC, au format `2026-10-08T02:30Z` (`donnees.iso`).
- Pas de tests automatisés ni de fichier de test (D-008) : on vérifie en lançant le script, par des assertions en ligne de commande (non commitées) et par des captures Chrome headless lues avec Read.
- Couleur de la grille : `(valeur − niveau) / pas` ; `niveau` = médiane des valeurs des 24 premières heures de la fenêtre ; `pas` = médiane des écarts absolus entre deux valeurs successives ; plafond ±10 ; case ou ligne sans valeur en gris (spec §2).
- Image la plus proche de T à 10 min près ; zoom de départ sur les positions médianes des capteurs, 150 px de marge (spec §1).
- Graphiques temporels du détail : zoom dans le temps seulement, ordonnée recalée sur la plage visible (D-013, `AUTOSCALE_Y_JS` de `src/common/page.py`).
- Aucun identifiant (`SIM_CCID`, `ip`) dans la page ; données réelles seulement.
## Review Focus
- Instant T sans image à 10 min près (le 05/10 de 22:00 à 23:45 : les images commencent le 06/10 à 00:00) : « No image at this time », marqueurs gardés. Testé tâche 2 (capture `#t=2026-10-05T22:00Z`).
- Cas sans dossier `plateforme/` (ex. `data/PS_DES_COUDRES`) : les onglets décor affichent « No capture of this page. », sans erreur. Testé tâche 1 (assertion).
- Dossier sans export « advanced » (mauvais chemin) : message clair et code de sortie 1, pas de trace Python. Testé tâche 1.
- Capteur demandé deux fois (clic répété, `open=PR17,PR17`) : un seul bloc de détail. Testé tâche 3 (capture).
- Grandeur imposée par l'adresse avec un détail ouvert (`col=error_value&open=PR17`) : la grille, les marqueurs et le détail suivent la même grandeur. Testé tâche 3 (capture).
## Fichiers
- Créer `vues-deplacements/maquette/explore.py` : lecture, calcul des écarts, JSON, écriture de la page.
- Créer `vues-deplacements/maquette/explore_template.html` : habillage, onglets, JS de la page.
- Modifier `vues-deplacements/CLAUDE.md` (rangement), `CLAUDE.md` (commande, carte, état).
- Lus sans modification : `agents/diagnostic/outils/donnees.py` (`trouver`, `charger`, `heure_image`, `iso`), `src/common/page.py` (`open_html`, `AUTOSCALE_Y_JS`), `maquettes/user/summary_template.html` (habillage repris).
---
### Task 1 : le script, la page et ses deux onglets décor
**Files :**
- Create : `vues-deplacements/maquette/explore.py`
- Create : `vues-deplacements/maquette/explore_template.html`
- Modify : `vues-deplacements/CLAUDE.md`, `CLAUDE.md`
**Interfaces :**
- Consumes : `donnees.trouver(dossier) -> {"advanced": [chemins], "images": [chemins], ...}` ; `donnees.charger(dossier) -> {capteur: [mesure]}`, mesure = dict avec `t` (datetime UTC), `pattern_type`, et `x`, `y`, `error_value`, `error_threshold`, `corr_x`, `corr_y`… (float ou None) ; `donnees.heure_image(chemin) -> datetime | None` ; `donnees.iso(t) -> "2026-10-08T02:30Z"` ; `common.page.open_html(chemin)`.
- Produces : `deviation(values, first_day) -> list[float | None]` ; `build(folder) -> dict` ; `page(folder) -> Path`. JSON de la page (`const D` dans le gabarit) :
- `platform` (str) ; `times` (liste de `"AAAA-MM-JJTHH:MMZ"`, triée) ;
- `sensors` : liste ordonnée (références `global_ref`, puis `ref`, puis cibles, chacune par nom) de `{"name", "kind", "threshold", "x": [...], "y": [...], "home": [x, y] | None, "values": {"corr_x": [...], "corr_y": [...], "error_value": [...]}, "dev": {même clés}}`, chaque liste alignée sur `times` (None = vide) ;
- `images` : `[{"t": "AAAA-MM-JJTHH:MMZ", "src": URL relative depuis out/}]`, triées ; `view` : `{"x": [x0, x1], "y": [y0, y1]}` ou None ; `captures` : `{"time_series": [URL], "advanced": [URL]}`.
- Gabarit : `` (nom échappé, toutes les occurrences), `/*DATA*/null` (le JSON) ; éléments `#period`, `.tabs button[data-pane]`, `#time_series`, `#advanced`, `#diagnosis`, `#columns`, `#instant`, `#image`, `#grid`, `#details`.
- [ ] **Step 1 : écrire `vues-deplacements/maquette/explore.py`**
```python
"""Maquette de la page Explore avec un onglet Diagnosis (D-053) ; spec : vues-deplacements/maquette/spec.md.
Lit l'export « advanced » d'un dossier de station avec l'outil donnees.py de l'agent, calcule l'écart de chaque mesure
au niveau des 24 premières heures, en variation d'un pas à l'autre, liste les images et les captures de la plateforme,
puis remplit explore_template.html. Écrit out/vues_deplacements_.html et l'ouvre dans le navigateur.
Usage : python3 vues-deplacements/maquette/explore.py [dossier de station] (défaut : le cas NORDEND d'octobre 2026)
"""
import html
import json
import os
import statistics
import sys
from datetime import timedelta
from pathlib import Path
from urllib.parse import quote
HERE = Path(__file__).resolve().parent
ROOT = HERE.parents[1]
OUT = ROOT / "out"
DEFAULT = ROOT / "vues-deplacements" / "cas" / "2026-10_NORDEND" / "NORDEND"
sys.path.insert(0, str(ROOT / "src"))
sys.path.insert(0, str(ROOT / "agents" / "diagnostic" / "outils"))
from common.page import open_html # noqa: E402 (bascule seule sur .venv si plotly manque)
import donnees # noqa: E402 (lecture des exports, bibliothèque standard)
COLUMNS = ("corr_x", "corr_y", "error_value") # grandeurs de la grille (spec §2)
KINDS = ("global_ref", "ref", "target") # ordre des lignes : références de la compensation, local reference, cibles
LEVEL_WINDOW = timedelta(hours=24) # niveau = médiane des 24 premières heures de la fenêtre (spec §2, choix de l'utilisateur)
MARGIN_PX = 150 # marge autour des capteurs, zoom de départ de l'image (spec §1)
CAPTURES = {"time_series": ("01", "02", "03"), "advanced": ("04", "05")} # captures de cas//plateforme/ par onglet
def deviation(values, first_day):
"""Valeurs alignées sur les instants (None = vide), nombre d'instants des 24 premières heures -> écarts
(valeur − niveau) / pas ; tout à None sans valeur dans les 24 premières heures ou si le pas est nul (spec §2)."""
present = [x for x in values if x is not None]
head = [x for x in values[:first_day] if x is not None]
steps = [abs(b - a) for a, b in zip(present, present[1:])]
if not head or not steps:
return [None] * len(values)
level, step = statistics.median(head), statistics.median(steps)
if step == 0:
return [None] * len(values)
return [None if x is None else (x - level) / step for x in values]
def url(path):
"""Chemin -> URL relative depuis out/, où la page est écrite."""
return quote(Path(os.path.relpath(path, OUT)).as_posix())
def build(folder):
"""Dossier de station -> données de la page ; quitte avec un message s'il n'a pas d'export « advanced »."""
files = donnees.trouver(str(folder))
if not files["advanced"]:
sys.exit(f"Pas d'export « advanced » dans {folder}")
mesures = donnees.charger(str(folder))
minute = lambda t: t.replace(second=0, microsecond=0) # noqa: E731 (instants à la minute, comme donnees.iso)
instants = sorted({minute(m["t"]) for ms in mesures.values() for m in ms})
col = {t: j for j, t in enumerate(instants)}
first_day = sum(1 for t in instants if t < instants[0] + LEVEL_WINDOW)
order = lambda s: (KINDS.index(mesures[s][0]["pattern_type"]) if mesures[s][0]["pattern_type"] in KINDS # noqa: E731
else len(KINDS), s)
sensors = []
for name in sorted(mesures, key=order):
ms = mesures[name]
row = {c: [None] * len(instants) for c in ("x", "y") + COLUMNS}
for m in ms:
for c in row:
row[c][col[minute(m["t"])]] = m[c]
xs, ys = [v for v in row["x"] if v is not None], [v for v in row["y"] if v is not None]
sensors.append({"name": name, "kind": ms[0]["pattern_type"], "threshold": ms[0]["error_threshold"],
"x": row["x"], "y": row["y"],
"home": [statistics.median(xs), statistics.median(ys)] if xs and ys else None,
"values": {c: row[c] for c in COLUMNS},
"dev": {c: deviation(row[c], first_day) for c in COLUMNS}})
homes = [s["home"] for s in sensors if s["home"]]
view = {a: [min(h[k] for h in homes) - MARGIN_PX, max(h[k] for h in homes) + MARGIN_PX]
for k, a in enumerate(("x", "y"))} if homes else None
images = sorted(({"t": donnees.iso(t), "src": url(p)} for p in files["images"] if (t := donnees.heure_image(p))),
key=lambda im: im["t"])
plateforme = Path(folder).resolve().parent / "plateforme"
captures = {tab: [url(p) for n in prefixes for p in sorted(plateforme.glob(f"{n}_*"))[:1]]
for tab, prefixes in CAPTURES.items()}
return {"platform": Path(files["advanced"][0]).name.split("_advanced_")[0], "times": [donnees.iso(t) for t in instants],
"sensors": sensors, "images": images, "view": view, "captures": captures}
def page(folder):
"""Dossier de station -> chemin de la page écrite dans out/."""
data = build(folder)
text = (HERE / "explore_template.html").read_text()
text = text.replace("", html.escape(data["platform"]))
text = text.replace("/*DATA*/null", json.dumps(data).replace("", "<\\/"))
OUT.mkdir(exist_ok=True)
out = OUT / f"vues_deplacements_{Path(folder).resolve().name}.html"
out.write_text(text)
return out
if __name__ == "__main__":
out = page(sys.argv[1] if len(sys.argv) > 1 else DEFAULT)
print(out)
open_html(out)
```
- [ ] **Step 2 : vérifier le calcul et les données (doit afficher `ok`)**
Run :
```bash
.venv/bin/python -c "
import statistics as st, sys
sys.path.insert(0, 'vues-deplacements/maquette')
import explore as e
assert e.deviation([1.0, 3.0, None, 2.0, 4.0], 2) == [-0.5, 0.5, None, 0.0, 1.0]
assert e.deviation([None, None, 5.0, 6.0], 2) == [None] * 4 # rien dans les 24 premières heures
assert e.deviation([1.0, 1.0, 1.0], 2) == [None] * 3 # pas nul
d = e.build('vues-deplacements/cas/2026-10_NORDEND/NORDEND')
names = [s['name'] for s in d['sensors']]
assert d['platform'] == 'Carrière TROYDO (B)', d['platform']
assert names[:5] == ['CTR02', 'CTR03', 'CTR04', 'CTR01', 'PR01'] and len(names) == 22, names
assert len(d['times']) == 980 and d['times'][0] == '2026-10-05T22:00Z' and d['times'][-1] == '2026-10-16T05:15Z'
assert len(d['images']) == 985 and d['images'][0]['src'].startswith('../vues-deplacements/cas/2026-10_NORDEND/NORDEND/images/')
assert [len(d['captures'][k]) for k in ('time_series', 'advanced')] == [3, 2]
ctr01 = d['sensors'][names.index('CTR01')]
gaps = [j for j, v in enumerate(ctr01['values']['corr_y']) if v is None]
assert gaps and all(ctr01['dev']['corr_y'][j] is None for j in gaps) # mesure rejetée : case grise
pr17 = d['sensors'][names.index('PR17')]['dev']['corr_y']
palier = [abs(x) for x, t in zip(pr17, d['times']) if '2026-10-08T03:00Z' <= t <= '2026-10-12T22:00Z' and x is not None]
assert st.median(palier) > 20, st.median(palier) # 23,6 mesuré (spec §2)
assert e.build('data/PS_DES_COUDRES')['captures'] == {'time_series': [], 'advanced': []}
print('ok')
"
```
Expected : `ok`. Si une assertion échoue, lire la valeur affichée et corriger `explore.py`, pas l'assertion (les valeurs viennent de la spec et des données).
- [ ] **Step 3 : écrire `vues-deplacements/maquette/explore_template.html`**
```html
· Explore
MP
Maxime Pasquier ▾
Explore
▾
Apply
Color
```
- [ ] **Step 4 : lancer le script et vérifier la sortie d'erreur**
Run :
```bash
python3 vues-deplacements/maquette/explore.py
E=$(mktemp -d) && .venv/bin/python vues-deplacements/maquette/explore.py "$E"; echo "exit $?"; rmdir "$E"
```
Expected : la première commande affiche `/home/maxime/Support-Agent/out/vues_deplacements_NORDEND.html` et ouvre la page ; la seconde affiche `Pas d'export « advanced » dans /tmp/…` puis `exit 1`, sans trace Python.
- [ ] **Step 5 : vérifier la syntaxe du JS de la page**
Run :
```bash
.venv/bin/python -c "import re; s = open('out/vues_deplacements_NORDEND.html').read(); open('out/check_explore.js', 'w').write(re.findall(r'', s, re.S)[-1])" && node --check out/check_explore.js && echo syntax-ok
```
Expected : `syntax-ok`.
- [ ] **Step 6 : capturer les deux onglets décor et regarder les captures**
Le premier onglet affiché est `Diagnosis` (vide à ce stade) ; pour voir le décor, capturer la page et vérifier l'habillage, puis contrôler que les captures existent dans `out/` (URL relatives) :
```bash
U=$(wslpath -w out/vues_deplacements_NORDEND.html | sed 's|\\|/|g; s|^//|file://|')
timeout 90 "/mnt/c/Program Files/Google/Chrome/Application/chrome.exe" --headless=new --disable-gpu --window-size=1600,900 --virtual-time-budget=10000 --screenshot="$(wslpath -w out)\\check_task1.png" "$U" 2>/dev/null
ls out/../vues-deplacements/cas/2026-10_NORDEND/plateforme/01_* out/../vues-deplacements/cas/2026-10_NORDEND/plateforme/05_*
```
Puis Read `out/check_task1.png`. Expected : barre latérale « AIMsight monitoring », en-tête « Carrière TROYDO (B) Explore », période « 5/10/2026 → 16/10/2026 », trois onglets, `Diagnosis` actif. Les deux `ls` trouvent leur fichier.
- [ ] **Step 7 : documenter le rangement et la commande**
Dans `vues-deplacements/CLAUDE.md`, remplacer :
```
Le code et les maquettes du chantier viendront ici aussi ; leur rangement se décide au premier besoin.
```
par :
```
Le code et les maquettes du chantier vivent dans `maquette/` (D-053) : `explore.py` (maquette de la page Explore avec l'onglet Diagnosis, `python3 vues-deplacements/maquette/explore.py [dossier de station]`, page dans `out/`), son gabarit `explore_template.html` et sa spec `spec.md`.
```
Dans `CLAUDE.md`, section « Commandes », après la ligne `python3 maquettes/support/home.py [début] [fin] # maquette support : out/maquette_support_home.html`, ajouter :
```
python3 vues-deplacements/maquette/explore.py [dossier] # maquette Explore + onglet Diagnosis (D-053) : out/vues_deplacements_.html (défaut : cas NORDEND)
```
Dans `CLAUDE.md`, « Carte du dépôt », remplacer la fin de la ligne `vues-deplacements/` :
```
sa carte : `vues-deplacements/CLAUDE.md`.
```
par :
```
sa carte : `vues-deplacements/CLAUDE.md` ; maquette de la page Explore avec l'onglet Diagnosis dans `vues-deplacements/maquette/` (D-053).
```
- [ ] **Step 8 : commit**
```bash
git add vues-deplacements/maquette/explore.py vues-deplacements/maquette/explore_template.html vues-deplacements/CLAUDE.md CLAUDE.md
git commit -m "Add the Explore mockup script and page with its two platform tabs (D-053)
Co-Authored-By: Claude Opus 5.5 "
```
---
### Task 2 : l'onglet Diagnosis, image et grille reliées
**Files :**
- Modify : `vues-deplacements/maquette/explore_template.html`
**Interfaces :**
- Consumes : le JSON `D` de la tâche 1 (`times`, `sensors[*].x|y|values|dev`, `images`, `view`) ; les éléments `#columns`, `#instant`, `#image`, `#grid`.
- Produces (pour la tâche 3) : constantes et fonctions JS globales `S`, `NAMES`, `COLUMNS`, `CONFIG`, `ASKED` (URLSearchParams du `#` de l'adresse), `col` (grandeur, let), `T` (index dans `D.times`, let), `tLine()` (shape du trait de T), `utc(t)`, `drawGrid()`, `drawImage()` (promesses Plotly), `setT(j)`, `markColumn()`. Les trois lignes que la tâche 3 modifie sont citées telles quelles dans ses étapes : ne pas les reformuler.
- [ ] **Step 1 : ajouter le style de la barre d'outils**
Dans `explore_template.html`, remplacer :
```
.empty { padding: 30px 0; color: var(--muted); }
```
par :
```
.empty { padding: 30px 0; color: var(--muted); }
/* Onglet Diagnosis (spec §1 à §3). */
.toolbar { display: flex; align-items: center; gap: 8px; margin-bottom: 8px; color: var(--text); font-size: 14px; }
.toolbar button { border: 1px solid var(--line); background: #fff; border-radius: 4px; padding: 4px 10px;
font: inherit; cursor: pointer; }
.toolbar button.active { background: var(--blue); border-color: var(--blue); color: #fff; }
.toolbar .meta { margin-left: auto; color: var(--muted); }
```
- [ ] **Step 2 : ajouter le JS de l'image et de la grille**
Dans `explore_template.html`, remplacer :
```