paul/audi-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5e4ef2a327af98157ec9e148d3f2c3d66b2e85c7
audi-app/UMSETZUNGSPLAN.md
T
Paul Nothaft 5e4ef2a327 Plan und AGENTS.md auf den erreichten Stand bringen 
Elf von dreizehn Phasen sind erledigt oder vorbereitet. AGENTS.md haelt
zusaetzlich die drei Fehler fest, die erst der Betrieb gegen eine echte
Home-Assistant-Instanz zutage brachte - und den verworfenen selbstgebauten
QR-Erzeuger, damit niemand den Versuch wiederholt.
2026-08-11 11:28:34 +02:00

38 KiB
Raw Blame History

DataMetric360 — Umsetzungsplan

Stand: 2026-08-11. Dieser Plan führt von heute (fertiges HA-Panel, fertige Datenschicht, halbfertiger Design-Entwurf) bis zur fertigen DataMetric360-App inklusive aller offenen Punkte aus AGENTS.md. Er ist bewusst kleinteilig geschrieben, damit jede Phase auch von einem schwächeren KI-Modell oder in einer frischen Session ohne Vorwissen abgearbeitet werden kann.

Beschlossene Rahmenbedingungen (nicht neu diskutieren):

  • Alle Daten liegen in Home Assistant. Es gibt kein eigenes Backend — die App spricht direkt mit der HA-REST-/WebSocket-API und ruft die vorhandenen pyscript.audi_dashboard_*-Services auf.
  • Kein Electron. Fürs iPhone wird die Web-App mit Capacitor verpackt (nur Sideload, nie App Store). Optionaler Zwischenschritt: als PWA auf den Homescreen (Phase 10).
  • Die App ersetzt später das HA-Panel; bis dahin bleibt das Panel unangetastet in Betrieb.

