audi-app/ha_install.md

# DataMetric360 als native Home-Assistant-Integration

**Stand: 2026-08-13.** Vorhaben: Das HA-Backend von „pyscript-Skripte plus Dateien kopieren" auf
eine **eigene Integration mit Konfigurationsdialog** umstellen — Einrichtung vollständig über die
Oberfläche, kein YAML, Updates als Knopfdruck in HAs eigener Update-Liste.

Alle unten genannten Schnittstellen sind **an der laufenden Instanz geprüft** (Home Assistant
2026.8.1 im Container `audi_ha_test`), nicht aus der Dokumentation abgeschrieben. Die geprüften
Signaturen stehen jeweils dabei.

Verwandte Dokumente: `homeassistant/INSTALL.md` (heutiger, manueller Weg — bleibt gültig, bis diese
Umstellung steht), `UMSETZUNGSPLAN.md`, `REVIEW_main_2026-08-13.md` (die Fehler, die hier
konstruktionsbedingt verschwinden).

---

## 1. Was heute nötig ist — und was davon bleibt

| Heute | Nach der Umstellung |
|---|---|
| HACS installieren, darüber pyscript | entfällt |
| drei Ordner nach `/config/` kopieren (`pyscript/`, `data/`, `www/`) | einmalig **ein** Ordner nach `custom_components/` |
| zwei Blöcke in `configuration.yaml` einfügen | entfällt vollständig |
| Entity-IDs zuordnen | bleibt, aber als HA-Konfigurationsdialog statt als selbstgebautes Menü |
| langlebiges Token in `audi_dashboard/ha_token.txt` ablegen | **entfällt ersatzlos** |
| `pip install pypdf` von Hand | entfällt (`manifest.json` → `requirements`) |
| Neustart | einmalig, wie bei jeder Integration |
| Updates über `update.ps1` per Samba | Knopfdruck in *Einstellungen → System → Updates* |

## 2. Die Bausteine, die HA dafür mitbringt

Alle in 2026.8.1 vorhanden und geprüft:

| Baustein | Ersetzt |
|---|---|
| `EntitySelector` mit `domain`, `device_class`, `multiple`, `reorder`, `exclude_entities` | das gesamte Setup-Menü (`entitaeten.py` + ~800 Zeilen JS) |
| `panel_custom.async_register_panel(...)` | den `panel_custom`-Block in `configuration.yaml` |
| `hass.http.async_register_static_paths([StaticPathConfig(url_path, path, cache_headers)])` | Kopieren nach `/config/www/` samt Cache-Busting-Stub |
| `ConfigEntry.add_update_listener(...)` | den „wirkt erst nach Neustart"-Hinweis bei den drei triggergebundenen Feldern |
| `async_track_state_change_event` / `async_track_time_interval` / `async_track_time_change` | `@state_trigger` / `@time_trigger("period")` / `@time_trigger("cron")` |
| `recorder.history.get_significant_states(...)` | den HTTP-Aufruf auf `/api/history/period` **samt Token-Datei** |
| `hass.async_add_executor_job(...)` | `task.executor(io.open, ...)` |
| `Store` (`homeassistant.helpers.storage`) | handgeschriebenes JSON-I/O (optional, siehe §6) |
| `HomeAssistantView` / `websocket_api.async_register_command` | die 16-KB-Attributgrenze für Fahrten und Tankvorgänge |
| `UpdateEntity` (`INSTALL`, `PROGRESS`, `BACKUP`, `RELEASE_NOTES`) | `updateverwaltung.py` als sichtbare Update-Entität |

Der wichtigste Einzelfund: **`EntitySelector` kann `exclude_entities`.** Die Duplikat-Prüfung wäre
damit keine wegklickbare Warnung mehr, sondern schlicht nicht anwählbar.

## 3. Aufbau

```
custom_components/datametric360/
├── manifest.json      Abhängigkeiten, "config_flow": true, Version
├── const.py           Rollen-Tabelle (heute FELDER in entitaeten.py)
├── config_flow.py     Ersteinrichtung + Optionen (die 17 Sensor-Rollen)
├── __init__.py        Dienste, Horcher, Zeitgeber, Panel, statische Dateien
├── update.py          UpdateEntity gegen das eigene Gitea
├── api.py             HomeAssistantView für die Companion-App (später)
└── www/               audi-dashboard-app.js, .css, badges/ — mitgeliefert
```

### Konfigurationsdialog

Statt einer eigenen Katalogverwaltung reicht ein Schema. Skizze für zwei der 17 Rollen:

```python
vol.Schema({
    vol.Required("zuendung_sensor"): EntitySelector(
        EntitySelectorConfig(domain=["binary_sensor"])
    ),
    vol.Optional("tuer_sensoren", default=[]): EntitySelector(
        EntitySelectorConfig(domain=["binary_sensor"], device_class=["door"],
                             multiple=True, reorder=True)
    ),
})
```

Suche, Übersetzung, Gerätezuordnung und Mehrfachauswahl kommen von HA. Die vier Türpositionen
werden zu einer sortierbaren Mehrfachauswahl — die Reihenfolge ersetzt die heutigen festen
Positionsfelder.

