docs(moteur): schémas Mermaid — vue d'ensemble des briques, rangs et domaines

Vue d'ensemble : entrées, protection contre la surcharge, cycle de répartition en six
étapes, optimiseur en option, adaptateurs, charges. Rangs et domaines : une seule liste
pour le moteur ; les domaines ne servent qu'à l'affichage de l'app, un chauffe-eau peut
être servi en dernier. Encadré : une borne détectée arrive en fin de liste.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ry3vBrJT1tHdxAaXdCWi6L

docs/fonctionnalites/moteur.de.md

@@ -7,6 +7,48 @@ Warmwasserbereiter, SG-Ready-Wärmepumpe, Relais. Sie ist frei (GPL-3.0) und ent
 der **Community**-Version. Diese Seite beschreibt ihre Logik für Installateure und
 Integratoren; die folgenden Seiten erläutern die einzelnen Funktionen.
 
+## Überblick
+
+```mermaid
+flowchart TB
+    CPT["Netzanschlusszähler<br/>Strom je Phase, Einspeisung, Bezug"]
+    BAT["Batterie<br/>Ladezustand"]
+    APP["App<br/>einmalige Anforderungen"]
+    CFG["Einstellungen des Installateurs<br/>Ränge, Grenzen, Pflichten"]
+
+    subgraph M["Energie-Engine, auf der Box"]
+        PROT["Überlastschutz<br/>bei jeder Messung, vorrangig"]
+        subgraph C["Verteilungszyklus, jede Minute"]
+            C1["1. Messung und Bezugsspielraum"] --> C2["2. Ladefristen"]
+            C2 --> C3["3. Batteriereserve"]
+            C3 --> C4["4. Eco-Durchlauf<br/>einmalige Anforderungen, Pflichten"]
+            C4 --> C5["5. Komfort-Durchlauf<br/>Überschuss kaskadiert, nach Rang"]
+            C5 --> C6["6. Ein Befehl pro Verbraucher"]
+        end
+        AD["Adapter<br/>Grenzen und Sperren jedes Verbrauchers"]
+    end
+
+    OPT["Optimierer, optional<br/>schlägt die Verteilung vor"]
+
+    VE["Wallboxen"]
+    ECS["Warmwasserbereiter<br/>per Relais oder regelbar"]
+    PAC["SG-Ready-Wärmepumpe"]
+    REL["Relais"]
+
+    CPT --> PROT
+    CPT --> C1
+    BAT --> C3
+    APP --> C4
+    CFG --> C
+    OPT -. "Plan" .-> C6
+    C6 --> AD
+    PROT --> AD
+    AD --> VE & ECS & PAC & REL
+```
+
+Überlastschutz und Adapter bleiben in jedem Fall bei der Engine: Ein
+[Optimierer](../optimiseur/index.md) schlägt, falls angeschlossen, nur die Verteilung vor.
+
 ## Zwei Schleifen, zwei Prioritäten
 
 Die Engine trennt Sicherheit und Verteilung. Es sind zwei getrennte Schleifen, mit
@@ -68,6 +110,48 @@ In jedem Zyklus durchläuft die Engine dieselben Schritte, in derselben Reihenfo
    Verbrauchers werden zusammengeführt: Jeder Verbraucher erhält einen einzigen Sollwert,
    mit seinem Grund.
 
