Files
Support-Agent/docs/superpowers/plans/2026-10-12-daily-battery-state.md
T
maximeandClaude Opus 5.5 1ae176cc5a 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.
Includes the implementation plan.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 10:52:08 +02:00

20 KiB

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 <noreply@anthropic.com>.

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 :

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
"""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
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 <noreply@anthropic.com>
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 :

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 :

import battery_state as bs
  • Step 3 : ajouter le style des états et le panneau, après la liste ZONES
# É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<extra></extra>",
                    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}<br>" + "<br>".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}<extra></extra>", 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 :

    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 :

    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 :

        figure(station, series, [ec.run(series), ec.run_midnight(series)]).write_html(

par :

        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

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 <noreply@anthropic.com>
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

"""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
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 <noreply@anthropic.com>
EOF