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>
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.pyqui lance la page commune, commeanalyse_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 danssrc/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 = Nonepour tous les jours. L'état UNKNOWN est porté parfacts["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 desassertdans une commande ponctuelle, sans fichier de test. - Ne pas modifier
src/__main__ (3).pyniarchitecture.drawio. - Documents projet en français. Commits en anglais, terminés par
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>.
Review Focus
- 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. - Jour de coupure à moitié troué (VERMONT 2026-09-27, 18 h mesurées) :
BELOW_PLATEAU, pas UNKNOWN. Vérifié dans la tâche 1. - Maximum du jour atteint à 00:00 (VERMONT 2026-05-05) :
night_end_v=max_v,rise_v= 0, étatNO_CHARGE. Vérifié dans la tâche 1. - Premier jour incomplet, jour d'installation (VERMONT 2026-04-09, mesures à partir de 15:00) :
FULL_CHARGEgrâce à une heure ≥ 14,0 V, malgré une couverture < 80 %. Vérifié dans la tâche 1. - Valeur
NaN/infet horodatage hors de la grille horaire : la première doit compter comme « pas de mesure », le second doit leverValueError. VERMONT n'en contient pas, et D-008 interdit d'en fabriquer : on vérifie à la relecture que les deux gardes reprennent celles deenergy_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 parenergy_check.load_stations(paths). -
Produit :
battery_state.RULE: dict avec les clésid,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 constanteSTATE_STYLEet fonctiondaily_state_panelaprèsZONES, boucle des analyses dansfigure(), liste des résultats dansmain())
Interfaces :
-
Consomme :
battery_state.run(series)etbattery_state.RULE(tâche 1). Les faits utilisés sontstate,max_v,night_end_v; les clés de règle utilisées sontfull_charge_vetplateau_floor_v. -
Produit :
energy_plot.daily_state_panel(fig, result, row).figure()dessine ce panneau pour tout résultat dontanalysis == 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 dansenergy_plot.py, point d'entréeanalyse_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.
- dans la ligne
-
« É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