+### Ränge und Domänen
+
+Die Engine kennt **nur eine einzige Liste**: Jeder Verbraucher hat einen Rang, über alle
+Kategorien hinweg, und die Kaskade folgt diesem Rang. Die **Domäne** eines Verbrauchers
+(Elektrofahrzeug, Warmwasser, Klimatisierung, Heizung, Batterie) ist ein vom Installateur
+gewähltes Etikett: Die Engine liest es nicht, um zu entscheiden.
+
+Die App nutzt es, um die Bedienreihenfolge **nach Domänen** darzustellen: Man ordnet die
+Domänen untereinander, dann die Verbraucher innerhalb jeder Domäne. Bei der
+Inbetriebnahme schlägt sie vor: Elektrofahrzeug, Warmwasser, Klimatisierung, Heizung. Da
+alles auf der einen Liste beruht, müssen die Verbraucher einer Domäne nicht
+aufeinanderfolgen: Ein Zusatz-Warmwasserbereiter kann **ganz zuletzt** bedient werden,
+nach der Heizung, und eine Wallbox kann vor dem Warmwasser kommen, eine andere danach.
+
+```mermaid
+flowchart LR
+    subgraph AV["Vorgeschlagene Reihenfolge"]
+        direction TB
+        a1["1 · Wallbox Garage"] --> a2["2 · Wallbox Gäste"] --> a3["3 · Warmwasser Haupt"] --> a4["4 · Warmwasser Zusatz"] --> a5["5 · Wärmepumpe"]
+    end
+    subgraph AP["Nach der Einstellung"]
+        direction TB
+        b1["1 · Wallbox Garage"] --> b2["2 · Warmwasser Haupt"] --> b3["3 · Wallbox Gäste"] --> b4["4 · Wärmepumpe"] --> b5["5 · Warmwasser Zusatz"]
+    end
+    AV ==>|"nur Ränge ändern sich"| AP
+
+    classDef ev stroke:#3b82f6,stroke-width:3px
+    classDef ecs stroke:#ef4444,stroke-width:3px
+    classDef chauf stroke:#f59e0b,stroke-width:3px
+    class a1,a2,b1,b3 ev
+    class a3,a4,b2,b5 ecs
+    class a5,b4 chauf
+```
+
+Blauer Rand: Elektrofahrzeug · rot: Warmwasser · orange: Heizung.
+
+!!! tip "Ränge bei der Inbetriebnahme festlegen"
+    Eine erkannte Wallbox wird automatisch **ans Ende der Liste** gesetzt, unabhängig von
+    ihrer Domäne. Zwei Verbraucher mit gleichem Rang werden über ihre Kennung getrennt –
+    das hat niemand so gewählt. Legen Sie die Reihenfolge bei der Inbetriebnahme in der App
+    fest.
+
 ### Die Grenzen jedes Verbrauchers
 
 Jeder Verbraucher hat vom Installateur eingetragene Grenzen, die **jede** Entscheidung

docs/fonctionnalites/moteur.en.md

@@ -7,6 +7,48 @@ SG-Ready heat pump, relays. It is free software (GPL-3.0) and it is the one that
 in the **Community** edition. This page describes its logic for installers and
 integrators; the following pages detail each feature.
 
+## Overview
+
+```mermaid
+flowchart TB
+    CPT["Grid meter<br/>current per phase, export, import"]
+    BAT["Battery<br/>state of charge"]
+    APP["App<br/>one-off requests"]
+    CFG["Installer settings<br/>ranks, bounds, obligations"]
+
+    subgraph M["Energy engine, on the box"]
+        PROT["Overload protection<br/>on every measurement, overrides"]
+        subgraph C["Allocation cycle, every minute"]
+            C1["1. Measurement and draw margin"] --> C2["2. Charging deadlines"]
+            C2 --> C3["3. Battery reserve"]
+            C3 --> C4["4. Eco pass<br/>one-off requests, obligations"]
+            C4 --> C5["5. Comfort pass<br/>surplus in cascade, by rank"]
+            C5 --> C6["6. One command per load"]
+        end
+        AD["Adapters<br/>bounds and locks of each load"]
+    end
+
+    OPT["Optimizer, optional<br/>proposes the allocation"]
+
+    VE["EV chargers"]
+    ECS["Water heaters<br/>relay or adjustable"]
+    PAC["SG-Ready heat pump"]
+    REL["Relays"]
+
+    CPT --> PROT
+    CPT --> C1
+    BAT --> C3
+    APP --> C4
+    CFG --> C
+    OPT -. "plan" .-> C6
+    C6 --> AD
+    PROT --> AD
+    AD --> VE & ECS & PAC & REL
+```
+
+Overload protection and the adapters always stay with the engine: an
+[optimizer](../optimiseur/index.md), if connected, only proposes the allocation.
+
 ## Two loops, two priorities
 
 The engine keeps safety apart from allocation. They are two separate loops, running at
