etm-powersync-app/docs/DASHBOARD_SPEC.md

Dashboard ETM-PowerSync — Brief d'implémentation Flutter

Spec pour Claude Code. Objectif : recréer l'écran Dashboard de l'app app.etm-powersync.fr (Flutter), tel que validé en maquette. Les fichiers HTML de référence (etm-powersync-dashboard-v4.html, etm-powersync-flux-drilldown.html) sont la source de vérité visuelle — ce document en est la transcription technique.

---

1. Contexte

ETM-PowerSync est un HEMS (Home Energy Management System). Le cœur intelligent s'appelle Héos (optimiseur prédictif MILP, horizon 24–48 h). Le Dashboard doit faire deux choses : montrer l'état énergétique en direct, et rendre lisible et explicable ce que Héos décide — c'est le différenciateur produit. Public : clients résidentiels (langage clair, zéro jargon) + installateurs.

---

2. Principes directeurs (ne pas dévier)

1. Chaque information à un seul endroit. Pas de doublon entre les blocs. L'autoconsommation est en KPI (haut) → elle n'apparaît nulle part ailleurs sur le Dashboard.
2. Lisibilité avant densité. Lecture rapide en haut, détail optionnel en bas. Le client pressé s'arrête à la décision Héos ; le curieux scrolle.
3. Expliquer = créer la confiance. Toute action automatique de Héos est accompagnée d'un pourquoi en langage courant.
4. Cohérence des flux = physique réelle. Héos est au centre. Le solaire et le réseau alimentent (→ vers le centre) ; le centre répartit vers batterie et maison. Jamais « maison → batterie ».
5. Passé plein, futur voilé. Sur tout graphe temporel : réalisé en couleur pleine, prévu en hachuré + fond grisé, ligne « maintenant » qui traverse.
6. Fluide = rien ne saute. Chaque valeur live s'anime (interpolation), jamais de flash.
7. Quality floor non négociable. Responsive, dark mode, focus clavier, prefers-reduced-motion respecté, contraste AA.

---

3. Design tokens (etm_tokens.dart)

Compléter le fichier existant avec ces valeurs. Typo : IBM Plex Sans (UI) + IBM Plex Mono (toutes les valeurs chiffrées / données).

Couleurs de marque (identiques light/dark sauf note)

Token	Hex	Usage
brand	#31A3DD	bleu ETM, accents, navigation active
solar	#FEC113 (dark #FFCB33)	production solaire
eco	#28A06A (dark #33B87A)	Héos, éco, autonomie, batterie
heat	#EF8B2A	chauffage / PAC
water	#31A3DD	eau chaude (ECS)
grid	#8A98A3	réseau
import	#E8806F	import réseau

Thème clair

Token	Valeur
bg	#EEF2F5
bg2	#E4EAEE
surface	#FFFFFF
ink	#0D2B3B
muted	#5D6F7B
faint	#8B9AA4
line	rgba(13,43,59,.10)
lineStrong	rgba(13,43,59,.16)

Thème sombre

Token	Valeur
bg	#06141D
bg2	#0A1F2B
surface	#0D2B3B (la couleur de marque devient la surface)
ink	#EAF3F7
muted	#9BB0BC
faint	#6C8493
line	rgba(255,255,255,.09)
lineStrong	rgba(255,255,255,.16)

Couleurs des flux (graphe « plan de la journée »)

solToHouse #B8C34D · solToEcs #31A3DD · solToVe #28A06A · solToBatt #7FCF72 · solToGrid #FEC113 · battToHouse #2F6FB0 · gridToHouse #E8806F

Formes & profondeur

• Rayons : cartes 20, contrôles internes 13–14, pills/badges 30 (stadium).
• Parti pris assumé : bordure hairline 1 px (line) + rayon large. Ombres quasi nulles en clair (0 1px 2px rgba(13,43,59,.04)), aucune en sombre. Ne pas revenir aux cartes blanches à ombre portée Material par défaut.
• Espacement entre cartes : 14. Padding interne carte : 14–16.

---

4. Architecture de l'écran

DashboardScreen = Scaffold + SingleChildScrollView (colonne), bottom nav fixe à 5 onglets. Ordre vertical des blocs :

[ TopBar : wordmark + toggle thème clair/sombre ]
[ 1. EnergyFlowCard   ]  ← flux en croix, temps réel, drill-down
[ 2. KpiRow           ]  ← 4 tuiles : autoconso, autonomie, vers/depuis réseau
[ 3. HeosDecisionCard ]  ← décision en cours + pourquoi
[ 4. DayPlanCard      ]  ← météo + barres horaires (réalisé/prévu)
[ BottomNav : Dashboard·Énergie·Things·A/C·Favoris ]

Onglets : Dashboard actif (couleur brand), les autres en faint.

---

5. Composants

5.1 EnergyFlowCard — flux en croix + drill-down

Layout : carte carrée (aspect 1:1, max 320). Stack :

• Couche basse : CustomPaint (lignes hairline entre hub↔nœuds + particules animées).
• Couche haute : nœuds en Positioned (Stack), GestureDetector sur les nœuds tappables.

Vue d'ensemble (overview) — positions cardinales :

Position	Nœud	Valeur (ex.)	Direction flux	Tap
centre (hub)	Héos (icône HEMS, anneau eco pulsant)	—	—	—
haut	Solaire	3.8 kW	entrant (nœud→hub)	→ prod
droite	Batterie	87 %	sortant (hub→nœud)	—
gauche	Réseau	0.2 kW	entrant	—
bas	Maison	2.4 kW	sortant	→ conso

Drill-down conso (depuis Maison) — hub = Maison, autour : PAC (haut, heat), Eau chaude (droite, water), Voiture (bas, eco), Autres (estimé) (gauche, bordure dashed, grid).

Le nœud « Autres (estimé) » est obligatoire : il absorbe le non-mesuré pour que le bilan boucle (conso totale = somme des postes). Sans lui, l'addition ne tombe pas juste et le client se méfie.

Drill-down prod (depuis Solaire) — hub = Solaire, autour : Onduleur 1 (haut), Onduleur 2 (bas), chacun avec point d'état (vert OK / orange défaut). Sens : onduleur → hub.

Particules : CustomPainter + AnimationController en boucle. N points par segment circulant de la source vers la destination. Vitesse et densité ∝ puissance (flux fort = plus de points, plus rapides ; flux faible = 1 point lent). Couleur = couleur de la source.

Transitions drill-down : sortie = fade + scale 0.8 (~170 ms) ; entrée = « éclatement radial », chaque nœud apparaît en scale .25→1 avec overshoot (Curves.easeOutBack) et stagger (~60 ms entre nœuds). Détail intégral du sens/positions dans etm-powersync-flux-drilldown.html.

Affordance tap : badge + discret sur les nœuds tappables (Héos n'est pas tappable ; Solaire et Maison le sont). Profondeur max 2 niveaux — au-delà, écran dédié.

Icône HEMS : utiliser HemsIcon (déjà livré, hems_icon.dart), couleur eco.

5.2 KpiRow

Grille 2×2.

• Tuile autoconsommation : anneau de progression (CustomPaint, couleur solar) + % en mono. S'anime au chargement (anneau qui se remplit + count-up).
• Tuile autonomie : idem, couleur eco.
• Tuile « Vers réseau » : icône flèche ←, valeur kWh du jour, badge fond eco léger.
• Tuile « Depuis réseau » : icône flèche →, valeur kWh, badge fond import léger.

Ces deux métriques (autoconso/autonomie) sont les seules occurrences sur le Dashboard. Ne pas les répéter ailleurs.

5.3 HeosDecisionCard

Carte bordée eco (liseré subtil). Contenu :

• En-tête : icône étincelle (mark Héos) + titre « Héos pilote en ce moment » + sous-titre mono « optimise sur 24 h · maj HH:MM » + point eco pulsant.
• Résumé : 1 phrase en langage client, segment clé surligné eco (ex. « Le surplus part dans l'eau chaude et la voiture plutôt que d'être revendu à bas prix »).
• Liste d'actions (1 par asset piloté) : icône + titre court + le pourquoi (1 ligne, muted) + puissance (kW, mono, eco), séparées par hairline.
• Pied : lien « Voir le plan de la journée » → ouvre l'écran plein Plan de la journée (séparé, voir etm-powersync-plan-journee.html ; c'est là que vivent les pistes appareils détaillées + la ligne gains €).

5.4 DayPlanCard — météo + barres horaires

CustomPaint unique (préférer à fl_chart : contrôle fin du voile futur + bande météo intégrée). Une seule colonne temporelle, axe horaire partagé, de haut en bas :

1. Bande météo : icône (soleil / soleil-nuage / lune) + température, à intervalles (~toutes les 4 h), posée sur l'axe.
2. Barres empilées horaires (kWh) : segments positifs vers le haut (solToHouse, solToEcs, solToVe, solToBatt, solToGrid), négatifs vers le bas (battToHouse, gridToHouse). Axe Y 0/2/4.
3. Axe X : 0h 6h 12h 18h 24h.

Traitement passé/futur : tout ce qui est à droite de la ligne « maintenant » = fond grisé + voile hachuré (lignes diagonales couleur surface, opacité ~.5) ; ligne « maintenant » verticale + tab HH:MM.

Légende sous le graphe : pastilles maison/eau/voiture/batterie/réseau/batt.→maison.

NE PAS mettre sur le Dashboard (retirés volontairement, ils vivent dans l'écran plein « Plan de la journée ») :

• les pistes appareils (timelines ECS / batterie charge-décharge / VE) ;
• la ligne gains (autoconso prévue / réseau ce soir / +€).

5.5 Toggle thème

Switch clair/sombre dans la TopBar, knob animé (overshoot). Persister le choix (provider de thème).

---

6. Animations & widgets

Effet	Approche Flutter
Valeurs live (kW, %)	TweenAnimationBuilder (count-up, easeOutCubic ~900 ms)
Particules de flux	CustomPainter + AnimationController répété ; position = (t + offset) % 1 mappée sur le segment
Anneaux KPI	CustomPaint, Tween sur l'angle balayé
Toggles / switch	AnimatedAlign ou AnimatedPositioned, courbe overshoot (Curves.easeOutBack)
Segmented (pill qui glisse)	Stack + AnimatedPositioned du « glider »
Cartes expandables (A/C)	AnimatedSize
Drill-down croix	AnimationController + Interval staggered (scale + opacity)
Anneau Héos (hub)	pulsation lente en boucle (opacité 0.25↔0.6)

Reduced motion : si MediaQuery.of(context).disableAnimations, court-circuiter les animations (valeurs finales directes, pas de particules en boucle).

---

7. Modèles de données (esquisse)

class LiveFlow {                 // alimente EnergyFlowCard (overview)
  final double solarKw, gridKw, houseKw, batteryKw; // batteryKw signé
  final int batteryPct;
}

class FlowNode {                 // générique, réutilisé à chaque niveau
  final String label, valueText, iconKey;
  final FlowDirection direction; // inbound | outbound
  final bool tappable, estimated; // estimated → bordure dashed
  final NodeState? state;        // ok | warn (onduleurs)
  final String? drillTo;         // 'conso' | 'prod'
}

class HeosDecision {
  final String summary;          // langage client
  final List<HeosAction> actions;
  final DateTime updatedAt;
}
class HeosAction { final String assetIconKey, title, why; final double powerKw; }

class Kpi { final int autoconsumptionPct, autonomyPct; final double toGridKwh, fromGridKwh; }

class DayPlan {
  final List<HourlyFlow> hours;  // 0..23
  final List<WeatherPoint> weather;
  final double nowHour;          // ex. 14.5
}
class HourlyFlow {               // tous en kWh, signés selon sens
  final int hour;
  final double solToHouse, solToEcs, solToVe, solToBatt, solToGrid;
  final double battToHouse, gridToHouse;
}
class WeatherPoint { final int hour; final WeatherKind kind; final int tempC; }

Toutes les valeurs affichées proviennent de ces modèles (les chiffres des maquettes sont des exemples). Prévoir des états loading (skeleton) et vide (« en attente de données du compteur… », jamais d'écran blanc).

---

8. Assets fournis

• hems_icon.dart — HemsIcon(size, color), CustomPainter natif sans dépendance. À utiliser pour le hub central.
• hems_icon.svg — équivalent SVG (currentColor) si passage par flutter_svg.

---

9. Arborescence suggérée

lib/features/dashboard/
  dashboard_screen.dart
  widgets/energy_flow_card.dart      + painters/flow_painter.dart
  widgets/kpi_row.dart               + painters/ring_painter.dart
  widgets/heos_decision_card.dart
  widgets/day_plan_card.dart         + painters/day_plan_painter.dart
  models/dashboard_models.dart
lib/shared/widgets/hems_icon.dart
lib/theme/etm_tokens.dart            (compléter)

10. Ordre de construction recommandé

1. Compléter etm_tokens.dart (couleurs light/dark, typo, radius).
2. KpiRow + RingPainter (le plus simple, valide les tokens).
3. HeosDecisionCard (statique, valide la typo/hairlines).
4. EnergyFlowCard overview + FlowPainter (lignes + particules), puis drill-down.
5. DayPlanCard + DayPlanPainter (barres + voile futur + bande météo).
6. Assemblage DashboardScreen + bottom nav + toggle thème.
7. Passe quality floor : reduced motion, focus, contraste AA en clair et sombre.

---

Réfs visuelles : etm-powersync-dashboard-v4.html (écran complet) et etm-powersync-flux-drilldown.html (interaction croix). En cas de doute sur un espacement ou une couleur, ces fichiers font foi.