### Panel und Dateien

```python
await hass.http.async_register_static_paths([
    StaticPathConfig("/datametric360", hass.config.path("custom_components/datametric360/www"),
                     cache_headers=False),
])
panel_custom.async_register_panel(
    hass, frontend_url_path="datametric360", webcomponent_name="audi-dashboard-panel",
    sidebar_title="Mein Audi", sidebar_icon="mdi:car-sports",
    module_url=f"/datametric360/audi-dashboard-app.js?v={VERSION}",
)
```

Die Versionsnummer in der URL macht den Lade-Stub `audi-dashboard-panel.js` und
`audi-dashboard-version.json` überflüssig — das Cache-Problem löst sich, weil die Integration ihre
eigene Version kennt.

**Das Frontend selbst bleibt unangetastet.** Alle 3.873 Zeilen `audi-dashboard-app.js` laufen
weiter; nur das Setup-Menü darin wird überflüssig.

## 4. Übersetzung der pyscript-Eigenheiten

Mechanisch, kein Neuentwurf. Die Fachlogik — Fahrterkennung, Tankerkennung, Beleg-Parser,
Reifenzähler, Prognose — geht nahezu unverändert mit.

| pyscript | Integration |
|---|---|
| `@service def audi_dashboard_x()` | `hass.services.async_register(DOMAIN, "x", handler, schema)` |
| `@state_trigger(f"{SENSOR}")` | `async_track_state_change_event(hass, [sensor], handler)` |
| `@time_trigger("period(now, 20 seconds)")` | `async_track_time_interval(hass, handler, timedelta(seconds=20))` |
| `@time_trigger("cron(0 4 * * *)")` | `async_track_time_change(hass, handler, hour=4, minute=0, second=0)` |
| `task.unique()` + `task.sleep()` | `asyncio.Task` merken und bei Bedarf `cancel()` |
| `task.executor(io.open, …)` | `hass.async_add_executor_job(...)` |
| `state.set("pyscript.x", …)` | eigene Entität oder `HomeAssistantView` (siehe §6) |
| `subprocess.run(shell_beleg_parser.py)` | `pypdf` direkt importieren, in einem Executor-Job |
| `urllib.request` auf `/api/history/period` | `recorder.history.get_significant_states(...)` |

Die letzte Zeile ist die wichtigste: Sie beseitigt **zwei** Befunde auf einmal — den blockierenden
Aufruf, den HA seit 2026.8 abbricht (siehe `REVIEW_main_2026-08-13.md`, und derselbe Fehler wurde
im Branch `umsetzung-datametric360` bereits behoben), **und** die Token-Datei im Klartext.

## 5. Installation und Updates

Hier liegt der eigentliche Knackpunkt, deshalb ausführlich.

### HACS scheidet aus

HACS spricht ausschließlich mit GitHub. Anfragen, auch GitLab, Gitea oder Codeberg zuzulassen, gibt
es seit Jahren; umgesetzt sind sie nicht. Das Repository liegt auf `gitea.nothaft.cloud` — HACS ist
damit kein Weg, außer man spiegelt nach GitHub.

### „App" ist der falsche Behälter

App-Repositories (früher Add-ons) akzeptieren **beliebige Git-URLs**, auch selbst gehostete; nötig
ist nur eine `repository.yaml` im Wurzelverzeichnis. Das ist die einzige Stelle, an der Gitea
nativ mitspielen würde.

Inhaltlich passt es trotzdem nicht: Apps sind **Docker-Container** neben Home Assistant. Eine
Integration muss *im* HA-Prozess laufen, um Entitäten anzulegen, Dienste zu registrieren und ein
Panel einzuhängen. Eine App kann das nicht.

*(Es gäbe den Trick, eine winzige App zu bauen, die nichts weiter tut, als die Integration nach
`custom_components/` zu schreiben — dann käme auch die Erstinstallation aus dem eigenen Gitea. Ein
Docker-Container für einen einmaligen Kopiervorgang ist das aus meiner Sicht nicht wert; der
Vollständigkeit halber notiert.)*

### Der native Weg: eigene UpdateEntity

`UpdateEntity` lässt die Integration ihre Updates selbst melden — sichtbar in **Einstellungen →
System → Updates**, derselben Liste wie HA-Kern und Apps. Geprüfte Möglichkeiten:

```
UpdateEntityFeature: INSTALL, SPECIFIC_VERSION, PROGRESS, BACKUP, RELEASE_NOTES
async_install(version: str | None, backup: bool, **kwargs) -> None
```

`BACKUP` gibt es genau für das, was `updateverwaltung.py` heute von Hand macht: vor dem Einspielen
den alten Code sichern.

**Die Logik ist bereits vorhanden.** `updateverwaltung.py` klont flach, vergleicht Versionen,
sichert nach `code_backups/` und ersetzt die Dateien. Das wandert nahezu unverändert in
`async_install()`. Neu sind nur zwei Eigenschaften:

```python
@property
def installed_version(self) -> str: return VERSION          # aus manifest.json
@property
def latest_version(self) -> str | None: return self._neueste  # aus Gitea
```

