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