# companion-app — DataMetric360

Private Fahrzeug-App für einen Audi RS 4 Avant competition. Läuft als Web-App
im Browser, als PWA auf dem Homescreen, später über Capacitor nativ auf
iOS/Android und eingebettet als Iframe im Home-Assistant-Dashboard.

**Kein eigenes Backend.** Die App spricht direkt mit der REST- und
WebSocket-Schnittstelle von Home Assistant und ruft dieselben
`pyscript.audi_dashboard_*`-Dienste auf wie das bestehende Panel. Alle Daten
liegen auf dem eigenen Server; das Gerät hält nur den Zugangstoken und einen
Zwischenspeicher für die Offline-Anzeige.

Architektur: `../COMPANION_APP_ARCHITECTURE.md` · Umsetzungsschritte:
`../UMSETZUNGSPLAN.md` · Projektstand: `../AGENTS.md`

## Loslegen

```bash
npm install          # im Repo-Wurzelverzeichnis, nicht hier (npm-Workspace)
npm run build:ds     # Design-System bauen, die App importiert aus dessen dist/
npm run dev --workspace datametric360
```

Beim ersten Start fragt die App nach Server-Adresse und Zugangstoken. Für die
Entwicklung setzt `../testumgebung/aufsetzen.sh` eine vollständige
Home-Assistant-Instanz mit dem echten Backend auf.

## Aufbau

| Ordner | Inhalt |
|---|---|
| `src/api/` | Datenschicht: REST, WebSocket mit Wiederverbindung, Offline-Warteschlange, Zugangsdaten |
| `src/daten/` | Fachlogik: Profil-Umrechnung, Statistik, Service-Prognose, Datenkontext |
| `src/screens/` | Die 21 Seiten der App |
| `src/stile/` | Layout, Bildschirmbausteine, Audi-Schrift |
| `src/assets/audi/` | Schrift, Vier-Ringe, Typenschilder — **lizenzpflichtig, siehe unten** |
| `src/tests/` | Testaufbau und Beispieldaten |

Gestaltung kommt vollständig aus `@audi-dash/ui` (`../design-system/`). Neue
Komponenten entstehen dort, nicht hier.

## Prüfen

```bash
npm run typecheck    # TypeScript, sehr streng (exactOptionalPropertyTypes u. a.)
npm run test         # 90 Tests: Rechenlogik, Layoutwechsel, alle Seiten gerendert
npm run smoke        # Adressbildung und Endpunkte, ohne Token
npm run smoke:auth   # gegen die laufende Testinstanz, mit Token
npm run build        # Produktionsbündel
```

`smoke:auth` liest Adresse und Token aus `.env.local` (schreibt
`../testumgebung/aufsetzen.sh`, gitignored). Ohne die Datei überspringt der
Test sich selbst, statt fehlzuschlagen.

Die Rendertests decken alle 21 Seiten in beiden Layouts ab — schmal mit
Tab-Leiste, breit mit Seitenleiste.

## Rechtlicher Hinweis

`src/assets/audi/` enthält die Hausschrift Audi Type, das Vier-Ringe-Zeichen
und die Modell-Typenschilder. Diese sind lizenz- beziehungsweise
markenrechtlich geschützt und ausschließlich für diese eine private,
unveröffentlichte Installation freigegeben (`../bauauftrag.md` §8/§12).

Daraus folgt: **Die App wird nur seitlich installiert, nie in einem App Store
veröffentlicht**, und dieses Repository bleibt privat. `../design-system/`
kommt bewusst ohne diese Dateien aus, weil es nach außen hochgeladen wird —
dort niemals Markendateien ablegen.

## Die signierte App

`auslieferung/App.ipa` ist der fertige, **Ad-hoc signierte** Stand (Team
`RMACS9VLS4`, Profil gültig bis 29.08.2027, nur für das eingetragene iPhone).
Neu bauen: `bash scripts/ios-signieren.sh` - baut Webbündel, synchronisiert die
Hülle, signiert und legt die `.ipa` wieder hier ab.

Beim ersten Signieren fragt der Schlüsselbund um Erlaubnis. Dort **„Immer
erlauben"** wählen, sonst hängt `xcodebuild` wortlos und endet nach Minuten mit
`errSecInternalComponent`.

## Noch offen

- Native Hülle selbst: `ios/`/`android/` (von `npx cap add` erzeugt, absichtlich
  gitignored) existieren in keinem Checkout dauerhaft und müssen auf einem Mac
  (für iOS zwingend, Xcode) neu erzeugt werden - die sichere Tokenablage
  (Keychain/Keystore) ist dagegen bereits vollständig angebunden
  (`src/api/ablageNativ.ts`, von `main.tsx` aktiviert) und wird automatisch
  aktiv, sobald die Hülle existiert
- Übertragung über die Luft: `scripts/ios-luftweg.sh https://<host>` erzeugt
  Manifest und Installationsseite; es fehlt nur noch ein Host, der den Ordner
  über **HTTPS mit gültigem Zertifikat** ausliefert (`tailscale serve`
  angedacht, dieser Mac ist dort noch abgemeldet)
- QR-Einrichtung als Alternative zum Einfügen des Tokens
- Live-Ansicht der laufenden Fahrt: gebaut, aber über
  `src/funktionen.ts` abgeschaltet, bis der FMM003 echte Werte liefert