sillyhome-next/docs/V1_0_0_OPERATING_GUIDE.md

SillyHome Next 1.0.0 Operating Guide

Diese Version stabilisiert den produktiven Kern: schnelle Dashboard-Nutzung, lokales Caching, klare Aktor-/Sensor-Kategorien und nachvollziehbare Freigabe gelernter Aktionen.

Grundprinzip

• Home Assistant bleibt die Quelle fuer aktuelle States und Services.
• SillyHome cached schwere Entity-/Discovery-Metadaten lokal als JSON.
• Die Startansicht liest nur lokale Store-/Cache-Daten.
• Vollstaendige Discovery, Vorschlaege und Detailanalysen laden blockweise nach.
• Es gibt keine externen Pings oder Cloud-Abfragen im Dashboard-Startpfad.

Wichtige Endpunkte

• GET /health
  Lokaler API-Status ohne externe Abfrage.
• GET /health/websocket
  Status des Home-Assistant-WebSocket-Listeners.
• GET /v1/actuators/dashboard
  Schnelle Dashboard-Startdaten aus Store und JSON-Cache.
• GET /v1/actuators/summary
  Schlanke Liste beobachteter Aktoren ohne Lernmuster-Payload.
• GET /v1/actuators/discovery
  Aktor-Auswahl aus gecachten oder frisch geladenen HA-Entities.
• GET /v1/actuators/context-options?actuator_entity_id=...
  Sensor-/Kontextvorschlaege fuer einen konkreten Aktor.
• POST /v1/actuators/{entity_id}/assignment
  Manuelle Sensor-/Kontextzuordnung speichern.
• POST /v1/actuators/{entity_id}/activation
  Freigabe oder Stop des automatischen Schaltens.

Cache

Der Entity-Cache liegt neben dem Aktor-Store als ha_entity_cache.json. Er enthaelt HA-Entity-Metadaten wie Friendly Name, Bereich, Device und Kategoriegrundlagen.

Der Cache wird geschrieben, wenn Discovery frische HA-Entities liest. Danach koennen Dashboard und Summary ohne erneute HA-Vollabfrage Namen, Raeume und Gruppen anzeigen.

Dashboard-Nutzung

1. Startansicht oeffnen.
2. System & Cache zeigt API, WebSocket, Cache-Groesse und geladene Discovery-Gruppen.
3. Geraet zum Lernen auswaehlen nutzt Suche, Typfilter und direkte Entity-ID-Eingabe.
4. Beobachtete Geraete zeigt gelernte Aktoren nach Raum oder Typ gruppiert.
5. Details zeigt Lernfortschritt, Freigabe, Vorhersage, verwendete Sensoren/Zustaende und Entscheidungsgruende.

Kategorien

Aktoren:

• Licht, LED, Lampen
• Schalter, Steckdosen, Helper
• Lueftung, Ventilatoren, Befeuchter/Entfeuchter
• Heizungen/Klima
• Rolllaeden/Cover
• TV/Medien/Fernbedienungen
• Szenen, Buttons, Schloesser, Ventile

Sensoren und Kontext:

• Luftfeuchtigkeit und Feuchte
• Temperatur
• Wetter
• Helligkeit/Lux
• Bewegung, Praesenz, Anwesenheit
• Tuer/Fenster/Oeffnung
• Licht-/Schalter-/Steckdosenstatus
• Strom, Leistung, Energie, Einspeisung
• PV, Akku, Wechselrichter
• Helper und Szenen

Qualitaetspruefung

Vor Release:

.venv/bin/pytest -q
.venv/bin/ruff check .
.venv/bin/mypy app backend tests
git diff --check

Live nach Installation:

wget -qO- http://58adbe1e-sillyhome-next:8000/health
wget -qO- http://58adbe1e-sillyhome-next:8000/health/websocket
wget -qO /tmp/summary.json http://58adbe1e-sillyhome-next:8000/v1/actuators/summary
wget -qO /tmp/dashboard.json http://58adbe1e-sillyhome-next:8000/v1/actuators/dashboard

Rollback

Der stabile Vor-1.0-Stand ist v0.7.21. Vor dem 1.0.0-Umbau wurde ein Git-Bundle-Backup erstellt:

/root/.openclaw/workspace/backups/sillyhome-next/

Bei Problemen kann auf v0.7.21 zurueck installiert werden.