# Versionierung — warum es zwei Zahlen gibt

Kurzfassung für den Alltag: **Wenn du etwas an der Oberfläche änderst, erhöhe
`VERSION`.** Alles Weitere erledigen die Bau- und Installationsskripte.

---

## Die zwei Zahlen tun verschiedene Dinge

Sie sahen sich lange zum Verwechseln ähnlich, deshalb hier ausdrücklich
getrennt:

| | `VERSION` (Repo-Wurzel) | `version` in `audi-dashboard-version.json` |
|---|---|---|
| Zweck | **Identität**: welcher Stand ist das? | **Cache-Bruch**: hol die Dateien neu |
| Format | `2026.08.23.1` (Datum + laufende Nummer) | Unix-Sekunden, z. B. `1787016000` |
| Wer setzt sie | **du, von Hand**, wenn sich etwas ändert | `install.ps1` / `update.ps1` bei jedem Deploy |
| Vergleichbar zwischen Panel und iOS-App | **ja, darum geht es** | nein, jede Installation hat eine andere |

Die Unix-Zahl taugt bewusst **nicht** als Versionsvergleich: sie wird bei jeder
Installation neu gesetzt, ohne dass sich am Code etwas geändert hätte. Sie sagt
dem Browser nur „lade neu", nicht „das ist Stand X".

## Warum das überhaupt nötig wurde

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

- **Panel:** holt bei jedem Seitenaufruf `audi-dashboard-version.json` mit
  `cache: "no-store"` und lädt seine Dateien neu, sobald die Zahl sich geändert
  hat. Es ist damit nach einem Deploy sofort aktuell, ohne Zutun.
- **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 bisher nichts etwas: die
iOS-App konnte wochenlang hinterherhinken, ohne dass es irgendwo sichtbar wurde.

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

## Wie die Zahl durchs System läuft

```
VERSION  (2026.08.23.1)
   │
   ├─► homeassistant/www/audi-dashboard-version.json   { "app": "2026.08.23.1" }
   │        │
   │        └─► Backend liest die Datei und veröffentlicht sie als
   │            pyscript.audi_dashboard_app_version
   │                 │
   │                 └─► die iOS-App vergleicht sie mit ihrer eigenen,
   │                     einkompilierten Zahl und zeigt bei Abweichung
   │                     einen Hinweis in der Hinweisleiste
   │
   └─► companion-app: von vite beim Bauen als __APP_VERSION__ eingesetzt
```

Der Vergleich läuft also immer in eine Richtung: **das Backend sagt, welcher
Stand ausgeliefert wurde; die App sagt, welchen sie hat.** Stimmen sie nicht
überein, ist die App zu alt (oder, seltener, das Backend).

## Was du tun musst

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

1. `VERSION` erhöhen — bei mehreren Änderungen am selben Tag die laufende
   Nummer: `2026.08.23.1` → `2026.08.23.2`, am nächsten Tag `2026.08.24.1`.
2. Panel deployen wie bisher (`update.ps1`). Das Skript trägt die neue `VERSION`
   in `audi-dashboard-version.json` ein und setzt die Cache-Zahl frisch.
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. `VERSION`
bleibt, wie sie ist; nur die Cache-Zahl wird neu gesetzt.

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