Neustart-Erkennung dokumentiert (AGENTS.md CZ)

Co-Authored-By: Claude Opus 5 <[email protected]>
2026-09-05 13:33:28 +02:00
parent 189dff5255
commit ecea8a0c22
1 changed files with 70 additions and 0 deletions
@@ -11902,3 +11902,73 @@ Wert sofort in `fahrzeugprofil.json`.
 Dasselbe Muster wie beim Koordinatenfehler in Abschnitt CS: **ein fehlgeschlagener
 synthetischer Test ist kein Fehlerbeweis.** Erst mit echten Ereignissen pruefen,
 dann urteilen.
 ## CZ. Nicht jedes Update braucht einen Neustart (2026.9.5.24)
 Frage des Eigentuemers: *"warum brauchen unsere updates immer einen HA reboot?
 kannst du das nicht anders loesen?"* - Teils ja.
 ### Zwei Faelle, nur einer ist unvermeidlich
 **Python-Code: Neustart noetig.** Home Assistant importiert die Module der
 Integration einmal in seinen laufenden Prozess; daran haengen dann Entitaeten,
 Zeittakte, Horcher, der Koordinator. Eine ausgetauschte `.py` auf der Platte
 aendert daran nichts. `importlib.reload()` ueber alle Module waere technisch
 moeglich, liesse aber alte Objekte referenziert und ergaebe eine Mischung aus
 altem und neuem Code. Auch HACS verlangt deshalb einen Neustart. Bleibt so.
 **Oberflaechendateien: Neustart war unnoetig.** `frontend/` wird direkt von der
 Platte ausgeliefert - `StaticPathConfig(STATIK_URL, ordner, False)`, also ohne
 lange Cache-Vorgabe. Eine ersetzte `.js` ist sofort wirksam, es braucht nur ein
 Neuladen im Browser. Gebunden war das nur an unseren eigenen Cache-Brecher
 `?v={version}`, und der kam aus `async_get_integration()` - das liest aus
 `hass.data[DATA_INTEGRATIONS]` und haelt das Manifest fuer die Laufzeit fest.
 ### Die Unterscheidung ist bewusst schief
 `aktualisierung.neustart_noetig(alt, neu)` vergleicht beide Ordner ueber sha256
 je Datei (ohne `__pycache__`) und meldet **"kein Neustart" nur, wenn JEDE
 Abweichung** unter `frontend/` liegt oder die `manifest.json` ist. Alles
 andere - `.py`, `services.yaml`, `translations/`, `vorlage/` - gilt als
 neustartpflichtig, auch wo es das im Einzelfall nicht waere.
 Der Grund fuer die Schieflage: ein faelschlich ausgelassener Neustart laesst
 neuen Python-Code nie anlaufen, und der Fehler wird an ganz anderer Stelle
 gesucht. Ein ueberfluessiger Neustart kostet eine Minute.
 `manifest.json` ist ausgenommen, weil sich ihre Versionsnummer bei **jeder**
 Veroeffentlichung aendert - ohne die Ausnahme waere jedes Update ein
 Neustart-Update und die Unterscheidung wertlos. Weil HA das Manifest
 zwischenspeichert, liest `version_von_platte()` die Nummer direkt von der
 Platte, und `koordinator.version_neu_lesen()` zieht sie nach einem
 neustartfreien Update nach - sonst zeigten Panel und App weiter die alte
 Fassung, und niemand wuesste, ob das Update angekommen ist.
 Panel und App zeigen dann "Seite neu laden" statt "Installation abschliessen -
 Jetzt neu starten".
 ### Bekannte Schwaeche: Zeilenenden
 Verglichen werden Datei-Inhalte. Steht die installierte Fassung mit CRLF auf
 der Platte (Windows-Checkout, install.ps1) und kommt die neue aus dem
 Gitea-Archiv mit LF, unterscheiden sich **alle** Dateien - auch die
 `.py`-Dateien, deren Inhalt sachlich gleich ist. Das erste Update nach dieser
 Aenderung meldet deshalb moeglicherweise "Neustart noetig", obwohl nur die
 Oberflaeche gewechselt hat. Ab dem zweiten Update stammen beide Seiten aus dem
 Archiv und der Vergleich stimmt. Bewusst nicht wegnormalisiert: die
 Fehlerrichtung ist die sichere.
 ### Stand der Pruefung
 Neun neue Testfaelle in `tests/aktualisierung/test_aktualisierung.py` decken
 die Unterscheidung ab (nur frontend, nur manifest, geaenderte/neue/entfallene
 `.py`, services.yaml, `__pycache__`, unlesbarer Ordner) - 23 Tests der Suite
 gruen.
 **Der Durchlauf ueber den echten Gitea-Weg steht noch aus.** Er braucht eine
 angemeldete Sitzung, und die war nach einem Browser-Neustart weg; ich melde
 mich nicht selbst an. Vorbereitet ist er: Gitea steht auf **2026.9.5.24** mit
 einer reinen Kommentaraenderung in `audi-dashboard-app.js` plus Versionsnummer,
 die Testinstanz auf **2026.9.5.23**. Ein "Update installieren" dort muss
 "nur Oberflaechendateien, kein Neustart noetig" melden. Die Probeaenderung
 gehoert danach wieder heraus.