@@ -65,6 +107,47 @@ On every cycle, the engine applies the same steps, in the same order.
 6. **One command per load.** The guaranteed need and the surplus share of the same load
    are merged: each load receives a single setpoint, with its reason.
 
+### Ranks and domains
+
+The engine knows **only one list**: each load has a rank, across all categories, and the
+cascade follows that rank. A load's **domain** (electric vehicle, domestic hot water, air
+conditioning, heating, battery) is a label chosen by the installer: the engine does not
+read it to decide.
+
+The app uses it to present the service order **by domain**: you set the order of the
+domains, then the order of the loads within each domain. At commissioning it proposes:
+electric vehicle, domestic hot water, air conditioning, heating. Since everything rests on
+the single list, nothing forces the loads of a domain to follow each other: a backup water
+heater can be served **last of all**, after the heating, and one charger can come before
+the water heater while another comes after.
+
+```mermaid
+flowchart LR
+    subgraph AV["Proposed order"]
+        direction TB
+        a1["1 · EV garage"] --> a2["2 · EV visitor"] --> a3["3 · Main water heater"] --> a4["4 · Backup water heater"] --> a5["5 · Heat pump"]
+    end
+    subgraph AP["After adjustment"]
+        direction TB
+        b1["1 · EV garage"] --> b2["2 · Main water heater"] --> b3["3 · EV visitor"] --> b4["4 · Heat pump"] --> b5["5 · Backup water heater"]
+    end
+    AV ==>|"only ranks change"| AP
+
+    classDef ev stroke:#3b82f6,stroke-width:3px
+    classDef ecs stroke:#ef4444,stroke-width:3px
+    classDef chauf stroke:#f59e0b,stroke-width:3px
+    class a1,a2,b1,b3 ev
+    class a3,a4,b2,b5 ecs
+    class a5,b4 chauf
+```
+
+Blue border: electric vehicle · red: domestic hot water · orange: heating.
+
+!!! tip "Set the ranks at commissioning"
+    A detected charger is added automatically **at the end of the list**, whatever its
+    domain. Two loads with the same rank are separated by their identifier, which nobody
+    chose. Set the order in the app at commissioning.
+
 ### The bounds of each load
 
 Each load carries bounds entered by the installer, which **every** decision respects,

docs/fonctionnalites/moteur.md

@@ -7,6 +7,48 @@ pompe à chaleur SG-Ready, relais. Il est libre (GPL-3.0) et c'est lui qui déci
 version **Community**. Cette page décrit sa logique pour l'installateur et l'intégrateur ;
 les pages suivantes détaillent chaque fonction.
 
+## Vue d'ensemble
+
+```mermaid
+flowchart TB
+    CPT["Compteur de tête<br/>courant par phase, injection, soutirage"]
+    BAT["Batterie<br/>état de charge"]
+    APP["Application<br/>demandes ponctuelles"]
+    CFG["Réglages de l'installateur<br/>rangs, bornes, obligations"]
+
+    subgraph M["Moteur d'énergie, sur la box"]
+        PROT["Protection contre la surcharge<br/>à chaque mesure, prioritaire"]
+        subgraph C["Cycle de répartition, chaque minute"]
+            C1["1. Mesure et marge de soutirage"] --> C2["2. Recharges à échéance"]
+            C2 --> C3["3. Réserve batterie"]
+            C3 --> C4["4. Passe éco<br/>demandes ponctuelles, obligations"]
+            C4 --> C5["5. Passe confort<br/>surplus en cascade, par rang"]
+            C5 --> C6["6. Une commande par charge"]
+        end
+        AD["Adaptateurs<br/>bornes et verrous de chaque charge"]
+    end
+
+    OPT["Optimiseur, en option<br/>propose la répartition"]
+
+    VE["Bornes de recharge"]
+    ECS["Chauffe-eau<br/>à relais ou modulable"]
+    PAC["Pompe à chaleur SG-Ready"]
+    REL["Relais"]
+
+    CPT --> PROT
+    CPT --> C1
+    BAT --> C3
+    APP --> C4
+    CFG --> C
+    OPT -. "plan" .-> C6
+    C6 --> AD
+    PROT --> AD
+    AD --> VE & ECS & PAC & REL
+```
+
+La protection contre la surcharge et les adaptateurs restent au moteur dans tous les cas :
+un [optimiseur](../optimiseur/index.md), s'il est branché, ne propose que la répartition.
+
 ## Deux boucles, deux priorités
 
 Le moteur sépare la sécurité de la répartition. Ce sont deux boucles distinctes, qui ne