Für `latest_version` empfiehlt sich statt der heutigen Zeitstempel-Zahl aus
`audi-dashboard-version.json` ein **Git-Tag**. Gitea bietet eine GitHub-kompatible Schnittstelle:

```
GET https://gitea.nothaft.cloud/api/v1/repos/paul/audi-app/releases/latest
```

Ein einzelner HTTP-Aufruf, kein Klonen. In HA steht dann „1.4.0 → 1.5.0" statt einer nichtssagenden
Zahl, und die Release-Beschreibung lässt sich über `release_notes` direkt anzeigen.

### Was bleibt

**Die Erstinstallation bleibt ein einmaliges Kopieren** des Ordners nach `custom_components/`. Für
Integrationen aus Nicht-GitHub-Quellen gibt es keinen nativen Installationsweg. Jedes weitere
Update ist danach ein Knopfdruck.

## 6. Datenhaltung — bewusst zu entscheiden

Zwei Möglichkeiten, beide vertretbar:

- **`Store`** (`.storage/datametric360`): atomar, versioniert, mit Migrationspfad. Nachteil: für
  Menschen nicht mehr lesbar, und die heutige Sicherung über `backup.py` müsste neu gedacht werden.
- **JSON-Dateien behalten** unter `/config/audi_dashboard/`, gelesen über Executor-Jobs. Nachteil:
  kein Migrationspfad. Vorteil: Fahrten und Tankvorgänge bleiben von Hand einsehbar und mit den
  bestehenden Sicherungen kompatibel.

**Empfehlung:** Dateien behalten. Bei einem Fahrzeugprofil, einem Fahrtenbuch und einer
Tankhistorie ist Lesbarkeit mehr wert als Migrationskomfort — und die vorhandene Sicherungslogik
bleibt gültig.

Unabhängig davon: Fahrten und Tankvorgänge gehören **nicht** in Entitäts-Attribute (16-KB-Grenze,
siehe `frontend_veroeffentlichung.py`), sondern hinter einen `HomeAssistantView`. Das ist zugleich
die saubere Schnittstelle für die Companion-App, die heute Attribut-Blobs auslesen muss.

## 7. Was dabei konstruktionsbedingt verschwindet

Aus `REVIEW_main_2026-08-13.md`:

- **Befund 1** (Speichern mit leerem Katalog löscht alle Zuordnungen) — der Konfigurationsdialog
  validiert serverseitig, ein leeres Formular kommt gar nicht durch.
- **Befunde 2 und 5** (Zurücksetzen wirkungslos bzw. zu stark) — die `setattr`-Override-Ebene
  entfällt komplett; HA verwaltet Optionen selbst.
- **Befunde 3 und 4** (falsche Vorbelegung, beliebige Sensoren) — HAs Entity-Picker schlägt nichts
  vor, der Nutzer wählt; `exclude_entities` verhindert Doppelbelegung.
- **Befund 7** (kaputte `entitaeten.json` legt das Panel lahm) — die Datei existiert nicht mehr.
- Der Neustart-Zwang bei den drei triggergebundenen Feldern — `add_update_listener` lädt die
  Integration neu und registriert die Horcher dabei mit den neuen Entity-IDs.

Nicht gelöst werden dadurch: die Frontend-Befunde (Standort-Dauerfeuer, Barrierefreiheit,
`.navmarke`) — das Frontend bleibt ja unverändert.

## 8. Aufwand und Reihenfolge

Realistisch einige Tage, nicht Wochen — der Großteil ist Umschreiben von Dekoratoren.

1. **Zuerst die drei Setup-Fehler roh fixen** (etwa eine Stunde). Sonst läuft die Instanz bis zur
   Umstellung mit einem Datenverlust-Pfad.
2. **Gerüst aufsetzen:** `manifest.json`, `config_flow.py`, Panel- und Dateiregistrierung. Die
   pyscript-Skripte laufen dabei zunächst unverändert weiter.
3. **Logik Datei für Datei herüberziehen**, beginnend mit `fahrtabschluss_logik.py` — dort
   verschwinden Token und blockierender Aufruf zuerst.
4. **`update.py`** gegen das Gitea-Repository.
5. **`api.py`** für die Companion-App, sobald diese so weit ist.

### Was dabei zu beachten ist

- **Neuladen im laufenden Betrieb entfällt.** pyscript lädt bei jeder Dateiänderung neu; eine
  Integration braucht einen Neustart oder ein Neuladen. Beim Entwickeln spürbar, im Betrieb egal.
- **Die Companion-App liest heute `pyscript.audi_dashboard_*`.** Werden daraus eigene Entitäten
  oder ein eigener Endpunkt, ändert sich die Tabelle `ENTITAETEN` in
  `companion-app/src/api/types.ts` — eine Datei, überschaubar.
- **`shell_beleg_parser.py` wandert mit in die Integration.** Heute liegt er unter
  `/config/audi_dashboard/` und wird von keinem Update-Pfad ausgeliefert (siehe Review) — als Teil
  des Integrationsordners löst sich das mit.