# Analyse 03 `DAILY_BATTERY_STATE` (phase C) — 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 :** donner, pour chaque jour UTC, l'état de la batterie (`FULL_CHARGE`, `BELOW_PLATEAU`, `NO_CHARGE`, `PARTIAL_CHARGE` ou UNKNOWN), et l'afficher en troisième panneau de la page commune. **Architecture :** - un module de calcul en bibliothèque standard, `src/battery_state.py`, qui respecte le contrat commun ; - un panneau propre à cette analyse dans `src/energy_plot.py`, qui ajoute le résultat à la liste des analyses de la page ; - un point d'entrée `src/analyse_03.py` qui lance la page commune, comme `analyse_02.py`. **Tech Stack :** Python 3 (bibliothèque standard) pour le calcul ; plotly (`.venv`) pour le graphique. **Spec :** `docs/analyses/analyse_03.md` (sections « Principe », « Constantes et sources », « Graphique », « Résultats attendus »). ## Global Constraints - `src/battery_state.py` : bibliothèque standard uniquement (code embarquable). Plotly seulement dans `src/energy_plot.py`. - Contrat commun : `run(series) -> {analysis, rule, points: [{t, value, anomaly, facts}]}`. Calcul causal : le jour d n'utilise que les heures de d. - En phase C, `anomaly = None` pour tous les jours. L'état UNKNOWN est porté par `facts["state"] = None`. - Constantes : `FULL_CHARGE_V = 14.0`, `PLATEAU_FLOOR_V = 12.8`, `MIN_RISE_V = 0.05`, `MIN_COVERAGE = 0.8`, chacune avec sa source en commentaire. - Identifiant de règle et noms d'états en anglais, en mots complets (D-017) : `DAILY_BATTERY_STATE`, `FULL_CHARGE`, `BELOW_PLATEAU`, `NO_CHARGE`, `PARTIAL_CHARGE`. - **Pas de tests automatisés** (D-008) et **pas de données synthétiques** (refus de l'utilisateur). La vérification se fait en lançant le code sur les données réelles de VERMONT (`data/`), avec des `assert` dans une commande ponctuelle, sans fichier de test. - Ne pas modifier `src/__main__ (3).py` ni `architecture.drawio`. - Documents projet en français. Commits en anglais, terminés par `Co-Authored-By: Claude Opus 5.5 `. ## Review Focus 1. **Dernier jour incomplet d'un export** (VERMONT 2026-10-09, 9 h mesurées, minimum 12,24 V) : il doit être lu `BELOW_PLATEAU` (valeur mesurée), pas UNKNOWN. Vérifié dans la tâche 1. 2. **Jour de coupure à moitié troué** (VERMONT 2026-09-27, 18 h mesurées) : `BELOW_PLATEAU`, pas UNKNOWN. Vérifié dans la tâche 1. 3. **Maximum du jour atteint à 00:00** (VERMONT 2026-05-05) : `night_end_v` = `max_v`, `rise_v` = 0, état `NO_CHARGE`. Vérifié dans la tâche 1. 4. **Premier jour incomplet, jour d'installation** (VERMONT 2026-04-09, mesures à partir de 15:00) : `FULL_CHARGE` grâce à une heure ≥ 14,0 V, malgré une couverture < 80 %. Vérifié dans la tâche 1. 5. **Valeur `NaN`/`inf` et horodatage hors de la grille horaire** : la première doit compter comme « pas de mesure », le second doit lever `ValueError`. VERMONT n'en contient pas, et D-008 interdit d'en fabriquer : on vérifie à la relecture que les deux gardes reprennent celles de `energy_check._ma_drop` (`math.isfinite`, `(t - t0) % HOUR`). Relecture dans la tâche 1. --- ### Task 1 : calcul `src/battery_state.py` **Files :** - Create : `src/battery_state.py` **Interfaces :** - Consomme : `energy_check.HOUR` (`timedelta(hours=1)`) ; les séries `{metric: {datetime UTC: float | None}}` chargées par `energy_check.load_stations(paths)`. - Produit : - `battery_state.RULE` : dict avec les clés `id`, `phase`, `full_charge_v`, `plateau_floor_v`, `min_rise_v`, `min_coverage`, `doc` ; - `battery_state.day_facts(day: dict[int, float]) -> dict` : `{state, max_v, night_end_v, rise_v, hours_full, coverage}`, ou `{state: None, coverage: 0.0}` pour un jour sans mesure ; - `battery_state.run(series) -> {analysis, rule, points}` : un point par jour UTC, `t` = dernière heure du jour présente dans la série, `value` = `facts.get("max_v")`, `anomaly = None`. - [ ] **Step 1 : écrire la commande de vérification (elle échoue tant que le module n'existe pas)** Run : ```bash cd /home/maxime/Support-Agent && python3 - <<'EOF' import sys; sys.path.insert(0, "src") from collections import Counter import energy_check as ec, battery_state as bs r = bs.run(ec.load_stations(["data"])["VERMONT"]) p = {q["t"].date().isoformat(): q for q in r["points"]} counts = dict(Counter(q["facts"]["state"] for q in r["points"])) print(r["analysis"], len(r["points"]), counts) for d in ("2026-04-09", "2026-05-05", "2026-09-26", "2026-09-27", "2026-10-09"): print(d, p[d]["t"].strftime("%H:%M"), p[d]["value"], p[d]["anomaly"], p[d]["facts"]) assert r["analysis"] == "DAILY_BATTERY_STATE" and len(r["points"]) == 184 assert counts == {"FULL_CHARGE": 139, "PARTIAL_CHARGE": 30, "BELOW_PLATEAU": 14, "NO_CHARGE": 1}, counts assert all(q["anomaly"] is None for q in r["points"]) assert all(q["value"] == q["facts"].get("max_v") for q in r["points"]) f = p["2026-04-09"]["facts"]; assert f["state"] == "FULL_CHARGE" and f["coverage"] < 0.8, f f = p["2026-05-05"]["facts"]; assert f["state"] == "NO_CHARGE" and f["rise_v"] == 0 and f["night_end_v"] == f["max_v"], f f = p["2026-09-26"]["facts"]; assert f["state"] == "BELOW_PLATEAU" and round(f["night_end_v"], 2) == 12.71, f f = p["2026-09-27"]["facts"]; assert f["state"] == "BELOW_PLATEAU" and f["coverage"] < 0.8, f f = p["2026-10-09"]["facts"]; assert f["state"] == "BELOW_PLATEAU" and f["coverage"] == 0.375, f assert p["2026-10-09"]["t"].strftime("%H:%M") == "15:00" print("OK") EOF ``` Expected : `ModuleNotFoundError: No module named 'battery_state'`. - [ ] **Step 2 : écrire `src/battery_state.py`** ```python """Analyse 03 DAILY_BATTERY_STATE : état de la batterie jour par jour (phase C : état seul, sans verdict). Documentation : docs/analyses/analyse_03.md Bibliothèque standard uniquement (cible : système embarqué de la station). """ import math from collections import defaultdict from energy_check import HOUR # Constantes (fiche analyse_03, « Constantes et sources »). FULL_CHARGE_V = 14.0 # VERMONT : maxima journaliers < 13,55 V (35 j) ou 14,02-14,33 V (135 j) ; absorption ~14,2 V PLATEAU_FLOOR_V = 12.8 # coude LiFePO4 : table OCV du collecteur (12,8 V = 30 %) ; pente nocturne doublée sous 12,8 V MIN_RISE_V = 0.05 # > variations horaires sur le plateau (<= 15 mV/h), < plus faible vraie montée (+0,18 V, VERMONT 04-11) MIN_COVERAGE = 0.8 # repris de l'analyse 01 : 20 h mesurées sur 24 RULE = { "id": "DAILY_BATTERY_STATE", "phase": "C : état seul, sans verdict (anomaly = None)", "full_charge_v": FULL_CHARGE_V, "plateau_floor_v": PLATEAU_FLOOR_V, "min_rise_v": MIN_RISE_V, "min_coverage": MIN_COVERAGE, "doc": "docs/analyses/analyse_03.md", } def day_facts(day): """{heure UTC: tension mesurée} d'un jour -> faits et état (fiche analyse_03, « Principe »).""" if not day: return {"state": None, "coverage": 0.0} h_max = max(sorted(day), key=day.get) # première heure où le maximum est atteint max_v = day[h_max] night_end_v = min(v for h, v in day.items() if h <= h_max) rise_v = max_v - night_end_v hours_full = sum(v >= FULL_CHARGE_V for v in day.values()) coverage = len(day) / 24 # Les états 1 et 2 reposent sur une valeur mesurée : ils passent avant la couverture minimale. if hours_full: state = "FULL_CHARGE" elif night_end_v < PLATEAU_FLOOR_V: state = "BELOW_PLATEAU" elif coverage < MIN_COVERAGE: state = None # UNKNOWN : trop de trous pour conclure à une absence elif rise_v < MIN_RISE_V: state = "NO_CHARGE" else: state = "PARTIAL_CHARGE" return {"state": state, "max_v": round(max_v, 3), "night_end_v": round(night_end_v, 3), "rise_v": round(rise_v, 3), "hours_full": hours_full, "coverage": round(coverage, 3)} def run(series): """Analyse DAILY_BATTERY_STATE, causale : le jour d n'utilise que les heures de d. Un point par jour UTC.""" v = series["BusVoltage"] if v: t0 = min(v) if any((t - t0) % HOUR for t in v): raise ValueError("BusVoltage : horodatages hors de la grille horaire") days, last = defaultdict(dict), {} for t in sorted(v): last[t.date()] = t x = v[t] if x is not None and math.isfinite(x): # NaN/inf (ex. export pandas) = pas de mesure days[t.date()][t.hour] = x points = [] for d in sorted(last): facts = day_facts(days.get(d, {})) points.append({"t": last[d], "value": facts.get("max_v"), "anomaly": None, "facts": facts}) return {"analysis": RULE["id"], "rule": RULE, "points": points} ``` - [ ] **Step 3 : relancer la commande du Step 1** Expected : la ligne `DAILY_BATTERY_STATE 184 {...}`, les 5 jours avec leurs faits, puis `OK`. - [ ] **Step 4 : relecture (Review Focus 5)** Vérifier que `run()` filtre les valeurs avec `math.isfinite` et lève `ValueError` sur `(t - t0) % HOUR`, comme `energy_check._ma_drop`. - [ ] **Step 5 : commit** ```bash cd /home/maxime/Support-Agent && git add src/battery_state.py && git commit -q -F - <<'EOF' Add analysis 03 DAILY_BATTERY_STATE computation (phase C) One state per UTC day from BusVoltage: FULL_CHARGE, BELOW_PLATEAU, NO_CHARGE, PARTIAL_CHARGE or unknown, with hardware thresholds (14.0 V end of charge, 12.8 V LiFePO4 knee). No verdict yet. Co-Authored-By: Claude Opus 5.5 EOF ``` --- ### Task 2 : panneau du graphique **Files :** - Modify : `src/energy_plot.py` (imports en tête, nouvelle constante `STATE_STYLE` et fonction `daily_state_panel` après `ZONES`, boucle des analyses dans `figure()`, liste des résultats dans `main()`) **Interfaces :** - Consomme : `battery_state.run(series)` et `battery_state.RULE` (tâche 1). Les faits utilisés sont `state`, `max_v`, `night_end_v` ; les clés de règle utilisées sont `full_charge_v` et `plateau_floor_v`. - Produit : `energy_plot.daily_state_panel(fig, result, row)`. `figure()` dessine ce panneau pour tout résultat dont `analysis == battery_state.RULE["id"]`. - [ ] **Step 1 : écrire la commande de vérification (elle échoue tant que le panneau n'existe pas)** Run : ```bash cd /home/maxime/Support-Agent && .venv/bin/python src/energy_plot.py data/ && python3 - <<'EOF' import re h = open("out/VERMONT_energy.html").read() print(sorted(set(re.findall(r'"text":"Analyse [^"]*"', h)))) for n in ("maximum du jour", "fin de nuit", "pleine charge 14.0 V", "bas du plateau 12.8 V", "pleine charge", "charge partielle (incertain)", "sous le plateau", "aucune charge"): assert f'"name":"{n}"' in h, n assert '"text":"Analyse DAILY_BATTERY_STATE"' in h print("OK") EOF ``` Expected : `AssertionError: maximum du jour`. - [ ] **Step 2 : importer le module de calcul** Dans `src/energy_plot.py`, sous `import energy_check as ec` : ```python import battery_state as bs ``` - [ ] **Step 3 : ajouter le style des états et le panneau, après la liste `ZONES`** ```python # États de DAILY_BATTERY_STATE : couleurs validées par le skill dataviz (toutes paires, fond blanc). # Le jaune contraste peu avec le fond : chaque état a aussi son symbole, sa légende et son survol. STATE_STYLE = { "FULL_CHARGE": ("pleine charge", "#008300", "circle"), "PARTIAL_CHARGE": ("charge partielle (incertain)", "#eda100", "diamond"), "BELOW_PLATEAU": ("sous le plateau", "#2a78d6", "triangle-down"), "NO_CHARGE": ("aucune charge", "#4a3aa7", "x"), None: ("état inconnu", "#8c8c8c", "circle-open"), } def daily_state_panel(fig, result, row): """Panneau DAILY_BATTERY_STATE : maximum et fin de nuit par jour, seuils, état en marqueurs (fiche analyse_03).""" group = dict(legendgroup=result["analysis"], legendgrouptitle_text=f"Analyse {result['analysis']}") rule, pts = result["rule"], result["points"] x = [p["t"] for p in pts] fig.add_scatter(x=x, y=[p["facts"].get("max_v") for p in pts], name="maximum du jour", mode="lines", line=dict(color="#52514e", width=1.5), hoverinfo="skip", row=row, col=1, **group) fig.add_scatter(x=x, y=[p["facts"].get("night_end_v") for p in pts], name="fin de nuit", mode="lines", line=dict(color="#9a9893", width=1.5), hovertemplate="fin de nuit %{y:.2f} V", row=row, col=1, **group) # Seuils tracés comme des courbes (un point par jour) : AUTOSCALE_Y_JS les garde visibles au zoom (D-013). for v, name, state in ((rule["full_charge_v"], "pleine charge", "FULL_CHARGE"), (rule["plateau_floor_v"], "bas du plateau", "BELOW_PLATEAU")): fig.add_scatter(x=x, y=[v] * len(x), name=f"{name} {v} V", mode="lines", hoverinfo="skip", line=dict(color=STATE_STYLE[state][1], dash="dash", width=1), row=row, col=1, **group) for state, (label, color, symbol) in STATE_STYLE.items(): sel = [p for p in pts if p["facts"]["state"] == state and p["facts"].get("max_v") is not None] if not sel: continue hover = [f"{p['t']:%Y-%m-%d} : {label}
" + "
".join(f"{k}={val}" for k, val in p["facts"].items()) for p in sel] fig.add_scatter(x=[p["t"] for p in sel], y=[p["facts"]["max_v"] for p in sel], name=label, mode="markers", marker=dict(color=color, symbol=symbol, size=8, line=dict(color="white", width=1)), text=hover, hovertemplate="%{text}", row=row, col=1, **group) fig.update_yaxes(title_text="BusVoltage [V]", row=row, col=1) ``` - [ ] **Step 4 : brancher le panneau dans `figure()`** Remplacer le début de la boucle des analyses : ```python for row, result in enumerate(results, start=1): analyse = dict(legendgroup=result["analysis"], legendgrouptitle_text=f"Analyse {result['analysis']}") thr = result["rule"]["threshold_v"] ``` par : ```python for row, result in enumerate(results, start=1): if result["analysis"] == bs.RULE["id"]: daily_state_panel(fig, result, row) continue analyse = dict(legendgroup=result["analysis"], legendgrouptitle_text=f"Analyse {result['analysis']}") thr = result["rule"]["threshold_v"] ``` - [ ] **Step 5 : ajouter le résultat dans `main()`** Remplacer : ```python figure(station, series, [ec.run(series), ec.run_midnight(series)]).write_html( ``` par : ```python figure(station, series, [ec.run(series), ec.run_midnight(series), bs.run(series)]).write_html( ``` Mettre aussi à jour la docstring du module (ligne 3) : `Documentation : docs/analyses/analyse_01.md, docs/analyses/analyse_02.md, docs/analyses/analyse_03.md`. - [ ] **Step 6 : relancer la commande du Step 1** Expected : la liste des titres contient `Analyse DAILY_BATTERY_STATE`, puis `OK`. - [ ] **Step 7 : vérification visuelle** Run : `python3 src/analyse_01.py` (ouvre la page dans le navigateur). À vérifier à l'œil : - le troisième panneau se trouve sous les deux autres ; - les marqueurs sont sur la courbe du maximum, et les seuils à 14,0 et 12,8 V sont en tirets ; - en zoomant sur septembre 2026, les deux seuils restent visibles ; - les triangles bleus (`BELOW_PLATEAU`) apparaissent à partir du 26/09. - [ ] **Step 8 : commit** ```bash cd /home/maxime/Support-Agent && git add src/energy_plot.py && git commit -q -F - <<'EOF' Plot DAILY_BATTERY_STATE as the third analysis panel Daily maximum and night-end voltage, 14.0 V and 12.8 V thresholds, one marker colour and symbol per day state. Co-Authored-By: Claude Opus 5.5 EOF ``` --- ### Task 3 : point d'entrée et documentation **Files :** - Create : `src/analyse_03.py` - Modify : `src/analyse_01.py:1-2` (docstring) - Modify : `docs/analyses/analyse_03.md` (statut, code, résultats, historique) - Modify : `docs/analyses/analyse_01.md` (section « Graphique ») - Modify : `CLAUDE.md` (tableau « Analyses », « Commandes », « État et prochaine étape ») - Modify : `README.md` (paragraphe des analyses en place) **Interfaces :** - Consomme : la page commune produite par `analyse_01.py` (tâche 2). - Produit : la commande `python3 src/analyse_03.py`. - [ ] **Step 1 : créer `src/analyse_03.py`** ```python """Analyse 03 : DAILY_BATTERY_STATE (état de la batterie jour par jour, phase C). Son graphique est le troisième panneau d'analyse de la page commune : ce script lance analyse_01.py. Usage : python3 src/analyse_03.py [CSV ou dossiers...] (défaut : data/, sortie dans out/) Documentation : docs/analyses/analyse_03.md """ import runpy from pathlib import Path runpy.run_path(str(Path(__file__).with_name("analyse_01.py")), run_name="__main__") ``` - [ ] **Step 2 : lancer le point d'entrée** Run : `cd /home/maxime/Support-Agent && python3 src/analyse_03.py` Expected : `/home/maxime/Support-Agent/out/VERMONT_energy.html`, et la page s'ouvre dans le navigateur. - [ ] **Step 3 : docstring de `src/analyse_01.py`** Remplacer la ligne 2 : `La page montre aussi, juste dessous, l'analyse 02 (MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP), pour comparer les deux méthodes.` par : `La page montre aussi, dessous, les analyses 02 (MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP) et 03 (DAILY_BATTERY_STATE).` - [ ] **Step 4 : fiche `docs/analyses/analyse_03.md`** - Statut : `prototype en place (2026-10-12). Phase C : l'état seul, sans verdict. La phase B (niveaux gradués) viendra ensuite (D-018).` - Code, premier point : `` `src/battery_state.py` : calcul, bibliothèque standard uniquement (`run()`, `day_facts()`). Il reçoit les séries chargées par `energy_check.load_stations`. `` - Section « Résultats attendus… » : renommer en `Résultats sur VERMONT (jeu de travail)`, et remplacer « essai de conception » par les valeurs imprimées au Step 3 de la tâche 1, si elles diffèrent. - Historique, ajouter : `- **2026-10-12** : implémentée (`src/battery_state.py`, panneau dans `energy_plot.py`, point d'entrée `analyse_03.py`). Résultats conformes à l'essai de conception.` - [ ] **Step 5 : fiche `docs/analyses/analyse_01.md`, section « Graphique »** Après la ligne « **Juste dessous, le panneau de l'analyse 02**… », ajouter : `- **Puis le panneau de l'analyse 03** (`DAILY_BATTERY_STATE`) : état de la batterie jour par jour (fiche `analyse_03.md`).` - [ ] **Step 6 : `CLAUDE.md`** - Tableau « Analyses », ligne 03 : statut `prototype en place`. - « Commandes » : - dans la ligne `analyse_01.py`, remplacer `(panneaux des analyses 01 et 02, D-016)` par `(panneaux des analyses 01, 02 et 03, D-016)` ; - ajouter : `` - `python3 src/analyse_03.py` : point d'entrée de l'analyse 03 ; il lance la même page. `` - « État et prochaine étape » : remplacer la ligne « Prochaine étape » par : `` - **Prochaine étape** : phase B de l'analyse 03 (niveaux gradués à partir des séries d'états, voir les pistes de sa fiche), puis la combinaison des analyses. `` Ajouter avant elle : `` - **2026-10-12** : analyse 03 `DAILY_BATTERY_STATE` en place (phase C, état seul). `` - [ ] **Step 7 : `README.md`** Remplacer `Deux analyses sont en place : … la même sur la seule mesure de 00:00 UTC.` par : `` Trois analyses sont en place : `MOVING_AVERAGE_7_DAYS_DROP`, la tendance de la tension batterie sur 7 jours ; `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP`, la même sur la seule mesure de 00:00 UTC ; `DAILY_BATTERY_STATE`, l'état de la batterie jour par jour. `` - [ ] **Step 8 : contrôle de cohérence** Run : `cd /home/maxime/Support-Agent && grep -n "en conception" CLAUDE.md docs/analyses/analyse_03.md; grep -n "analyse_03.py" CLAUDE.md` Expected : aucune ligne pour le premier `grep` ; une ligne de commande pour le second. - [ ] **Step 9 : commit** ```bash cd /home/maxime/Support-Agent && git add src/analyse_03.py src/analyse_01.py docs/analyses/analyse_03.md docs/analyses/analyse_01.md CLAUDE.md README.md && git commit -q -F - <<'EOF' Add analysis 03 entry point and documentation src/analyse_03.py launches the common page; sheet 03 moves to "prototype en place" with VERMONT results; CLAUDE.md, README and sheet 01 list the third panel. Co-Authored-By: Claude Opus 5.5 EOF ```