Doku: Automatiken und Zeitleiste ausfuehrlich beschrieben

Neues Verzeichnis doku/ mit zwei Tiefenbohrungen: das Regelwerk der Automatiken (Datenmodell, Editor, Runner, Auswertung, Verkettung, Sperren) und die Zeitleiste (Serverrechnung, Zeichnen, Stapeln, Ketten, Karte). Mit Diagrammen und je einem Bild; die Haupt-README verweist darauf. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-21 07:39:43 +02:00
parent 149cdb46e1
commit a0a8ad04de
6 changed files with 730 additions and 0 deletions
@@ -17,6 +17,12 @@ Dieses Verzeichnis ist zugleich der Web-Root der NAS
 Der Arbeitsordner *ist* die laufende Anwendung — jede gespeicherte Datei ist
 sofort live.
 Für zwei Teile reicht diese Landkarte nicht, weil ihr Verhalten aus dem
 Zusammenspiel von Editor, Datenbank und Runner entsteht. Sie haben eigene,
 ausführliche Dokumente unter [`doku/`](doku/README.md):
 **[Automatiken](doku/automatiken.md)** und
 **[Zeitleiste](doku/zeitleiste.md)**.
 ---
 ## Inhalt
@@ -0,0 +1,79 @@
 # Vertiefende Dokumentation
 Die [README im Wurzelverzeichnis](../README.md) beschreibt das Ganze: welche
 Seite es gibt, welche Datei was tut, wo eine Zahl herkommt. Sie ist die
 Landkarte.
 Hier liegen die **Tiefenbohrungen** — für die Teile, bei denen die Landkarte
 nicht reicht, weil das Verhalten aus dem Zusammenspiel mehrerer Prozesse
 entsteht und die Regeln nicht aus dem Quelltext einer einzelnen Datei
 abzulesen sind.
 | Dokument | Worum es geht |
 |---|---|
 | [automatiken.md](automatiken.md) | Die Automatiken (AutoActions): Datenmodell, Editor, Runner, wie eine Bedingung wirklich ausgewertet wird, Verkettung, Sperren, Fehlerbilder |
 | [zeitleiste.md](zeitleiste.md) | Die Zeitleiste der Automatiken: wie der Server den Tag ausrechnet und wie der Browser ihn zeichnet |
 ---
 ## Die drei Prozesse, die zusammenspielen
 Nichts hier ist eine einzelne Anwendung. Drei Dinge laufen gleichzeitig, und
 sie reden nur über MQTT und über die Datenbanken miteinander — nie direkt.
 ```mermaid
 flowchart LR
  subgraph Browser["Browser"]
    UI["Weboberfläche<br/><small>PHP + JS, /volume1/web/smart</small>"]
  end
  subgraph NAS["NAS, Hintergrundprozesse (SolarManager)"]
    RUN["autoaction_runner.py<br/><small>führt Automatiken aus</small>"]
    SM["solarManager.py<br/><small>sammelt Anlagenwerte</small>"]
    SK["gatherSkodaData.py<br/><small>Fahrzeug</small>"]
  end
  subgraph Speicher["Speicher"]
    MQTT[["MQTT-Broker<br/><small>alles Aktuelle</small>"]]
    HM[("homeMesh<br/><small>Geräte, Automatiken, Grundriss</small>")]
    SL[("solarLog<br/><small>Messreihen, Sonnenzeiten</small>")]
  end
  subgraph Geraete["Geräte"]
    TAH["Tahoma-Box<br/><small>Jalousien</small>"]
    SHE["Shelly, WLED, ESP32"]
  end
  UI -- "liest/schreibt Regeln" --> HM
  UI -- "abonniert" --> MQTT
  UI -- "schaltet von Hand" --> TAH & SHE
  RUN -- "Regelwerk" --> HM
  RUN -- "Messwerte zurück" --> HM
  RUN -- "Sonnenzeiten" --> SL
  RUN -- "hört + schaltet" --> MQTT
  RUN -- "liest + schaltet" --> TAH & SHE
  SM --> MQTT & SL
  SK --> SL
 ```
 **Wichtig für das Verständnis aller folgenden Kapitel:**
 * Die **Weboberfläche schaltet nichts von selbst.** Sie beschreibt, was
  gelten soll (`homeMesh`), und zeigt, was ist. Ausgeführt wird im Runner.
 * **`actor_states.current_value` pflegt der Runner.** Ohne ihn stünde dort
  der Wert vom Tag des Gerätesuchlaufs. Deshalb zeigt auch der Editor
  aktuelle Zahlen, obwohl er nur eine Tabelle liest.
 * Der Runner ist ein **Dauerprozess, kein Cronjob** — er braucht den
  Vorzustand (`cond_met`), um steigende Flanken zu erkennen.
 ---
 ## Lesereihenfolge
 1. [README](../README.md), Abschnitt „Auf einen Blick“ — Seiten und Dateien.
 2. [automatiken.md](automatiken.md) — das Regelwerk und seine Ausführung.
 3. [zeitleiste.md](zeitleiste.md) — die Darstellung desselben Regelwerks
   über einen Tag.
 Wer nur etwas ändern will, findet die Einstiegspunkte am Ende beider
 Dokumente unter „Wo fange ich an, wenn ich …“.
