audi-app/VERSIONIERUNG.md

Versionierung — eine Zahl, drei Verbraucher

Kurzfassung für den Alltag: Wenn du etwas änderst, erhöhe version in custom_components/audi_dashboard/manifest.json. Alles Weitere ergibt sich daraus von selbst.

---

Warum es diese Zahl braucht

Das Panel und die iOS-App werden völlig unterschiedlich ausgeliefert:

• Panel: gehört zur Integration und wird mit ihr zusammen installiert. Es kann gar nicht hinterherhinken — ein Update der Integration ist automatisch ein Update des Panels.
• iOS-App: eine Capacitor-Hülle mit fest gebündelten Dateien. Sie bleibt auf dem Stand, der beim Signieren in Xcode eingebaut wurde — unbegrenzt.

Die Paritätsregel in AGENTS.md sichert, dass beide Codebasen in derselben Sitzung geändert werden. Über das, was läuft, sagte lange nichts etwas: die iOS-App konnte wochenlang zurückliegen, ohne dass es irgendwo sichtbar wurde.

Die Versionszahl schließt genau diese Lücke — nicht, indem sie die Abweichung verhindert (das kann keine Zahl), sondern indem sie sie sichtbar macht.

Wo sie steht

In custom_components/audi_dashboard/manifest.json, Feld version. Format 2026.8.23.2 (Datum + laufende Nummer).

Genau dort und nirgends sonst. Home Assistant verlangt das Feld für jede benutzerdefinierte Integration, HACS zeigt es an und entscheidet danach, ob ein Update bereitliegt — eine zweite Quelle für dieselbe Angabe wäre eine zu viel. Sie hätten irgendwann auseinandergelegen, und dann wäre der Vergleich still falsch geworden statt laut.

Bis 2026-08-23 gab es dafür eine eigene Datei VERSION in der Repo-Wurzel, daneben eine Unix-Sekundenzahl in www/audi-dashboard-version.json als Cache-Brecher. Beide sind mit dem Umbau zur Integration entfallen: die Version steht jetzt im Manifest, und die Oberflächen-Dateien tragen sie als ?v=… in ihrer URL — die Integration hängt sie beim Anmelden des Panels an. Ein Cache-Brecher, der sich nur bei echten Änderungen ändert, ist der bessere: er lädt nichts unnötig neu.

Wie sie durchs System läuft

manifest.json  { "version": "2026.8.23.2" }
   │
   ├─► Home Assistant führt sie als Version der Integration
   │      └─► HACS vergleicht sie gegen das Repository und meldet Updates
   │
   ├─► die Integration veröffentlicht sie als
   │      sensor.audi_dashboard_app_version
   │        └─► die iOS-App vergleicht sie mit ihrer eigenen, einkompilierten
   │            Zahl und zeigt bei Abweichung einen Hinweis in der
   │            Hinweisleiste
   │
   ├─► sie hängt als ?v=… an der Panel-URL
   │      └─► Browser laden Panel, CSS und Badges nur dann neu, wenn sich
   │          wirklich etwas geändert hat
   │
   └─► companion-app: vite liest das Manifest beim Bauen und setzt sie als
       __APP_VERSION__ ein (bricht ab, wenn das Feld fehlt)

Der Vergleich läuft in eine Richtung: die Integration sagt, welcher Stand installiert ist; die App sagt, welchen sie hat. Stimmen sie nicht überein, ist die App zu alt (oder, seltener, die Integration).

Bewusst nur auf Gleichheit, nie größer/kleiner: die Version ist eine Kennung, keine Zahl. Ein Sortierversuch wäre scheingenau und würde bei einem Formatwechsel still falsche Antworten geben. Fehlt eine der beiden Seiten, wird gar nicht verglichen und nichts gemeldet — ein älteres Backend oder ein Start ohne Netz darf keinen Fehlalarm auslösen.

Was du tun musst

Bei einer Änderung an der Oberfläche oder am Backend:

1. version in manifest.json erhöhen — bei mehreren Änderungen am selben Tag die laufende Nummer: 2026.8.23.2 → 2026.8.23.3, am nächsten Tag 2026.8.24.1.
2. Integration ausliefern: über HACS (wenn das Repository auf GitHub liegt) oder mit homeassistant\installationspaket\Installieren.cmd.
3. iOS-App neu bauen (npm run build), damit sie dieselbe Zahl einkompiliert bekommt.

Vergisst du Schritt 3, ist das kein stiller Fehler mehr: die App meldet selbst, dass sie älter ist als der Server.

Bei einer reinen Neuinstallation ohne Codeänderung: nichts tun.

Ausblick: OTA-Updates

Sobald @capgo/capacitor-updater eingebaut ist (geprüft: MPL-2.0, passt zu Capacitor 8, Selbst-Hosting ohne fremde Cloud möglich), holt sich die iOS-App den neuen Stand selbst — dann entfällt Schritt 3 für alles, was nur JavaScript/CSS betrifft. Xcode wird dann nur noch für echte native Änderungen gebraucht. Der Vergleich aus dieser Datei bleibt dabei unverändert nützlich: er ist genau das Signal, an dem die App erkennt, dass ein neues Bündel bereitliegt.