Für das ausführende Modell: Arbeitsregeln

  1. Lies zuerst: AGENTS.md (Regeln + Stand), dann die Phase, die du bearbeitest — nichts anderes. Hole dir Detailwissen erst, wenn ein Schritt es verlangt (die Schritte nennen die Quelldatei).
  2. Eine Phase pro Session. Arbeite die Schritte in Reihenfolge ab. Jeder Schritt hat eine Prüfung („✅ Fertig wenn"). Erfülle sie, bevor du weitergehst. Wenn eine Prüfung fehlschlägt, behebe das, bevor du den nächsten Schritt beginnst.
  3. Nach jeder abgeschlossenen Phase: Haken in diesem Plan setzen, betroffene Checkboxen in AGENTS.md abhaken, „Last updated" in AGENTS.md aktualisieren (englisch!), committen mit deutscher Commit-Message.
  4. Harte Verbote:
    • Audi-Assets (Schriften, Ringe, Typenschilder) niemals nach design-system/ kopieren oder in irgendetwas einbauen, das veröffentlicht/hochgeladen wird. Quelle für die App: homeassistant/www/ und design/uploads/.
    • Keine Schriftgewichte ≥ 600, keine Schatten, keine Verläufe. Nur Gewichte 300/400.
    • homeassistant/ nicht umbauen (nur die explizit genannten Pflege-Schritte in Phase 2).
    • Keine zusätzlichen npm-Pakete einführen, die der Plan nicht nennt, ohne es zu begründen und in AGENTS.md zu dokumentieren.
    • Home Assistant niemals direkt ins Internet stellen. Nur die in Phase 12 beschriebenen Wege.
  5. Sprache: Code-Bezeichner, Kommentare, UI-Texte, Commits auf Deutsch (Ausnahme: AGENTS.md englisch; design-system/ behält englische Props).
  6. Zahlenformat immer de-DE (1.234,5). Übernimm die Helfer de()/eur() aus dem alten Panel (homeassistant/www/audi-dashboard-app.js), statt eigene zu erfinden.

Phasenübersicht und Abhängigkeiten

Phase Inhalt Hängt ab von Braucht Hardware/Extern?
1 Arbeitsumgebung herstellen und verifizieren — nein
2 Pflege HA-Panel (Doku-Drift, Härtung) — nein
3 Design-Entwurf vervollständigen — Claude Design (Besitzer)
4 Workspace + React-Gerüst in companion-app/ 1 nein
5 App-Shell: Theme, Router, responsives Layout 4 nein
6 Onboarding + Datenanbindung + Offline-UX 5 nein
7 Alle Screens umsetzen 3, 6 nein
8 Audi-Assets einbauen 7 nein
9 Tests (authentifiziert + Komponenten) 6 nein
10 PWA + Capacitor/iOS-Sideload 7 Mac mit Xcode, iPhone
11 HA-Einbettung, Ablösung + Archivierung des Panels 7–10 HA-Produktivinstanz
12 Externer Zugriff: Cloudflare Tunnel + Reverse Proxy teils unabhängig Domain/DNS, Besitzer
13 FMM003: MQTT, Zertifikate, Mapping, Fahrterkennung Hardware ja: FMM003 verbaut

Phasen 2, 3 und 12 (Teilschritte) sind unabhängig und können vorgezogen werden. Phase 13 ist die einzige, die zwingend auf Hardware wartet.

Phase 1 — Arbeitsumgebung herstellen und verifizieren ✅ ERLEDIGT (2026-08-11)

Ergebnis: design-system baut und besteht 21/21, companion-app typecheckt und besteht 7/7. Die verlorene Testinstanz wurde als reproduzierbares Skript neu aufgebaut — siehe testumgebung/ (Abweichung vom Plan, bewusst: das Original ging genau deshalb verloren, weil es nur als Anleitung existierte).

Ziel: Beide npm-Pakete bauen, beide Smoke-Tests laufen, die HA-Testinstanz ist erreichbar.

  1. Node-Version prüfen: node --version — muss ≥ 20 sein (companion-app nutzt --experimental-strip-types, ab Node 22 stabil; wenn < 20: mit nvm/Volta Node 22 installieren).
  2. cd design-system && npm install && npm run build ✅ Fertig wenn: design-system/dist/index.js und dist/styles.css existieren, Build ohne Fehler.
  3. npm run smoke (im selben Ordner) ✅ Fertig wenn: 21/21 Fälle „ok" melden.
  4. cd ../companion-app && npm install && npm run typecheck ✅ Fertig wenn: tsc --noEmit fehlerfrei durchläuft.
  5. HA-Testinstanz prüfen: curl -s -o /dev/null -w '%{http_code}' http://localhost:18123/api/ — erwartet: 401 (API da, Token fehlt — das ist richtig so). Wenn keine Antwort: Der Docker-Container heißt audi_ha_test (docker start audi_ha_test). Existiert er nicht, siehe homeassistant/README.md (Testbericht-Abschnitt) für den Aufbau; notfalls Phase-1-Schritt 6 überspringen und in Phase 9 nachholen.
  6. npm run smoke in companion-app/ ✅ Fertig wenn: 7/7 Prüfungen grün.

Abschluss Phase 1: nichts committen (nur node_modules/dist, beides gitignored).

Phase 2 — Pflege des bestehenden HA-Panels ✅ ERLEDIGT (2026-08-11)

Doku-Drift behoben, profil_lesen() gehärtet und an der Testinstanz belegt. Offen bleibt nur, was Betriebsdaten sind: Fahrzeugfotos und steuer.faellig.

Ziel: Doku stimmt wieder mit dem Code überein; ein Crash-Risiko ist beseitigt. Reine Pflege — keine Funktionsänderungen.

  1. Statistik-Behauptung korrigieren (3 Stellen, gleiche Falschaussage „zeigt Beispielzahlen"):
    • homeassistant/www/audi-dashboard-app.js Kopfkommentar Zeilen ~13–15
    • homeassistant/README.md Zeile ~99
    • homeassistant/INSTALL.md Zeile ~204 Neue Aussage sinngemäß: „Die Statistik-Seite berechnet echte Werte aus Fahrten und Tankvorgängen (Zeiträume, Verbrauch, Tag/Nacht, privat/Arbeitsweg)."
  2. INSTALL.md Schritt 4 (Zeilen ~106–109): falsche Variablennamen ersetzen. Falsch: DOORS_SENSOR, WINDOWS_SENSOR, LOCK_ENTITY, BATTERY_VOLTAGE_SENSOR. Richtig (siehe homeassistant/pyscript/modules/einstellungen.py): TUER_SENSOREN, FENSTER_SENSOREN, TUERSCHLOSS_SENSOREN (je 4er-Listen) und BATTERIE_SENSOR (einzeln).
  3. README.md: Erwähnung der „97-%-Volltankungsregel" (~Zeile 110) streichen (Regel wurde entfernt, siehe Kommentar pyscript/belegverarbeitung.py:18-20); in der Dateiübersicht die fehlenden Skripte ergänzen: tankerkennung.py, batterieverlauf.py, bilderverwaltung.py, backup.py, updateverwaltung.py.
  4. Obsoleten Kommentar entfernen: pyscript/belegverarbeitung.py:41 — den Zusatz „TODO: Datei ablegen" streichen (Datei existiert längst), Konstante selbst unverändert lassen.
  5. profil_lesen() härten (pyscript/modules/profil.py, ~Zeile 51–55): fehlende oder nicht parsebare fahrzeugprofil.json abfangen. Verhalten: Fehler ins Log (log.error ist in pyscript global verfügbar), Rückgabe None; Aufrufer prüfen. Vorher alle Aufrufer suchen (grep -rn "profil_lesen" homeassistant/pyscript/) und sicherstellen, dass jeder mit None umgehen kann — wo nicht, dort eine frühe Rückkehr einbauen. pyscript-Eigenheit beachten: Datei-I/O nur über task.executor(io.open, …)-Muster wie im Bestand, kein nacktes open(). ✅ Fertig wenn: python3 -c "import ast; ast.parse(open('homeassistant/pyscript/modules/profil.py').read())" fehlerfrei ist und jeder Aufrufer den None-Fall behandelt.
  6. Bewusst NICHT tun: Swipe-Delete-Fallback, Popup-Tastaturzugang, Leaflet-Selbsthosting (Audit-Reste) — Entscheidung laut Audit: kommt in DataMetric360, nicht ins alte Panel. RAM-only-Zustände (Fahrtstart, Tank-Tiefststand) ebenfalls nicht anfassen — wird mit dem FMM003-Umstieg hinfällig.
  7. Committen: „Doku an Codestand angleichen und profil_lesen gegen fehlende Datei härten". AGENTS.md: die erledigten Punkte in Block C abhaken.

Offen bleiben in Block C nur: Fahrzeugfotos hochladen + steuer.faellig setzen (macht der Besitzer in der App/UI, kein Code).

Phase 3 — Design-Entwurf vervollständigen ⏭️ ÜBERSPRUNGEN (2026-08-11)

Entscheidung des Besitzers: Die Screens wurden direkt aus den Views des alten Panels abgeleitet, statt auf den Claude-Design-Entwurf zu warten. Dieser Abschnitt bleibt stehen, falls der Entwurf später auf den Stand der Umsetzung gebracht werden soll.

Ziel: Der Entwurf zeigt das richtige Fahrzeug und alle Seiten, die das alte Panel hat. Diese Phase läuft im Claude-Design-Projekt (https://claude.ai/design/p/c28a8d4d-ec4e-4178-9e49-ab5b90c02097) — der Besitzer stößt sie an; ein Agent kann den Auftragstext vorbereiten und den Export danach einpflegen.

  1. Korrektur Modell: überall „Audi RS 4 Avant competition" statt „RS 6 Avant"; Typenschild rs4 (negative/positive) statt rs6.
  2. Fehlende Seiten ergänzen (16 Stück; Vorlage ist jeweils die View im alten Panel — Funktionsnamen aus homeassistant/www/audi-dashboard-app.js, Beschreibung in SPECIFICATION.md §3 „Views"):
    # Seite Vorlage (alte View)
    1 Fahrzeugstatus-Detail (12-Punkte Türen/Fenster/Schlösser) vSicherheit()
    2 Fahrzeugdaten/Technik/Ausstattung vIdent()
    3 Batterieverlauf (SVG-Kurve, SoC/SoH) vBatterieverlauf()
    4 Service (Termine, Terminanfrage, Servicebuch-Liste) vService()
    5 Werkstatt bearbeiten vWerkstatt()
    6 Servicebuch-Eintrag (ansehen/bearbeiten/neu) vSbuch(i)
    7 Versicherung & Steuer (Hub) vVers()
    8 Beitrag bearbeiten vBeitrag()
    9 Vertragsdetails vVertragsdetails()
    10 Schutzbrief (nur lesen) vSchutz()
    11 Notrufnummern bearbeiten vNotrufBearbeiten()
    12 Kfz-Steuer (Ansicht + Bearbeiten) vSteuer()/vSteuerBearbeiten()
    13 Reifen (Sätze, km-Zähler, Wechsel, Drehmoment) vReifen()
    14 Fahrt-Detail (Karte, Daten, Bearbeiten) vTrip(id)
    15 Tankvorgang-Detail (inkl. Beleg-Upload/-Ersetzen) vFill(id)
    16 Einstellungen in voller Tiefe (Fahrzeug-Setup, Fotos, SmartDeal, Pausenzeit, Export/Import, Backup, Version/Update) vEinst()
    Für jede Seite beide Layoutvarianten (schmal mit Tab-Leiste unten, breit ≥1000px mit
    Seitenleiste) — wie im Brief DESIGN_BRIEF_DATAMETRIC360.md gefordert.
  3. Export einpflegen: kompletten Ordner design/ durch den neuen Export ersetzen (design/README.md sagt selbst: „wird beim nächsten Export komplett ersetzt"), README-Abschnitt „Stand dieses Exports" aktualisieren. ✅ Fertig wenn: grep -ci "rs 6\|rs6" design/DM360.dc.html = 0 und alle 16 Seiten im Export auffindbar sind.
  4. Committen; AGENTS.md Block A Punkt 1 abhaken.

Wichtig: Phase 7 kann pro Screen schon vor Abschluss dieser Phase beginnen — die 8 vorhandenen Hauptscreens sind entworfen; die 16 Unterseiten folgen dann dem gleichen Muster.

Phase 4 — Workspace und React-Gerüst ✅ ERLEDIGT (2026-08-11)

Ziel: companion-app/ ist ein lauffähiges Vite+React+TS-Projekt, das @audi-dash/ui als echte Dependency nutzt. Die bestehende Datenschicht (src/api/) bleibt unverändert liegen.

  1. npm-Workspace-Root anlegen — neue Datei package.json im Repo-Root: 
    {
  "name": "audi-app",
  "private": true,
  "workspaces": ["design-system", "companion-app"]
}
    Dazu Repo-Root-.gitignore um node_modules/ ergänzen (falls nicht abgedeckt).
  2. Dependencies in companion-app/package.json ergänzen (bestehende Felder beibehalten!): dependencies: react ^18, react-dom ^18, @audi-dash/ui (Versionsangabe * — kommt über den Workspace); devDependencies zusätzlich: vite, @vitejs/plugin-react, @types/react, @types/react-dom. Scripts ergänzen: "dev": "vite", "build": "vite build", "preview": "vite preview".
  3. npm install im Repo-Root ausführen (verlinkt design-system in die companion-app). Danach einmal npm run build --workspace design-system (die App importiert aus dist/).
  4. Vite-Konfiguration companion-app/vite.config.ts: 
    import { defineConfig } from "vite"
import react from "@vitejs/plugin-react"
export default defineConfig({
  plugins: [react()],
  server: { port: 5173 },
  build: { outDir: "dist", target: "es2022" },
})
  5. tsconfig anpassen: Das bestehende companion-app/tsconfig.json ist auf die reine Datenschicht zugeschnitten (noEmit, sehr streng — so lassen). Ergänzen: "jsx": "react-jsx", "lib": ["ES2022", "DOM", "DOM.Iterable"] und "moduleResolution": "bundler", falls nicht gesetzt. Die strengen Flags (exactOptionalPropertyTypes usw.) NICHT abschwächen.
  6. Einstieg anlegen:
    • companion-app/index.html — Minimal-HTML mit <div id="wurzel"></div> und <script type="module" src="/src/main.tsx"></script>; <html lang="de">; <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">.
    • companion-app/src/main.tsx: 
      import { createRoot } from "react-dom/client"
import "@audi-dash/ui/styles.css"
import { App } from "./App"
createRoot(document.getElementById("wurzel")!).render(<App />)
    • companion-app/src/App.tsx — vorerst nur: 
      export function App() {
  return <div className="ads-root" data-theme="nacht" style={{ minHeight: "100vh" }}>DataMetric360</div>
}
    Pflicht: Das äußerste Element trägt immer className="ads-root" und data-theme — ohne diese Wurzelklasse greifen die Design-Tokens nicht (Regel aus design-system/.design-sync/conventions.md).
  7. ✅ Fertig wenn: npm run dev --workspace companion-app startet, http://localhost:5173 zeigt dunklen Hintergrund (#161b23) mit Text; npm run typecheck --workspace companion-app und npm run build --workspace companion-app laufen fehlerfrei.
  8. Committen: „companion-app: Vite+React-Gerüst und Workspace-Anbindung an @audi-dash/ui". AGENTS.md Block A Punkt 2 abhaken, Statustabelle aktualisieren.

Phase 5 — App-Shell: Theme, Navigation, responsives Layout ✅ ERLEDIGT (2026-08-11)

Ziel: Navigationsgerüst, das beide Layouts beherrscht (schmal: Tab-Leiste unten; breit ≥1000px: Seitenleiste), mit Tag/Nacht-Theme und Zurück-Navigation. Noch ohne echte Daten.

Vorbild für Verhalten: das alte Panel (audi-dashboard-app.js) — flacher Routenzustand, ZURUECK-Tabelle. Vorbild fürs Aussehen: design/DM360.dc.html (dort existiert der wide-Umschalter mit 240px-Seitenleiste bereits).

  1. Kein Router-Paket installieren. Eigener flacher Zustand wie im alten Panel: src/navigation.ts mit type Route = { name: RouteName; id?: string }, React-State im App-Root, geheZu(name, id?), plus ZURUECK-Tabelle (aus dem alten Panel übernehmen und um die neuen Routen ergänzen; 3-stufige Verschachtelung schutz → vertragsdetails → vers beachten).
  2. Theme: src/theme.ts — Zustand "nacht" | "tag", Persistenz in localStorage (Schlüssel dm360.theme), Initialwert: gespeicherter Wert, sonst prefers-color-scheme, Standard nacht. Gesetzt wird ausschließlich data-theme auf dem ads-root-Element. localStorage-Zugriffe in try/catch (Muster aus dem alten Panel, Private-Mode-Browser).
  3. Layout: src/Shell.tsx — CSS-Grid/Flex mit Breakpoint bei 1000px (window.matchMedia("(min-width: 1000px)") + Listener):
    • schmal: Inhalt + TabBar-Komponente (aus @audi-dash/ui) unten, env(safe-area-inset-*) als Padding (iPhone-Notch).
    • breit: 240px-Seitenleiste links (Navigationspunkte + Ringe-Platzhalter oben), Inhalt rechts; Listen-Detail nebeneinander wo der Entwurf es vorsieht. Die 5 Hauptbereiche: Übersicht, Mein Audi, Fahrten, Statistik, Tanken. Einstellungen über Zahnrad oben rechts (nicht in der Tab-Leiste) — wie im alten Panel und im Entwurf.
  4. Platzhalter-Screens: je Hauptbereich eine Datei unter src/screens/ (z. B. Uebersicht.tsx), die vorerst nur Titel per ads-eyebrow/Tile zeigt.
  5. ✅ Fertig wenn: Im Browser (a) bei < 1000px die Tab-Leiste unten erscheint und alle 5 Bereiche wechselbar sind, (b) bei ≥ 1000px stattdessen die Seitenleiste erscheint, (c) der Theme-Wechsel sichtbar Tag/Nacht umschaltet und einen Reload überlebt.
  6. Committen: „companion-app: App-Shell mit responsivem Layout, Navigation und Theme".

Phase 6 — Onboarding, Datenanbindung, Offline-UX ✅ ERLEDIGT (2026-08-11)

Ziel: Die App verbindet sich echt mit Home Assistant über die vorhandene Datenschicht.

Die Datenschicht ist fertig — nur benutzen, nicht neu bauen. Einstieg: companion-app/src/api/index.ts (DataMetricApi). Sie liefert: REST-Reads (profilLesen, fahrtenLesen, tankvorgaengeLesen, fahrzeugstatusLesen), Live-Updates (HassLive mit Reconnect), Schreibzugriffe über die Offline-Queue (profilSchreiben, belegHochladen, fahrtLoeschen, tankvorgangLoeschen, jetztAktualisieren) und Zugangsdaten-Verwaltung (umgebung.ts).

  1. Ersteinrichtungs-Screen (src/screens/Einrichtung.tsx) nach dem Entwurf in design/DM360.dc.html (dort der isSetup-Block): Felder Server-Adresse + Zugangs-Token, Knopf „Verbinden" ruft verbindungPruefen() aus der Datenschicht; Fehler unterscheiden nach ApiFehler.istAnmeldeproblem (Token falsch) vs. istNetzproblem (Adresse/Netz) und in verständlichem Deutsch anzeigen. QR-Knopf: vorerst ausblenden oder deaktiviert mit Hinweis (kommt mit Capacitor, Phase 10). Bei Erfolg Zugangsdaten über die Ablage der Datenschicht speichern und in die App wechseln.
  2. Datenkontext: src/datenkontext.tsx — ein React-Context, der beim Start DataMetricApi instanziiert, initial alle vier Reads lädt, sich bei aufZustand() für Live-Updates registriert und {profil, fahrten, tankvorgaenge, status, verbindung} bereitstellt. Übernahme-Pflicht aus dem alten Panel: die Umrechnungen profilZuConfig()/profilZuCar() (inkl. SmartDeal-Gültigkeit: aktiv wenn laeuft_ab fehlt oder ≥ heute, Ablaufdatum einschließlich) aus audi-dashboard-app.js nach TypeScript portieren — Logik exakt beibehalten.
  3. Offline-UX (Entwurf: Offline-Marker in der Kopfzeile):
    • Verbindungszustand aus aufVerbindung() der Datenschicht → dezenter „Offline"-Hinweis im Kopf, Daten bleiben sichtbar.
    • Warteschlange aus aufAenderung() → sichtbare Zahl wartender Änderungen („2 Änderungen warten auf Übertragung"), wie im Design-Brief gefordert.
  4. Stale-Anzeige: last_updated des Fahrzeugstatus mitführen (Muster: Staleness-Indikator des alten Panels).
  5. ✅ Fertig wenn: Gegen audi_ha_test (Token siehe Phase 9 Schritt 1): Einrichtung mit falschem Token zeigt Anmeldefehler, mit richtigem Token lädt die App Profil + Status; HA-Container stoppen → Offline-Marker erscheint; Container starten → verschwindet wieder (Reconnect testet die Backoff-Logik der Datenschicht).
  6. Committen; AGENTS.md Block A Punkte Onboarding/Offline teilweise abhaken (QR bleibt offen).

Phase 7 — Alle Screens umsetzen ✅ ERLEDIGT (2026-08-11)

Alle 21 Seiten stehen. Die Entwurfsvorlage kam für die 16 Unterseiten aus den Views des alten Panels statt aus Claude Design (Entscheidung des Besitzers, 2026-08-11) — Phase 3 ist damit gegenstandslos, solange der Entwurf nicht nachgezogen werden soll.

Ziel: Funktionsgleichheit mit dem alten Panel plus die neuen Live-Ansichten. Pro Screen: Entwurf aus design/ nachbauen (mit @audi-dash/ui-Komponenten), Logik aus der alten View portieren, an den Datenkontext anschließen.

Reihenfolge und Zuordnung (Logik-Vorlage = Funktion in audi-dashboard-app.js; Datenquelle = Feld im Datenkontext):

Screen Logik-Vorlage Datenquelle / Services Hinweise
Übersicht vHome() status, profil, fahrten, tankvorgaenge Foto, Status „sicher abgestellt", Reichweite, km, nächster Service, Teaser letzte Fahrt/Tankung; Pull-to-Refresh → jetztAktualisieren()
Fahrten-Liste vTrips() fahrten Jahr→Monat-Akkordeon (Accordion); Lösch-Aktion: nicht nur Swipe — zusätzlich „…"-Menü pro Zeile (behebt Audit-Finding barrierefreies Löschen); manuelles Anlegen (vTripsFormular()) über Service audi_dashboard_fahrt_manuell_anlegen
Fahrt-Detail vTrip(id) fahrten Karte: Leaflet lokal bündeln (npm i leaflet, Audit-Finding CDN), Tile-Layer nach Theme; kein fakeTrack() portieren — ohne echte Route nur Start/Ende-Marker zeigen, mit ehrlichem Leerhinweis
Tanken-Liste vFuel() tankvorgaenge volumengewichteter Durchschnittspreis; Lösch-„…"-Menü wie bei Fahrten
Tankvorgang-Detail vFill(id) tankvorgaenge Beleg-Upload: Datei → Base64 → belegHochladen(); Ergebnis kommt asynchron über die Entität pyscript.audi_dashboard_beleg_ergebnis (Muster im alten Panel: belegErgebnisVerarbeiten())
Statistik vStat() fahrten, tankvorgaenge Rechenfunktionen (fahrtenSeit, tankSeit, verbrauch, istNachtZeit) 1:1 portieren
Mein Audi (Hub) vAudi() profil Fotogalerie + Kachel-Links auf die Unterseiten
Fahrzeugstatus-Detail vSicherheit() status 16-Punkte-Liste; ok === null heißt „unbekannt", nie grün raten
Fahrzeugdaten vIdent() profil (technik, ausstattung) statisch aus dem Profil
Batterieverlauf vBatterieverlauf() eigener Read der Entität pyscript.audi_dashboard_batterieverlauf SVG-Chart portieren (Pinch/Pan/Tap); Leerzustand prominent — Sensor ist derzeit unbesetzt
Service + Werkstatt + Servicebuch vService(), vWerkstatt(), vSbuch() profil.service Öl-/Service-Prognose (oelwechselPrognose(), intervalle(), termine()) exakt portieren; ICS-Export (ics()-Helfer) übernehmen
Versicherung/Steuer-Gruppe vVers(), vBeitrag(), vVertragsdetails(), vSchutz(), vNotrufBearbeiten(), vSteuer() profil.versicherung, profil.steuer reine Formular-/Anzeige-Seiten; Schreiben immer als ganzes Profil über profilSchreiben() (es gibt keinen Feld-einzeln-Service!)
Reifen vReifen() profil.reifen + Entitäten pyscript.reifen_* Wechsel über Service audi_dashboard_reifen_wechseln (nur "sommer"/"winter"); Wechseldatum → ICS
Einstellungen vEinst() profil, alle volle Tiefe: Fahrzeug-Setup, Theme, Fotos (Upload über audi_dashboard_bild_hochladen, nur die 10 erlaubten Dateinamen!), SmartDeal, Pausenzeit, Profil-Export/Import, Backup, CSV-Export, Version
Neu: Live-Fahrt — (neu) status (künftig FMM003-Felder) Entwurf screen === 'live': Karte, Geschwindigkeit groß, Strecke/Dauer; bis Phase 13 hinter einem Feature-Schalter LIVE_VERFUEGBAR = false in einer zentralen Konfigurationsdatei — Screen bauen, Schalter erst mit echten Daten umlegen
Leerzustände — — für Fahrten/Tanken/Statistik je einen freundlichen „noch keine Daten"-Zustand (Design-Brief), wird real gebraucht: beide JSONL sind aktuell leer

Regeln für alle Screens:

  • Nur @audi-dash/ui-Komponenten + Tokens (var(--…)), keine neuen Hex-Farben, keine neuen Komponenten ohne sie zuerst in design-system/ anzulegen (dann dort mit CSS+Preview, danach hier verwenden).
  • Destruktive Aktionen immer mit Bestätigung; Fehler sichtbar in rot inline (Muster altes Panel).
  • Jede Zahl durch de()/eur().
  • Nach jedem Screen: npm run typecheck + Sichtprüfung schmal UND breit.

✅ Fertig wenn: jeder Screen der Tabelle existiert, mit Testdaten befüllbar ist und in beiden Layouts bedienbar aussieht wie der Entwurf. Committen pro Screen-Gruppe (z. B. „Fahrten-Screens"), nicht ein Riesencommit.

Phase 8 — Audi-Assets einbauen ✅ ERLEDIGT (2026-08-11)

Ziel: Die App sieht aus wie das Original — Schriften, Ringe, Typenschilder.

  1. Quellen: Schriften aus design/uploads/*.ttf (oder die woff2-Base64-Blöcke aus homeassistant/www/audi-dashboard.css), Ringe design/assets/audi-rings-{white,black}.svg, Typenschilder aus homeassistant/www/badges/ (alle 14).
  2. Ablage: companion-app/src/assets/audi/ + @font-face-Deklarationen in einer eigenen src/audi-schrift.css (Familien exakt wie im Bestand: "Audi Type" 400, "Audi Type Wide" 300/400, "Audi Type Extended" italic). Der --font-stack wird per CSS-Variable auf dem ads-root überschrieben — design-system/-Dateien bleiben unberührt.
  3. Typenschild-Auswahl nach Modell aus dem Profil (Logik aus vEinst()/Badge-Mapping des alten Panels übernehmen; Theme-abhängig positive/negative-Variante).
  4. Kontrolle: git log --stat des Commits zeigt KEINE Änderung unter design-system/; Gewichte ≥ 600 kommen nirgends vor (grep -rn "font-weight" companion-app/src | grep -vE "300|400" liefert nichts).
  5. Committen; AGENTS.md Block A Assets-Punkt abhaken. Hinweis im Commit: Repo bleibt privat (Lizenz).

Phase 9 — Tests ✅ ERLEDIGT (2026-08-11)

90 Unit- und Rendertests, dazu 9 Prüfungen gegen die laufende Instanz.

Ziel: Die ungeteste Hälfte der Datenschicht ist abgedeckt; die Kern-Rechenlogik hat Unit-Tests.

  1. Token für die Testinstanz erzeugen: audi_ha_test im Browser öffnen (http://localhost:18123), anmelden, Profil → Sicherheit → langlebiges Zugriffstoken erstellen. Token NUR in companion-app/.env.local ablegen (VITE_TEST_TOKEN=…), Datei in .gitignore aufnehmen. Niemals committen.
  2. Authentifizierter Smoke (scripts/smoke-auth.ts, Aufbau wie scripts/smoke.ts): mit Token (a) zustandLesen("pyscript.audi_dashboard_profil") liefert Daten, (b) dienstAufrufen mit einem harmlosen Service (audi_dashboard_jetzt_aktualisieren) gibt 200, (c) Queue-Round-Trip: Eintrag einstellen bei gestopptem Container, Container starten, Queue leert sich. Script in package.json als smoke:auth; ohne gesetztes Token bricht es mit klarer Meldung ab (Exit-Code 0, „übersprungen").
  3. Unit-Tests mit vitest (einzige neue Dev-Dependency): portierte Rechenlogik testen — Statistik (verbrauch, istNachtZeit, Zeiträume), Service-Prognose (oelwechselPrognose: Neustart nach Ölwechsel, 180-Tage-Gewichtung, Kappung), SmartDeal-Gültigkeit (Ablauftag einschließlich!), de()/eur()-Formatierung. Testdaten als Fixtures aus realistischen JSONL-Zeilen (Schema: SPECIFICATION.md §5).
  4. ✅ Fertig wenn: npm run smoke:auth 3/3 grün (mit Token), npx vitest run grün, und beide in companion-app/README.md dokumentiert sind.
  5. Committen; AGENTS.md Block A Test-Punkt abhaken.

Phase 10 — PWA und Capacitor 🟡 STUFE 1 ERLEDIGT (2026-08-11)

PWA fertig. Capacitor-Konfiguration, Secure-Storage-Adapter und die QR-Seite liegen bereit; die Hülle selbst braucht einen Mac mit Xcode und ein Gerät.

Ziel: Die App läuft auf dem iPhone. Zwei Stufen — erst PWA (sofort nutzbar), dann Capacitor (Keychain + QR-Scan).

Stufe 1 — PWA (kein neues Werkzeug):

  1. companion-app/public/manifest.webmanifest (Name „DataMetric360", display: "standalone", Themenfarbe #161b23, neutrale Icons 192/512px — NICHT die Audi-Ringe als App-Icon, der Homescreen ist „außen"; neutrales DM360-Monogramm erzeugen) + Verweis im index.html.
  2. Erreichbarkeit fürs Handy: solange Phase 12 nicht fertig ist, über Tailscale (npm run build, Ausgabe z. B. über HA /local/ oder vite preview --host im LAN testen).
  3. ✅ Fertig wenn: „Zum Home-Bildschirm" auf dem iPhone die App randlos startet und Login + Datenanzeige funktionieren.

Stufe 2 — Capacitor: 4. npm i -D @capacitor/cli && npm i @capacitor/core @capacitor/ios @capacitor/android (im Workspace für companion-app), npx cap init DataMetric360 app.datametric360 --web-dir dist, npx cap add ios, npx cap add android. 5. Sichere Token-Ablage: Capacitor-Secure-Storage-Plugin (z. B. @aparajita/capacitor-secure-storage) als neue Ablage-Implementierung; über den vorhandenen Hook ablageSetzen() der Datenschicht einhängen, wenn umgebungErkennen() „capacitor" meldet. Browser-Fall bleibt unverändert BrowserAblage. 6. QR-Scan: Barcode-Plugin (@capacitor-mlkit/barcode-scanning) + Kamera-Berechtigung; Gegenstück: kleine statische Seite unter HA /local/dm360-qr.html, die den Token clientseitig (Offline-JS-QR-Bibliothek, keine Netzabfrage) als QR anzeigt. Inhalt des QR: JSON {"url": "...", "token": "..."}. Wenn das zusammen > 1 Tag Aufwand wird: weglassen — manuelles Einfügen ist die beschlossene, ausreichende Lösung. 7. iOS-Sideload: npx cap open ios, in Xcode Signing mit eigener Apple-ID, aufs Gerät bauen. ⚠️ Entscheidungspunkt für den Besitzer: mit kostenlosem Apple-Konto läuft die Signatur nach 7 Tagen ab (App neu aufspielen); ein bezahltes Entwicklerkonto (99 €/Jahr) macht 1 Jahr. Bei 7-Tage-Schmerz ist die PWA-Stufe die Alltagslösung, Capacitor das Extra für Keychain/QR. 8. ✅ Fertig wenn: App startet nativ auf dem iPhone, Token liegt im Keychain (Test: App löschen und neu installieren → Token weg; Backup/Restore-Verhalten notieren), QR-Einrichtung funktioniert oder ist dokumentiert entfallen. 9. Committen; AGENTS.md Block A Punkte QR/Secure-Storage abhaken.

Phase 11 — HA-Einbettung und Ablösung des alten Panels

Ziel: Die neue App läuft im HA-Seitenmenü; das alte Panel ist archiviert.

  1. Build in HA ausliefern: npm run build, Ausgabe nach /config/www/dm360/ der Produktivinstanz (Weg analog update.ps1; das Script um diesen Ordner erweitern).
  2. configuration.yaml: panel_iframe-Eintrag (Titel „Mein Audi", mdi:car-sports, URL /local/dm360/index.html). Der panel_custom-Block des alten Panels bleibt zunächst parallel bestehen (zweiter Menüpunkt „Mein Audi (alt)").
  3. Parallelbetrieb mindestens 2 Wochen: beide Panels zeigen dieselben Daten (gleiche Entitäten/Services — Abweichungen sind Portierungsfehler; prüfen: Übersichtszahlen, eine Fahrt anlegen/löschen, ein Beleg-Upload).
  4. Ablösung: alten panel_custom-Block entfernen; Dateien NICHT löschen, sondern verschieben: homeassistant/www/audi-dashboard-app.js → homeassistant/archiv/ (plus Panel-Stub und CSS), README-Hinweis dort ablegen. Beschlossene Regel: archivieren, nie löschen (COMPANION_APP_ARCHITECTURE.md §1).
  5. ✅ Fertig wenn: Neues Panel im HA-Menü, altes entfernt aber archiviert, SPECIFICATION.md bekommt eine Kopfnotiz „beschreibt das archivierte Panel; aktuell ist companion-app/".
  6. Committen; AGENTS.md Block D abhaken, Statustabelle umstellen.

Phase 12 — Externer Zugriff: Cloudflare Tunnel + Reverse Proxy 🟡 VORBEREITET

Fertige Freigabeliste samt Prüfbefehlen: homeassistant/REVERSE_PROXY.md. Ausführung braucht Cloudflare-Konto und die Nameserver-Umstellung.

Ziel: Die App funktioniert von unterwegs (Mobilfunk), ohne dass HA selbst erreichbar ist. Referenz: COMPANION_APP_ARCHITECTURE.md §4/§5. Teilweise Besitzer-Aufgaben (Konten/DNS).

  1. [Besitzer] Nameserver umstellen: datametric360.app bei all-inkl auf die Cloudflare-Nameserver zeigen lassen (Cloudflare-Konto → Site hinzufügen → „Full setup"; Domain trägt sonst nichts, Umstellung ist folgenlos). ✅ wenn dig NS datametric360.app die Cloudflare-Server liefert.
  2. Hostnamen festlegen (Empfehlung aus dem Architekturdokument übernehmen): App unter https://datametric360.app, API unter https://api.datametric360.app — getrennter API-Hostname hält die Allowlist übersichtlich. Entscheidung in AGENTS.md protokollieren.
  3. Cloudflared-Add-on in HA installieren, Tunnel erstellen, zwei öffentliche Hostnamen: datametric360.app → Reverse-Proxy-Port (statische App-Dateien + nichts weiter), api.datametric360.app → Reverse-Proxy-Port (API-Pfade). Kein Router-Port wird geöffnet.
  4. Reverse Proxy: Nginx Proxy Manager-Add-on (Standard-Empfehlung; Traefik nur, falls NPM an Grenzen stößt — Entscheidung dokumentieren). Allowlist ausschließlich:
    • GET /api/states/pyscript.audi_dashboard_* und GET /api/states/pyscript.reifen_*
    • POST /api/services/pyscript/audi_dashboard_*
    • GET /api/ (Verbindungsprüfung) und der WebSocket-Pfad /api/websocket Alles andere (v. a. /auth, /lovelace, /config, /api/config) wird geblockt. ⚠️ Ehrliche Einschränkung dokumentieren: /api/websocket lässt sich nicht pfadgenau beschneiden — nach auth_ok sind darüber alle States lesbar. Schutzschicht bleibt der LLAT (ohne Token keine Verbindung); das ist die im Architekturdokument akzeptierte Abwägung.
  5. Prüfen von außen (Mobilfunk, VPN aus): App lädt, Login klappt, curl auf einen Nicht-Allowlist-Pfad (z. B. /auth/authorize) liefert 403/404; HA-Port 8123 ist von außen nicht erreichbar.
  6. ✅ Fertig wenn: Schritt 5 vollständig besteht. Die endgültige Allowlist wortwörtlich in COMPANION_APP_ARCHITECTURE.md §5.1 eintragen (dort als offener Punkt vorgemerkt) und in AGENTS.md Block B abhaken.

Schritte 2–4 können gegen die bestehende HA-API vor der FMM003-Hardware erledigt werden.

Phase 13 — FMM003-Inbetriebnahme 🟡 VORBEREITET (wartet auf Hardware)

Gerüst der Zuordnungstabelle und alle Schritte: homeassistant/FMM003_MAPPING.md.

Ziel: Live-Daten vom Fahrzeug fließen nach HA; Fahrterkennung läuft über die Zündung. Referenz: COMPANION_APP_ARCHITECTURE.md §2b. Nichts hiervon vorab raten oder simulieren.

  1. Mosquitto-Add-on in HA installieren, Benutzer für das Gerät anlegen.
  2. Zertifikate: kleine eigene CA (drei openssl-Befehle: CA-Schlüssel+Zertifikat, Server-Zertifikat für den Broker, Client-Zertifikat fürs Gerät); Broker auf 8883/TLS; CA-/Client-Dateien im Teltonika Configurator unter Security hinterlegen. Ohne Zertifikate verweigert der FMM003 MQTT.
  3. [Besitzer] Broker-Erreichbarkeit entscheiden: Portfreigabe 8883 (einfach; TLS+Login davor) oder VPS-Broker mit Mosquitto-Bridge über Tailscale (keine Freigabe, mehr Aufwand). Entscheidung + Begründung in COMPANION_APP_ARCHITECTURE.md §5.2a und AGENTS.md nachtragen.
  4. Gerät konfigurieren: Firmware-Version notieren (Codec JSON ist firmwareabhängig!); System → Data Protocol → Codec JSON; GPRS → MQTT mit Broker-IP/Port/Login.
  5. Erste echte Nachricht mitschneiden: mosquitto_sub -h <broker> -p 8883 --cafile ca.crt -u <nutzer> -P <pw> -t '#' -v > mitschnitt.txt — mit Zündung an/aus, kurzer Fahrt. Aus dem Mitschnitt die Feldzuordnungstabelle bauen (JSON-Feld → Bedeutung → Einheit) und als homeassistant/FMM003_MAPPING.md einchecken (ohne echte Positionsdaten im Beispiel!).
  6. HA-MQTT-Integration: aus der Tabelle mqtt:-Sensoren/device_tracker in der HA-Konfiguration definieren (Zündung, Geschwindigkeit, Drehzahl, Tankfüllstand, Position, km).
  7. Fahrterkennung umstellen: neues pyscript fahrterkennung_fmm003.py nach dem Muster von fahrterkennung.py — Trigger ist die Zündungs-Entität (1→0 mit Pausentoleranz via task.unique()/task.sleep(), Ende-Zeitpunkt auf den echten Zündung-aus-Moment rückdatieren; fahrten_pausenzeit_min aus dem Profil weiterverwenden). Erst parallel laufen lassen (schreibt in eine Test-Datei), vergleichen, dann scharf schalten und sensor.iphone_wifi_connection aus einstellungen.py entfernen.
  8. Live-Screen aktivieren: Feature-Schalter aus Phase 7 umlegen, Live-Felder anbinden; GPS-Route der laufenden Fahrt aufzeichnen und im Fahrt-Detail echte Tracks statt der Start/Ende-Marker zeigen (damit stirbt der letzte Rest von fakeTrack() endgültig).
  9. ✅ Fertig wenn: eine echte Fahrt automatisch erkannt, mit km und Route gespeichert und in der App (Liste, Detail mit echter Route, Statistik) korrekt angezeigt wird; VAG-Integration und WLAN-Trigger sind entfernt; AGENTS.md Block B komplett abgehakt.

Anhang A — Nachschlagereferenz für das ausführende Modell

Entitäten (lesen): pyscript.audi_dashboard_profil, …_fahrten, …_tankvorgaenge, …_fahrzeugstatus, …_batterieverlauf, …_beleg_ergebnis, …_update_status, pyscript.reifen_sommer_km, …_winter_km, …_aktiver_satz. Nutzdaten stets im Attribut daten.

Services (schreiben, Domain pyscript): audi_dashboard_profil_schreiben, …_beleg_hochladen, …_tankvorgang_manuell, …_tankvorgang_aktualisieren, …_tankvorgang_loeschen, …_fahrt_manuell_anlegen, …_fahrt_loeschen, …_bild_hochladen, …_bild_loeschen, …_reifen_wechseln, …_backup_jetzt, …_backup_wiederherstellen, …_jetzt_aktualisieren, …_screening_jetzt, …_update_pruefen, …_update_installieren. Signaturen: SPECIFICATION.md §5. Service-Aufrufe geben keine Werte zurück — Ergebnisse kommen asynchron über Entitäten (Muster: Beleg-Upload).

Stolperfallen:

  • Profil wird immer als Ganzes geschrieben — nie Teil-Updates erfinden.
  • edited_fields eines Datensatzes schützt Felder vor automatischen Überschreibungen — beim Portieren von Bearbeiten-Formularen beibehalten.
  • Sensorwerte "unknown"/"unavailable" = None behandeln, nie raten (Muster zustand_oder_none()).
  • pyscript: kein nacktes open()/with — task.executor-Muster aus modules/profil.py.
  • HA-Attribute haben ~16 KB-Grenze (frontend_veroeffentlichung.py) — keine großen Blobs in Entitäten stopfen.
  • fahrten.jsonl/tankvorgaenge.jsonl sind aktuell leer — Leerzustände sind der erste Eindruck der App, nicht ein Randfall.

Anhang B — Definition of Done (gesamt)

Die App gilt als fertig, wenn: alle Screens aus Phase 7 in beiden Layouts funktionieren; Onboarding, Offline-Queue und Beleg-Upload gegen die Produktiv-HA laufen; die App als PWA und (falls Capacitor umgesetzt) nativ auf dem iPhone installiert ist; der externe Zugriff über datametric360.app funktioniert, ohne dass HA exponiert ist; das alte Panel archiviert ist; und AGENTS.md den Endstand widerspiegelt (alle Blöcke A–D abgehakt oder begründet gestrichen).

Reference in New Issue View Git Blame Copy Permalink