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
@@ -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 …“.