@@ -0,0 +1,409 @@
 # Die Automatiken (AutoActions)
 Eine Automatik ist ein Satz: **„Wenn … , dann …, aber nur wenn der Rahmen
 passt.“** Sie wird im Browser gebaut, liegt in der Datenbank `homeMesh` und
 wird von einem Dauerprozess auf der NAS ausgeführt.
 ```
   Rahmen              Auslöser                         Aktionen
   ──────              ────────                         ────────
   Mo–Fr,              Uhrzeit  um 07:00                Magdalena Fenster: Auf
   nicht in Ferien,    UND Außentemperatur > −10 °C     Magdalena Tür:     Auf
   06:00–09:00,
   Sperrzeit 15 min
 ```
 Beteiligt sind drei Stellen:
 | Wo | Datei | Aufgabe |
 |---|---|---|
 | Browser | `js/solar/autoActionFuncs.js` | Editor: Modell bauen, zeichnen, abschicken |
 | Web-Server | `restricted/automations.php`, `ajax/AutoAction.php` | Laden, Prüfen, Speichern, Beschreiben |
 | NAS | `SolarManager/autoActions/autoaction_runner.py` | Auswerten und Ausführen |
 ![Der Automatik-Editor](bilder/editor.png)
 ---
 ## 1. Datenmodell
 Alles steht in `homeMesh` — dort, wo auch die Geräte liegen, damit
 Fremdschlüssel greifen können. Schema: [`homeMesh_automations.sql`](../homeMesh_automations.sql).
 ```mermaid
 erDiagram
  actors ||--o{ actor_states : "hat Messwerte"
  actors ||--o{ actor_commands : "hat Kommandos"
  actor_commands ||--o{ command_parameters : "hat Parameter"
  automations ||--o{ automation_conditions : "Auslöser"
  automations ||--o{ automation_actions : "Aktionen"
  automations ||--o{ automation_log : "Protokoll"
  automation_actions ||--o{ automation_action_params : "Werte"
  actor_states ||--o{ automation_conditions : "state_id"
  actor_commands ||--o{ automation_actions : "command_id"
  command_parameters ||--o{ automation_action_params : "parameter_id"
  automations {
    int id
    varchar name
    varchar floor "Reiter in der Übersicht"
    tinyint enabled "pausiert oder nicht"
    time window_from "Rahmen: Zeitfenster"
    time window_to
    tinyint weekdays "Bitmaske Mo..So"
    tinyint on_vacation "0 nie, 1 egal, 2 zusätzlich"
    tinyint on_holiday "0 nie, 1 egal, 2 zusätzlich"
    tinyint next_day "Rahmen gilt für morgen"
    tinyint force_once "am Fensterende notfalls doch"
    tinyint once_per_day "höchstens einmal am Tag"
    int lockout_secs "Sperrzeit nach einem Lauf"
    tinyint cond_met "Laufzustand: war die Bedingung zuletzt wahr?"
    datetime last_run "Laufzustand: wann zuletzt ausgelöst"
    timestamp changed "Signal an den Runner"
  }
  automation_conditions {
    int automation_id
    int group_no "gleich = UND, verschieden = ODER"
    int state_id "zeigt auf actor_states"
    enum operator "ASCII, nie das hübsche Zeichen"
    varchar value "Schwelle als Text"
  }
 ```
 Drei Felder sind **nachgerüstet** und stehen deshalb nicht in der
 Schema-Datei, sondern in eigenen Skripten im SolarManager-Repo
 (`autoActions/`): `next_day` (`vorabend.sql`), `once_per_day` und die
 Dreiwertigkeit von `on_vacation`/`on_holiday` (`rahmen_erweitern.sql`),
 sowie der Datentyp `elapsed` samt gerechnetem Gerät „Automatiken“
 (`automatik_ausloeser.sql`). Wer die Datenbank neu aufsetzt, spielt sie nach
 `homeMesh_automations.sql` ein.
 Drei Spalten in `automations` sind **kein Regelwerk, sondern Laufzustand**:
 `cond_met`, `last_run` und `changed`. Sie werden vom Runner geschrieben.
 Wer eine Automatik per SQL kopiert, sollte sie leeren.
 ### Warum `state_id` und nicht „Gerät + Feld“
 Eine Bedingung zeigt mit einer einzigen Zahl auf `actor_states`. Damit hängen
 Gerät, Messwertname, Datentyp, Einheit und Quelle (Topic, HTTP-Feld, Tahoma)
 an dieser Zeile. Der Editor muss nichts davon wissen: Er listet Geräte und
 deren Messwerte. Genau deshalb funktioniert auch die Verkettung
 (→ [Abschnitt 6](#6-verkettung-eine-automatik-löst-die-nächste-aus)) ohne eine
 einzige Sonderregel im Editor.
 ---
 ## 2. Der Editor
 Der Editor arbeitet **auf einem Modell und zeichnet daraus die Oberfläche** —
 nicht umgekehrt:
 ```js
 autoModel.groups  = [ [ {state_id, operator, value}, … ], … ]   // innen UND, außen ODER
 autoModel.actions = [ {command_id, params: {parameterID: wert}}, … ]
 ```
 Der Gerätekatalog (`deviceCatalog()`) kommt **im selben Dokument** mit, es
 gibt also kein Nachladen je Zeile.
 ```mermaid
 sequenceDiagram
  autonumber
  participant B as Browser<br/>autoActionFuncs.js
  participant A as ajax/AutoAction.php
  participant M as restricted/automations.php
  participant DB as homeMesh
  B->>A: GET ?action=editor&id=42
  A->>M: loadAutomation(42) + deviceCatalog()
  M->>DB: SELECT automations / conditions / actions
  A-->>B: HTML + Katalog + Datensatz (ein Dokument)
  Note over B: autoModel füllen, rendern
  loop alle 8 s, solange der Editor offen ist
    B->>A: GET ?action=werte&ids=…
    A->>DB: SELECT current_value FROM actor_states
    A-->>B: aktuelle Messwerte → Punkte neben den Zeilen
  end
  B->>A: POST ?action=save (JSON)
  A->>M: saveAutomation()
  M->>M: pruefeKreis()
  M->>DB: UPDATE automations; DELETE+INSERT conditions/actions
  A-->>B: {ok, id}
  Note over DB: changed = NOW() → der Runner lädt neu
 ```
 Drei Eigenheiten, die man kennen sollte:
 * **Speichern heißt löschen und neu einfügen.** Bedingungen und Aktionen
  bekommen dabei neue IDs. Deshalb reicht `changed` allein dem Runner nicht,
  um Änderungen zu erkennen (→ [Abschnitt 4](#4-der-runner)).
 * **Live-Werte neben jeder Bedingung** kommen aus `actor_states`, nicht aus
  MQTT: Über den Broker kommt nur ein Teil der Geräte (Jalousien hängen an
  der Tahoma-Box, gerechnete Werte an gar nichts). Eine Tabelle, ein Zugriff,
  alle Gerätearten.
 * **Kreise werden beim Speichern abgelehnt** (`pruefeKreis()`), nicht im
  Betrieb geheilt. Im Protokoll sähe ein Kreis nur wie „läuft halt oft“ aus.
 ### Der Rahmen in Worten
 `rahmenText()` im Editor und `describeConditions()` auf dem Server erzeugen
 denselben Satz in Alltagssprache („werktags, 06:00–09:00, höchstens einmal
 am Tag“). Wer die Bedeutung eines Feldes ändert, muss beide anfassen —
 sonst steht in der Übersicht etwas anderes als im Editor.
 ---
 ## 3. Die drei Teile einer Automatik
 ### 3.1 Rahmen: darf sie überhaupt?
 | Feld | Bedeutung | Fallstrick |
 |---|---|---|
 | `enabled` | pausiert oder nicht | Pausierte laden der Runner gar nicht erst — ihre Nachfolger stehen mit still |
 | `weekdays` | Bitmaske, Bit 0 = Montag | |
 | `on_vacation`, `on_holiday` | **dreiwertig**: 0 nie, 1 egal, 2 zusätzlich | „zusätzlich“ zählt wie ein passender Wochentag; ein Verbot schlägt eine Erweiterung |
 | `next_day` | Der Rahmen gilt für **morgen** (Vorabend-Form) | Uhrzeit und Fenster bleiben bei heute |
 | `window_from`/`window_to` | Zeitfenster; `von > bis` heißt über Mitternacht | |
 | `lockout_secs` | Sperrzeit nach einem Lauf (0 / 60 / 900) | |
 | `once_per_day` | höchstens ein Lauf je Kalendertag | |
 | `force_once` | am Ende des Fensters notfalls doch ausführen | greift nur, wenn im Fenster gar nichts lief |
 Warum dreiwertig? „Wochenenden **und** Feiertage“ ließ sich vorher nicht
 schreiben: Die Wochentagsmaske kennt nur Sa und So, und ein Feiertag am
 Dienstag ist eben ein Dienstag. Mit „Feiertage: zusätzlich“ kommt er über
 den Kalender (`calendar_days`, gefüllt von `fetch_calendar.py`) herein.
 Warum `next_day`? „Kinderrollos zu, wenn **morgen** Schule ist“ ließ sich mit
 dem heutigen Tag nur annähern (So–Do, heute keine Ferien) — und das ging am
 letzten Ferientag, am Abend vor einem Feiertag und am Abend eines Feiertags
 daneben.
 ### 3.2 Auslöser: `any(all(gruppe))`
 Bedingungen mit derselben `group_no` sind mit **UND** verknüpft, verschiedene
 Gruppen mit **ODER**. Im Editor ist eine Gruppe ein gerahmter Block und
 zwischen den Blöcken steht ein ODER — die Klammerung ist also gezeichnet und
 nicht bloß vereinbart.
 > Eine Automatik **ohne** Bedingung löst nie aus. Sonst würde sie nach einem
 > Gerätesuchlauf, der ihren Messwert entfernt hat, plötzlich dauernd feuern.
 ### 3.3 Aktionen
 Eine Aktion ist ein Kommando eines Geräts plus je Parameter ein Wert
 (`automation_action_params`, eine Zeile je Parameter statt fester Spalten).
 Geschickt wird über denselben Transport-Zoo wie beim Lesen
 (→ [Abschnitt 4](#4-der-runner)); Jalousien bekommen dabei die
 Kugelschreiber-Mechanik (erst Neigung 0, dann das Ziel), siehe
 `TahomaTransport` und `sendeTahoma()` in `restricted/commands.php`.
 ---
 ## 4. Der Runner
 `autoaction_runner.py` läuft als Dauerprozess.
 ```mermaid
 flowchart TB
  START([Start]) --> LOAD["Regelwerk laden<br/><small>Automatiken, Messwerte, Kommandos</small>"]
  LOAD --> SUB["MQTT abonnieren<br/>Sammlerfäden starten"]
  SUB --> TAKT
  subgraph TAKT["Takt, alle tick_seconds (10 s)"]
    direction TB
    T1["Werte einsammeln<br/><small>MQTT-Puffer + Queue der Sammler</small>"]
    T2["durchlauf(): jede Automatik prüfen"]
    T3["Ergebnisse des Versands verbuchen"]
    T4["alle reload_seconds: Signatur vergleichen"]
    T1 --> T2 --> T3 --> T4
  end
  T4 -- "Signatur geändert" --> LOAD
  T2 -- "Aktionen" --> VERSAND[["Versand<br/><small>je Gerät der Reihe nach,<br/>über Geräte hinweg parallel</small>"]]
  SAMMLER[["Sammler<br/><small>HTTP/WLED 1 min,<br/>Tahoma 5 min</small>"]] -. "Queue" .-> T1
 ```
 **Warum ein Dauerprozess und nicht Cron?**
 1. Schwellwerte („Temperatur über 22 °C“) sollen greifen, wenn die Nachricht
   hereinkommt — nicht im nächsten Minutenraster.
 2. Nur so gibt es einen Vorzustand für die steigende Flanke.
 3. `actor_states.current_value` würde sonst niemand fortschreiben.
 **Warum drei Fäden?** Früher wurde mitten in der Hauptschleife gepollt:
 neunzehn Tahoma-Geräte nacheinander, jedes mit bis zu zehn Sekunden
 Zeitlimit. Eine Runde dauerte 45 statt 30 Sekunden, dadurch kam **jede
 dritte Minute nie vor** — und ein Auslöser „um 18:26“ wurde schlicht nie
 wahr. Heute hat jeder Transport seinen eigenen Faden, die Hauptschleife
 macht nur noch Billiges, und die Uhr wird gar nicht mehr abgetastet, sondern
 gegen `datetime.now()` verglichen.
 ### Transporte
 | URL des Aktors | Transport | Lesen | Schreiben |
 |---|---|---|---|
 | `mqtt://…` | MQTT | abonniert, gepuffert | `publish` |
 | `http://…` | HTTP | Poll, 1 min | Abfrageargumente |
 | `wled://…` | WLED | Poll, 1 min | JSON an `/json/state` |
 | `io://`, `rts://`, `internal://`, `ogp://` | Tahoma | Poll, 5 min | `exec/apply` |
 | `Logic` | gerechnet | Uhrzeit, Datum, Sonnenauf-/-untergang | — |
 | `Automatik` | gerechnet | letzte Auslösung je Automatik | — |
 Ausnahme beim Lesen: Steht in `actor_states.url` ein **Topic**, liest der
 MQTT-Transport — auch wenn das Gerät über HTTP geschaltet wird. So sind die
 Shellys der zweiten Generation angebunden.
 ### Woran der Runner merkt, dass er neu laden muss
 Nicht an `changed` allein — eine gelöschte Automatik ändert den größten
 Zeitstempel nicht, und wer nur die Uhrzeit einer Bedingung verstellt, ändert
 in `automations` gar keine Spalte. Stattdessen eine **Signatur**: Zeilenzahl
 plus Summe der `CRC32` je Zeile, über Bedingungen, Aktionen, Aktionsparameter
 *und* die Gerätetabellen (dort auch `url` und `value_path`, weil ein
 Discovery-Lauf bestehende Zeilen umschreibt).
 ---
 ## 5. Die Auswertung im Detail
 Das Herzstück, `durchlauf()`, für jede Automatik in topologischer Reihenfolge
 (Auslöser vor Nachfolger):
 ```mermaid
 flowchart TB
  A["Tag bestimmen<br/><small>heute, mit next_day morgen</small>"] --> B{"tag_passt?<br/><small>Wochentag, Ferien, Feiertag</small>"}
  B -- nein --> Z1
  B -- ja --> C{"im Zeitfenster?"}
  C -- nein --> Z1["Fenster zu:<br/>force_once prüfen,<br/>Flanke zurücksetzen"]
  C -- ja --> D{"Bedingung erfüllt?<br/><small>any(all(gruppe))</small>"}
  D -- nein --> E["cond_met = 0"]
  D -- ja --> F{"cond_met schon 1?"}
  F -- ja --> G["nichts tun<br/><small>keine neue Flanke</small>"]
  F -- nein --> H{"once_per_day<br/>und lief heute?"}
  H -- ja --> G
  H -- nein --> I{"innerhalb<br/>lockout_secs?"}
  I -- ja --> J["Flanke verwerfen"]
  I -- nein --> K["ausloesen()"]
  K --> L["Aktionen in den Versand,<br/>last_run + Protokoll,<br/>eigenen Auslöserwert setzen"]
 ```
 ### Nur die steigende Flanke
 `cond_met` hält fest, ob die Bedingung beim letzten Durchlauf schon erfüllt
 war. Ohne das würde „Temperatur über 22 °C“ in jedem Takt erneut feuern.
 ### Die drei Zeitformen
 | Schreibweise | Operator | Bedeutung | Gedacht für |
 |---|---|---|---|
 | `um 16:30` | `=` | ab dieser Minute, plus **Nachholfenster** (5 min) | der Normalfall: einmal täglich zu einem Termin |
 | `ab 16:30` | `>=` | von da bis Mitternacht wahr | alles, was auch nach einem verpassten Takt noch laufen soll (Bewässerung) |
 | `vor 16:30` | `<` | bis dahin wahr | als Zusatzbedingung |
 Ausgelöst wird in allen drei Fällen **höchstens einmal** — wegen der Flanke.
 Das Nachholfenster ersetzt die früher verlangte Punktgenauigkeit: Ein
 Neustart oder ein hängendes Gerät kostet die Automatik nicht mehr den ganzen
 Tag. Gerechnet wird modulo 24 h, damit ein Ziel um 23:58 auch um 00:01 noch
 zieht.
 ```
  Takt:      ▼    ▼    ▼    ▼    ▼    ▼    ▼    ▼   (alle 10 s)
             │              │
  um 16:30   └── wahr ──────┘  (16:30:00 bis 16:34:59, Nachholfenster)
                 ↑ Flanke: genau hier wird ausgelöst
  ab 16:30   └── wahr ───────────────────────────────────► 23:59
                 ↑ Flanke: ebenfalls nur einmal
 ```
 ### Sonnenstand und Ketten
 Beim Sonnenauf-/-untergang trägt der Operator zusätzlich **das Vorzeichen des
 Versatzes**: `+ 00:30` = eine halbe Stunde danach, `>=- 00:30` = ab einer
 halben Stunde davor, `<+ 00:30` = bis eine halbe Stunde danach. Über den
 Tagesrand wird gerechnet und nicht abgeschnitten — „sechs Stunden vor
 Sonnenaufgang“ landet dann eben am Vorabend.
 Beim Datentyp `elapsed` (Verkettung) ist es fast dasselbe, mit einem
 wichtigen Unterschied: Verglichen wird der **echte Abstand**, nicht die
 Uhrzeit im Tag. Sonst machte ein Lauf von vorgestern um 05:50 die Bedingung
 heute um 06:00 wahr, an einem Tag, an dem der Auslöser gar nicht lief.
 `ab + 00:10` gilt zusätzlich nur am selben Kalendertag.
 ### Sperrzeit, „einmal am Tag“, „auf jeden Fall“
 | Mittel | Wogegen | Verhalten |
 |---|---|---|
 | `lockout_secs` | Messwerte, die um die Schwelle pendeln (22,1 / 21,9 / 22,1) | Die Flanke wird **verworfen**, nicht aufgehoben — ein Rollladen, der eine Viertelstunde später doch losfährt, wäre unangenehmer als einer, der gar nicht fährt |
 | `once_per_day` | Dinge, die man hinterher von Hand anders stellt | Nach dem ersten Lauf ist bis Mitternacht Ruhe. Die Sperrzeit taugt dafür nicht: sie zählt Sekunden und verfehlte am nächsten Morgen den Termin |
 | `force_once` | verpasste Fenster | Beim Zugehen des Fensters, aber nur, wenn darin nichts lief (zusätzlich gegen `last_run` geprüft, damit ein Neustart nicht doppelt auslöst) |
 ---
 ## 6. Verkettung: eine Automatik löst die nächste aus
 Das gerechnete Gerät **„Automatiken“** führt jede Automatik als Messwert;
 ihr Wert ist der Zeitpunkt der letzten Auslösung (Datentyp `elapsed`, URL
 `auto:<id>`). Damit ist eine Automatik für den Editor ein Messwert wie jeder
 andere — „Wecker Magdalena + 00:10“.
 ```mermaid
 flowchart LR
  W["Wecker Magdalena<br/><small>um 07:00</small>"] -->|"+ 00:10"| R["Magdalena Rollos<br/><small>und es ist hell</small>"]
  R -->|"+ 00:05"| S["Schlafzimmer<br/>Tür auf"]
 ```
 Warum nicht einfach eine Verzögerung an der Aktion? Weil der Nachfolger eine
 **vollwertige Automatik mit eigenem Rahmen** bleiben soll: „zehn Minuten
 später, aber nur wenn es dann schon hell ist“ ließe sich als bloße
 Verzögerung nicht formulieren — die Zusatzbedingung gilt erst zum späteren
 Zeitpunkt.
 Was daran hängt:
 * **Reihenfolge:** `reihenfolge_bestimmen()` sortiert topologisch, damit ein
  Versatz von null noch im selben Takt greift. Nach dem Auslösen trägt der
  Runner den eigenen Auslöserwert sofort nach.
 * **Pausieren wirkt weiter:** Der Runner lädt nur `enabled = 1`. Wer den
  Wecker pausiert, lässt morgens auch die Rollos unten — gewollt.
 * **Anlegen/Löschen der Messwerte** macht `ausloeser_nachfuehren()` vor jedem
  Regelwerk-Laden. Angelegt wird auch für pausierte Automatiken, sonst
  löschte `ON DELETE CASCADE` still die Bedingung des Nachfolgers.
 * **Löschen mit Anhang:** `deleteAutomation($id, "abhaengen"|"mitloeschen")`.
  Der Editor fragt nach, wenn Nachfolger existieren.
 * **Kreise** lehnt der Server beim Speichern ab; der Runner meldet sie nur
  und lässt die Beteiligten weiterlaufen.
 ---
 ## 7. Protokoll und Fehlerbilder
 `automation_log` bekommt je Lauf eine Zeile (`fired` / `forced`) und je
 fehlgeschlagenem Kommando eine weitere (`error`). Einträge älter als 30 Tage
 räumt der Runner selbst weg.
 | Beobachtung | Wahrscheinliche Ursache |
 |---|---|
 | Automatik läuft gar nicht, ohne Protokolleintrag | Rahmen: falscher Wochentag, Ferien/Feiertag auf „nie“, Fenster zu eng — oder die Bedingung war nie *neu* erfüllt (`cond_met` stand schon auf 1) |
 | Läuft einmal und dann nicht mehr am selben Tag | `once_per_day` |
 | Läuft kurz nacheinander nicht erneut | `lockout_secs` |
 | Kette bleibt stehen | Auslöser pausiert oder an dem Tag nicht dran |
 | Änderung im Editor wirkt nicht | Regelwerk-Signatur: erst beim nächsten `reload_seconds`-Fenster (30 s) |
 | `error` im Protokoll | Gerät nicht erreichbar, Kommando oder Transport gibt es nicht mehr |
 ---
 ## 8. Wo fange ich an, wenn ich …
 | Vorhaben | Ort |
 |---|---|
 | … einen neuen Operator oder Datentyp anbieten | `operatorsForType()` in `restricted/automations.php` **und** `bedingung_erfuellt()` im Runner |
 | … ein neues Rahmenfeld einführen | Spalte in `homeMesh_automations.sql`, `saveAutomation()`/`loadAutomation()`, Editor (`renderRahmen`, `leseFormular`), `durchlauf()` im Runner, Satz in `rahmenText()` |
 | … eine neue Geräteart anschließen | eine Klasse in `SolarManager/autoActions/transports.py` (Lesen + Senden), Erkennung an der Aktor-URL |
 | … verstehen, warum etwas lief | `automation_log`, dann die Zeitleiste des Tages (→ [zeitleiste.md](zeitleiste.md)) |
 | … das Nachholfenster ändern | `catchup_minutes` in `config.ini` des Runners |
@@ -0,0 +1,236 @@
 # Die Zeitleiste der Automatiken
 Die Übersicht als Tabelle beantwortete nicht, was man eigentlich wissen will:
 **Läuft der Tag stimmig, und warum ist etwas noch nicht gefahren?** Die
 Zeitleiste legt deshalb jede Automatik auf die Stunde, zu der sie greift.
 ![Die Zeitleiste](bilder/zeitleiste.png)
 Zwei Dateien teilen sich die Arbeit, und die Trennung ist scharf:
 | Datei | Aufgabe |
 |---|---|
 | `restricted/zeitleiste.php` | **rechnen**: wo liegt eine Automatik auf dem Tag, in welcher Bahn, ist sie heute dran, ist sie gelaufen |
 | `js/solar/zeitleiste.js` | **zeichnen**: Bahnen, Stapeln, Etiketten, Kettenbögen, Karte, Filter |
 Geliefert wird über `ajax/AutoAction.php?action=zeitleiste&datum=YYYY-MM-DD`
 als JSON.
 ---
 ## 1. Was der Server ausrechnet
 ```mermaid
 flowchart TB
  A["Alle Automatiken laden<br/><small>loadAutomation() je Id</small>"] --> B["Bedingungen je ODER-Gruppe einsortieren"]
  B --> C{"Was trägt die Gruppe?"}
  C -->|"Uhrzeit =, Sonne ±"| P["punkt"]
  C -->|"Uhrzeit >= / <"| F["start / ende"]
  C -->|"Automatik + Versatz"| K["kette + versatz"]
  C -->|"alles andere"| S["sensor = true<br/><small>wartet auf einen Messwert</small>"]
  P & F & K & S --> D["Art bestimmen:<br/>punkt › kette › fenster › jederzeit"]
  D --> E["Ketten auflösen<br/><small>bis zu 6 Runden</small>"]
  E --> G["Bahn, Satz, Tagesprüfung, Läufe"]
  G --> H[["JSON"]]
 ```
 ### 1.1 Die Regeln, wie eine Lage entsteht
 | Bedingung | Ergebnis auf dem Tag |
 |---|---|
 | feste Uhrzeit `um 07:00` | **Punkt** |
 | Sonnenauf-/-untergang ± Versatz | **Punkt**, an diesem Tag ausgerechnet |
 | andere Automatik `+ 00:10` | **Kette**: Punkt hinter dem Auslöser |
 | `ab …` / `vor …` oder ein eingeengtes Zeitfenster | **Balken** über das Fenster |
 | nur Messwerte, ganzer Tag | **„jederzeit“** (eigenes Band unter der Leiste) |
 Mehrere Gruppen (ODER) werden zusammengefasst: Gibt es Punkte, gewinnt der
 früheste; sonst eine Kette; sonst das umschließende Fenster aus allen
 Gruppengrenzen. Trägt eine Gruppe einen zeitlich bestimmten Beginn (etwa
 „Sonnenuntergang + 30 **oder** dunkel“), merkt sich der Eintrag ihn als
 `punkt` — er erscheint im Hinweis als „frühestens 19:01“.
 ### 1.2 Ketten auflösen
 Die Lage eines Nachfolgers hängt vom Auslöser ab, und die Kette kann mehrere
 Stufen haben (Wecker → Rollos → Schlafzimmer). Deshalb läuft die Auflösung
 reihum, höchstens sechs Runden:
 | Zustand des Auslösers | Nachfolger |
 |---|---|
 | ist an diesem Tag schon **gelaufen** | Punkt bei der echten Laufzeit + Versatz |
 | hat einen **Punkt** | Punkt dort + Versatz |
 | ist ein **Fenster** | Fenster ab dessen Beginn + Versatz |
 | hat selbst keine Lage / Kreis | „jederzeit“ |
 Immer begrenzt auf das eigene Zeitfenster. Und: Der Nachfolger **erbt**, ob
 der Tag passt — läuft der Wecker heute nicht, steht auch das Rollo
 gestrichelt da, mit dem Grund „Auslöser ‚Wecker Magdalena‘ ist nicht dran“.
 ### 1.3 Ist sie heute überhaupt dran?
 `zlTagPasst()` rechnet **genau wie der Runner** (`tag_passt()` und
 `gemeinter_tag()`): erst öffnen (Wochentag, „zusätzlich“ an Ferien/Feiertagen),
 dann sperren (Ferien/Feiertage auf „nie“), und bei `next_day` für morgen.
 Sonst hieße „heute nicht“ hier etwas anderes als dort.
 > Ausgeblendet wird trotzdem nichts. Wer nicht dran ist, steht gestrichelt
 > da — mit Grund im Hinweis. Eine Zeitleiste, die Einträge verschweigt,
 > beantwortet die Frage „warum ist das nicht gefahren?“ gerade nicht.
 ### 1.4 Sonnenzeiten für beliebige Tage
 `solarLog.daylight` kennt heute, morgen und die Vergangenheit. Für einen
 späteren Tag nimmt `zlSonne()` denselben Kalendertag eines Vorjahres — die
 Sonne verschiebt sich von Jahr zu Jahr um weniger als eine Minute, und so
 braucht es keinen Standort, der in einem anderen Haus wieder falsch wäre.
 Im Hinweis steht dann „(Vorjahr)“.
 ### 1.5 Die Bahn
 Die Zeile, in der eine Automatik steht, ergibt sich aus den **Geräten, die
 sie schaltet** — dieselbe Einordnung wie im Raum-Modal (`bedienform()` in
 `roomControls.php`), Mehrheit gewinnt, bei Gleichstand die Bahn weiter oben.
 Bewässerung ist dort „sonstiges“ und wird am Gerätetyp erkannt.
 Bahnen: Licht · Beschattung · Heizung · Bewässerung · Schalter · Sonstiges.
 ### 1.6 Das JSON
 ```jsonc
 {
  "datum": "2026-09-21", "heute": true, "jetzt": 964,   // Minuten seit Mitternacht
  "sonne": { "auf": 431, "unter": 1176, "genau": true },
  "bahnen": { "licht": {"titel": "Licht", "symbol": "bi-lightbulb"}, … },
  "etagen": [ {"code": "OG", "label": "Obergeschoss"}, … ],
  "automatiken": [{
    "id": 18, "name": "Hitzeschutz Süd", "floor": "EG", "enabled": true,
    "dran": true, "grund": "",
    "bahn": "beschattung",
    "satz": "Wozi Schiebetür, Wozi Fensterfront +1: Position+Neigung",
    "wenn": "Sonne Süd: Helligkeit > 30000 Lux und …",
    "laeufe": ["12:50"],                 // aus automation_log
    "art": "fenster",                    // punkt | fenster | kette | jederzeit
    "punkt": 570, "von": 570, "bis": 1080,
    "kette": null, "versatz": 0,
    "sonne": false,                      // Lage kommt vom Sonnenstand
    "wartet": true                       // hängt an einem Messwert
  }]
 }
 ```
 ---
 ## 2. Was der Browser daraus macht
 ```mermaid
 flowchart TB
  L["zeitleisteLaden()<br/><small>fetch ?action=zeitleiste</small>"] --> Z["zeitleisteZeichnen()"]
  Z --> F["Etagenfilter anwenden"]
  F --> T["Dreiteilung:<br/>gelegt · jederzeit · pausiert"]
  T --> ST["je Bahn: zlStapeln()<br/><small>Zeilen wie im Kalender</small>"]
  ST --> HTML["HTML bauen:<br/>Achse, Bahnen, Bänder, Legende"]
  HTML --> KET["zlKettenZeichnen()<br/><small>SVG-Bögen, nach dem Layout</small>"]
  KET --> SCR["Scrollstand setzen"]
  SCR --> KAR["offene Karte wieder öffnen"]
 ```
 Jede Automatik erscheint **genau einmal**: in ihrer Bahn, unter „Jederzeit“
 oder unter „Pausiert“. Der Zähler oben („22 von 22 · 3 pausiert“) ist die
 Probe aufs Exempel — fehlte eine, fiele es dort auf.
 ### 2.1 Stapeln: warum in Pixeln und nicht in Minuten
 Zwei Punkte zehn Minuten auseinander liegen zeitlich getrennt — ihre
 **Beschriftungen** aber übereinander. `zlStapeln()` rechnet deshalb in
 Pixeln: Es misst den Etikett-Text (einmal ein Canvas, dann nur messen) und
 legt jeden Eintrag in die erste Zeile, in der er nichts überdeckt.
 ```
  Zeile 0   ●07:00 Wecker Magdalena      ▭ 09:30–18:00 Hitzeschutz Süd ✓12:50
  Zeile 1        ●07:08 Wecker Rollos            ●15:59 Hitzeschutz Süd zurück
             └── Nachfolger direkt unter seinem Auslöser
 ```
 Drei Sonderfälle stecken darin:
 * **Punkt am rechten Rand** trägt sein Etikett links von sich — die Marke
  bleibt, wo die Zeit ist.
 * **Fenster-Etikett** rückt nie vor seinen Balken; sonst sähe „15:00–18:31“
  aus, als finge es um halb elf an. Reicht der Platz nicht, wird der Name
  gekürzt (voll steht er im Hinweis).
 * **Ketten bleiben beisammen:** Eingesetzt wird familienweise — erst der
  Auslöser, gleich danach seine Nachfolger in die erste freie Zeile
  *darunter*. Je Zeile werden belegte Strecken geführt, nicht nur ihr Ende,
  weil ein Nachfolger links von etwas liegen kann, das schon steht.
 ### 2.2 Zustand, Farbe, Form
 `zlZustand()` kennt fünf Zustände — sie bestimmen Farbe und Zeichen:
 | Zustand | Wann | Darstellung |
 |---|---|---|
 | `nichtdran` | Tag passt nicht | gestrichelt, Kalendersymbol, Grund im Hinweis |
 | `gelaufen` | es gibt Läufe an dem Tag | Haken und echte Laufzeit |
 | `vorbei` | Zeit liegt hinter „jetzt“, nichts gelaufen | matt |
 | `aktiv` | „jetzt“ liegt im Fenster / hinter dem Punkt | hervorgehoben |
 | `kommt` | liegt noch vor uns | normal |
 Beim Punkt zeigt das Etikett nach einem Lauf die **echte** Zeit, beim Fenster
 immer das Fenster und den Lauf hinten mit Haken — sonst stünde „12:50“ am
 Balkenanfang bei 09:30.
 ### 2.3 Kettenbögen
 Erst **nach** dem Einsetzen gezeichnet, weil die Lage beider Enden aus dem
 Layout kommt. Die Linie verlässt den Auslöser lotrecht nach unten und biegt
 mit einer kleinen Rundung von links in den Nachfolger ein; liegt der
 Nachfolger links vom Auslöser, kommt sie von oben an. Jeder Pfad trägt
 `data-von`/`data-nach`, damit das Überfahren eines Eintrags seine ganze Kette
 hell schaltet (`zlKetteHervorheben()`).
 ### 2.4 Die Karte
 Ein Klick auf einen Eintrag öffnet eine kleine Karte: was die Automatik tut,
 wann, wie sie heute steht — und die drei Dinge, die man damit tun will
 (Bearbeiten, Pausieren, Löschen). Pausieren und Löschen gehen über dieselben
 Funktionen wie in der Liste, samt Rückfrage nach abhängigen Automatiken.
 Zwei Fallen stecken in dieser Karte, beide behoben:
 1. **Die Karte machte eine zweite Bildlaufleiste.** AdminLTE gibt
   `main.app-main` `overflow: auto` bei Inhaltshöhe. Wurde die Karte zum
   Messen kurz ohne Lage eingehängt, stand sie unterhalb aller Bahnen und
   ragte aus `main` — Chrome zeigte dann dauerhaft eine eigene Leiste.
   Heute wird sie unsichtbar oben links eingehängt, gemessen und erst dann
   platziert.
 2. **Die Karte verschwand sofort wieder.** Die neue Leiste machte die
   Zeitleiste schmaler, der `ResizeObserver` zeichnete neu — und dabei ging
   die Karte verloren. Heute merkt sich `zeitleisteZeichnen()`, welche Karte
   offen war, und öffnet sie danach wieder. Außerdem klappt die Karte nach
   oben, wenn sie unten aus `main` liefe.
 ### 2.5 Was ein Neuzeichnen auslöst
 | Anlass | Folge |
 |---|---|
 | Tag wechseln, Ansicht öffnen | `zeitleisteLaden()` — neue Daten vom Server |
 | Etagenfilter | nur `zeitleisteZeichnen()`, Auswahl in `localStorage` |
 | Breite ändert sich (> 4 px) | `zeitleisteZeichnen()` nach 120 ms |
 | Minutentakt (nur heute, Tab sichtbar) | `zeitleisteLaden()` — „jetzt“-Linie und neue Läufe |
 | nach Speichern/Pausieren/Löschen | `refreshAutomations()` lädt die Zeitleiste mit |
 Was sich der Browser merkt: offene Ansicht (Zeitleiste oder Liste),
 Etagenfilter, Scrollstand innerhalb des Tages.
 ---
 ## 3. Wo fange ich an, wenn ich …
 | Vorhaben | Ort |
 |---|---|
 | … eine Bahn hinzufügen oder umbenennen | `zeitleisteBahnen()` in `restricted/zeitleiste.php`; Farbe in `css/solar.css` (`.zl-bahn-<name>`) |
 | … das Symbol einer Bahn ändern | ebenda — dasselbe Symbol muss auch im Raum-Modal und im Editor stehen (siehe `GERAETE_SYMBOL` in `autoActionFuncs.js`) |
 | … eine neue Art von Lage einführen | `zeitleiste()` (Gruppen-Auswertung + Art bestimmen), dann `zlLage()`/`zlEintrag()` im Browser |
 | … an der Höhe/Dichte schrauben | `ZL_ZEILE`, `ZL_KOPF`, `ZL_MIN_SPUR` in `js/solar/zeitleiste.js` |
 | … verstehen, warum ein Eintrag „nicht dran“ ist | `zlTagPasst()` — und zum Gegenprüfen `tag_passt()` im Runner |