@@ -67,6 +109,47 @@ active. La répartition reprend au cycle qui suit le retour du compteur.
 6. **Une seule commande par charge.** Le besoin garanti et la part de surplus d'une même
    charge sont fusionnés : chaque charge reçoit une seule consigne, avec son motif.
 
+### Les rangs et les domaines
+
+Le moteur ne connaît **qu'une seule liste** : chaque charge a un rang, toutes catégories
+confondues, et la cascade suit ce rang. Le **domaine** d'une charge (véhicule électrique,
+eau chaude sanitaire, climatisation, chauffage, batterie) est une étiquette choisie par
+l'installateur : le moteur ne la lit pas pour décider.
+
+L'application s'en sert pour présenter l'ordre de service **par domaines** : on règle
+l'ordre des domaines entre eux, puis l'ordre des charges dans chaque domaine. À la mise en
+service, elle propose : véhicule électrique, eau chaude sanitaire, climatisation,
+chauffage. Comme tout repose sur la liste unique, rien n'oblige les charges d'un domaine à
+se suivre : un chauffe-eau d'appoint peut être servi **en tout dernier**, après le
+chauffage, et une borne peut passer avant le chauffe-eau tandis qu'une autre passe après.
+
+```mermaid
+flowchart LR
+    subgraph AV["Ordre proposé"]
+        direction TB
+        a1["1 · VE garage"] --> a2["2 · VE visiteur"] --> a3["3 · Chauffe-eau principal"] --> a4["4 · Chauffe-eau d'appoint"] --> a5["5 · PAC"]
+    end
+    subgraph AP["Après réglage"]
+        direction TB
+        b1["1 · VE garage"] --> b2["2 · Chauffe-eau principal"] --> b3["3 · VE visiteur"] --> b4["4 · PAC"] --> b5["5 · Chauffe-eau d'appoint"]
+    end
+    AV ==>|"on ne change que des rangs"| AP
+
+    classDef ev stroke:#3b82f6,stroke-width:3px
+    classDef ecs stroke:#ef4444,stroke-width:3px
+    classDef chauf stroke:#f59e0b,stroke-width:3px
+    class a1,a2,b1,b3 ev
+    class a3,a4,b2,b5 ecs
+    class a5,b4 chauf
+```
+
+Bordure bleue : véhicule électrique · rouge : eau chaude sanitaire · orange : chauffage.
+
+!!! tip "Poser les rangs à la mise en service"
+    Une borne détectée est ajoutée d'office **en fin de liste**, quel que soit son domaine.
+    Deux charges au même rang sont départagées par leur identifiant, ce qui n'est le choix
+    de personne. Réglez l'ordre dans l'application à la mise en service.
+
 ### Les bornes de chaque charge
 
 Chaque charge porte des bornes saisies par l'installateur, que **toute** décision

mkdocs.yml

@@ -50,7 +50,12 @@ markdown_extensions:
       permalink: true
   - pymdownx.highlight:
       anchor_linenums: true
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      # Schémas Mermaid (page « Comment le moteur décide ») : Material les dessine côté navigateur.
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.details
   - pymdownx.inlinehilite
   - pymdownx.tabbed: