Station name as "brand, street, city", grey box on all editable fields

The "grey box around the icons" report turned out not to be a defect: the box
on "10.000 km"/"1 Jahr"/"15" is the wanted pattern, and every value the user
can change should carry it. All .feld inputs and selects now get the grey iOS
fill; inputs with their own visual language (checkbox/radio/range/file) keep
the transparent base rule, so the switches are unaffected.

Fuel stations are now displayed as "Shell, Pascalstr. 8, Ingolstadt" instead of
the bare operator name. New _marke()/_ist_strasse()/_tankstelle() helpers are
shared by both parser paths so Shell and non-Shell receipts format the same.
The brand is only matched against the receipt header - searching the whole text
would let "Total" hit a totals line. Missing parts are dropped instead of
leaving empty comma slots, and without a known brand the operator name takes
its place. station_address still carries the full street and postcode.
test_bekannte_stationen updated to the new format; suite stays green.

installationspaket/ is versioned from now on (user request). It contains no
real vehicle data - only the example profile with empty FIN/plate placeholders.
Keep it in sync whenever pyscript/ or www/ changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

homeassistant/installationspaket/pyscript/modules/einstellungen.py

@@ -0,0 +1,93 @@
+"""Technische Konfiguration — die einzige Stelle, die vor der Installation
+angepasst werden muss (siehe INSTALL.md Schritt 4).
+
+Alles andere (WLAN-Name des Fahrzeugs, Pausenzeit, Reifendaten, ...) ist Teil
+des Fahrzeugprofils (data/fahrzeugprofil.json) und über die Oberfläche
+änderbar. Diese Entity-IDs sind es bewusst nicht: @state_trigger und die
+Fahrzeugstatus-Abfrage brauchen sie als festen Wert, bevor überhaupt ein
+Profil gelesen werden kann.
+
+In Home Assistant unter Entwicklerwerkzeuge -> Zustände nachschlagen. Werte
+lassen sich außerdem über das Setup-Menü in der Oberfläche zuordnen (siehe
+entitaeten.py) - Änderungen von dort werden zur Laufzeit auf diese Variablen
+angewendet (überschreiben also die hier hinterlegten Standardwerte), ohne
+diese Datei anzufassen.
+
+2026-08-12: Die HACS-Integration TommiG1/HA_VAG-EU-Data-Act (bisherige
+Quelle für Kilometerstand, Tankfüllstand, Türen/Fenster/Schlösser,
+Ölwechsel-/Inspektionsdaten) wird nicht mehr verwendet - die zugehörigen
+Entity-IDs sind deshalb unten bewusst leer. Neue Datenquelle ist der
+Teltonika FMM003 (GPS-Tracker mit CAN-Anbindung, siehe AGENTS.md Abschnitt
+B); er liefert Standort, Zündungsstatus und Batteriespannung, aber keinen
+Tankfüllstand, keine Tür-/Fenster-/Schlossdaten und keine Ölwechsel-/
+Inspektionstermine - die entsprechenden Kacheln zeigen deshalb bis auf
+Weiteres "unbekannt" statt eines falschen Werts (siehe zustand_oder_none()
+in frontend_veroeffentlichung.py). Bleibt ein Wert leer ("") oder passt eine
+Entity-ID nicht zur tatsächlichen Integration, liefert zustand_oder_none()
+für das jeweilige Feld None statt abzustürzen.
+"""
+
+# Fahrterkennung (§7.1): Start/Ende einer Fahrt wird über den Zündungs-/ACC-
+# Status des FMM003 erkannt (on = Fahrt läuft), nicht mehr über die WLAN-
+# Verbindung des iPhones zum Fahrzeug (siehe fahrterkennung.py).
+ZUENDUNG_SENSOR = "binary_sensor.testzone_fmm003_engine_ignition_or_acc_status"
+
+# Kilometerstand - bisher aus der TommiG1-Integration, aktuell keine Quelle
+# vorhanden. Der FMM003 liefert unter sensor.testzone_fmm003_total_calculated_mileage
+# einen selbst berechneten Wert, der aber auf einer anderen Zählbasis beruht
+# als der echte Fahrzeug-Kilometerstand (GPS-Streckenberechnung statt
+# Tacho) - bewusst NICHT automatisch übernommen, um Reifenzähler,
+# Ölwechsel-Prognose und Fahrtabschluss-Screening nicht mit einem
+# inkonsistenten Basiswert zu verfälschen. Bei Bedarf über das Setup-Menü
+# gezielt zuordnen.
+KM_SENSOR = ""
+
+# Tankfüllstand (Prozent) - keine Quelle mehr vorhanden (der FMM003 ist kein
+# Tankgeber).
+TANK_SENSOR = ""
+
+# Reichweite (§5.1 Übersicht) - keine Quelle mehr vorhanden.
+RANGE_SENSOR = ""
+
+# 12V-Batteriespannung (Mein Audi -> Zustand). Vom FMM003 geliefert -
+# external_power_voltage ist die vom Gerät gemessene Bordnetzspannung des
+# Fahrzeugs, NICHT battery_voltage (das ist die interne Pufferbatterie des
+# Trackers selbst und hat mit der Fahrzeugbatterie nichts zu tun).
+BATTERIE_SENSOR = "sensor.testzone_fmm003_external_power_voltage"
+
+# Knopf für eine sofortige Neuabfrage beim Fahrzeug - kam aus der
+# TommiG1-Integration, keine Entsprechung beim FMM003 vorhanden.
+REFRESH_BUTTON = ""
+
+# Türen (§4.1) - keine Quelle mehr vorhanden.
+TUER_SENSOREN = []
+
+# Fenster (§4.1) - keine Quelle mehr vorhanden.
+FENSTER_SENSOREN = []
+
+# Heckklappe und Motorhaube - keine Quelle mehr vorhanden.
+HECKKLAPPE_SENSOR = ""
+HECKKLAPPENSCHLOSS_SENSOR = ""
+HAUBE_SENSOR = ""
+
+# Vom Fahrzeug selbst gemeldete Service-Fälligkeit (ergänzt die App-eigene,
+# aus dem Servicebuch berechnete Prognose) - keine Quelle mehr vorhanden.
+NAECHSTER_OELWECHSEL_SENSOR = ""
+OELWECHSEL_STRECKE_SENSOR = ""
+NAECHSTE_INSPEKTION_SENSOR = ""
+INSPEKTION_STRECKE_SENSOR = ""
+
+# Live-GPS-Position des Fahrzeugs (Übersicht -> Standort-Kachel). Breiten-/
+# Längengrad als zwei eigene sensor-Entities (flespi liefert Koordinaten so,
+# nicht als Attribute einer device_tracker-Entity - siehe _standort() in
+# frontend_veroeffentlichung.py).
+STANDORT_LAT_SENSOR = ""
+STANDORT_LON_SENSOR = ""
+
+# Update-Funktion (Einstellungen -> "Update suchen", siehe
+# updateverwaltung.py): Git-Repository, in das dieses Projekt gepflegt wird -
+# z. B. ein privates GitHub-Repo, genau wie für die HACS-Integration bereits
+# verwendet. Leer lassen, solange es keins gibt - "Update suchen" meldet dann
+# nur "keine Update-Quelle eingerichtet", ohne etwas zu tun.
+UPDATE_REPO_URL = ""
+UPDATE_BRANCH = "main"

homeassistant/installationspaket/pyscript/modules/entitaeten.py

@@ -0,0 +1,245 @@
+"""Sensor-zu-Entität-Zuordnung fürs Setup-Menü (Einstellungen -> Fahrzeug
+einrichten -> Setup).
+
+Ersetzt NICHT das manuelle Eintragen in einstellungen.py (dessen Kommentare
+sind die eigentliche Dokumentation der Integration und bleiben unangetastet),
+sondern legt eine zusätzliche, zur Laufzeit angewendete Override-Ebene
+darüber: data/entitaeten.json enthält nur die vom Nutzer über das Setup-Menü
+geänderten Zuordnungen, keyed nach den einstellungen.py-Variablennamen.
+
+Warum das funktioniert, ohne jede Verbraucher-Datei anzufassen: Alle
+bestehenden Leser (frontend_veroeffentlichung.py, fahrterkennung.py, ...)
+machen `import einstellungen` und lesen dann `einstellungen.KM_SENSOR` -
+ein lebendiger Attributzugriff auf das Modul-Objekt, kein `from einstellungen
+import KM_SENSOR` (das würde den Wert beim Import einfrieren). overrides_
+anwenden() unten nutzt genau das: setattr(einstellungen, key, wert) ändert
+das Attribut auf dem bereits importierten Modul-Objekt, jeder spätere
+Zugriff `einstellungen.KM_SENSOR` liefert sofort den neuen Wert.
+
+Eine Ausnahme (siehe TRIGGER_GEBUNDEN unten): mehrere @state_trigger(f"...")-
+Dekoratoren backen ZUENDUNG_SENSOR/KM_SENSOR/TANK_SENSOR einmalig beim
+Modul-Laden in die Trigger-Registrierung ein. Eine Änderung dieser drei
+Felder wirkt für die Fahrterkennung selbst erst nach einem Neustart von
+Home Assistant (bzw. pyscript.reload) - das Setup-Menü weist deshalb bei
+diesen drei Feldern ausdrücklich darauf hin, statt automatisch und riskant
+einen Selbst-Reload aus einer laufenden pyscript-Funktion heraus zu
+versuchen.
+"""
+
+import io
+import json
+import os
+
+import einstellungen
+
+BASIS = "/config/audi_dashboard"
+OVERRIDES_PFAD = f"{BASIS}/entitaeten.json"
+
+# Vier gleich aufgebaute Positionen, wie schon in frontend_veroeffentlichung.py
+# (dort POSITIONEN genannt) - hier dupliziert statt importiert, damit
+# entitaeten.py nicht von frontend_veroeffentlichung.py abhängt (wäre die
+# falsche Richtung: die Veröffentlichung importiert diese Datei, nicht
+# umgekehrt).
+POSITIONEN = ["vorne links", "vorne rechts", "hinten links", "hinten rechts"]
+
+# Katalog aller von der App genutzten Entity-Rollen, fürs Setup-Menü im
+# Frontend. Reihenfolge = Anzeige-Reihenfolge innerhalb jeder Gruppe.
+# domains/device_classes/units sind Erwartungen fürs Frontend-seitige
+# Filtern+Vorschlagen (Schalter "Nur passende Sensoren anzeigen") - eine
+# fehlende oder leere Liste bedeutet "keine Einschränkung" bzw. "diese Rolle
+# hat üblicherweise keine Einheit" (binary_sensor/button/device_tracker).
+FELDER = [
+    {"key": "ZUENDUNG_SENSOR", "label": "Zündung/ACC-Status", "gruppe": "fahrterkennung",
+     "hinweis": "on = Fahrt läuft, erkennt Fahrtbeginn/-ende (ersetzt die frühere WLAN-Erkennung).",
+     "domains": ["binary_sensor"], "device_classes": [], "units": [], "liste": False, "pflicht": True,
+     "stichworte": ["zündung", "ignition", "acc", "motor", "engine"]},
+    {"key": "KM_SENSOR", "label": "Kilometerstand", "gruppe": "fahrterkennung",
+     "hinweis": "Gesamt-Kilometerstand des Fahrzeugs - für Fahrtabschluss-Screening, Reifenzähler und Ölwechsel-Prognose.",
+     "domains": ["sensor"], "device_classes": ["distance"], "units": ["km", "mi"], "liste": False, "pflicht": False,
+     "stichworte": ["kilometer", "km", "mileage", "odometer", "tacho", "laufleistung"]},
+    {"key": "TANK_SENSOR", "label": "Tankfüllstand", "gruppe": "fahrterkennung",
+     "hinweis": "Füllstand in Prozent - für die automatische Tankerkennung.",
+     "domains": ["sensor"], "device_classes": [], "units": ["%"], "liste": False, "pflicht": False,
+     "stichworte": ["tank", "fuel", "kraftstoff", "füllstand", "level"]},
+    {"key": "RANGE_SENSOR", "label": "Reichweite", "gruppe": "uebersicht",
+     "hinweis": "Für die Übersicht - bleibt leer, zeigt die Oberfläche \"unbekannt\".",
+     "domains": ["sensor"], "device_classes": ["distance"], "units": ["km", "mi"], "liste": False, "pflicht": False,
+     "stichworte": ["reichweite", "range"]},
+    {"key": "BATTERIE_SENSOR", "label": "12V-Batteriespannung", "gruppe": "uebersicht",
+     "hinweis": "Nicht jede Integration liefert diesen Wert - bleibt er leer, zeigt \"Mein Audi\" \"unbekannt\".",
+     "domains": ["sensor"], "device_classes": ["voltage"], "units": ["V"], "liste": False, "pflicht": False,
+     "stichworte": ["batterie", "battery", "spannung", "volt", "12v"]},
+    {"key": "REFRESH_BUTTON", "label": "Sofort-Aktualisierung (Knopf)", "gruppe": "uebersicht",
+     "hinweis": "Der von der Integration bereitgestellte Knopf für \"Ziehen zum Aktualisieren\".",
+     "domains": ["button"], "device_classes": [], "units": [], "liste": False, "pflicht": False,
+     "stichworte": ["refresh", "aktualisieren", "update", "abrufen", "poll"]},
+    {"key": "TUER_SENSOREN", "label": "Türen", "gruppe": "sicherheit",
+     "hinweis": "\"aus\"/off = zu. Für \"Sicher abgestellt\" wichtig.",
+     "domains": ["binary_sensor"], "device_classes": ["door"], "units": [], "liste": True, "positionen": POSITIONEN,
+     "pflicht": False, "stichworte": ["tür", "door"]},
+    {"key": "FENSTER_SENSOREN", "label": "Fenster", "gruppe": "sicherheit",
+     "hinweis": "\"aus\"/off = zu.",
+     "domains": ["binary_sensor"], "device_classes": ["window"], "units": [], "liste": True, "positionen": POSITIONEN,
+     "pflicht": False, "stichworte": ["fenster", "window"]},
+    {"key": "HECKKLAPPE_SENSOR", "label": "Heckklappe", "gruppe": "sicherheit",
+     "hinweis": "\"aus\"/off = zu.",
+     "domains": ["binary_sensor"], "device_classes": ["door", "opening"], "units": [], "liste": False, "pflicht": False,
+     "stichworte": ["heckklappe", "tailgate", "kofferraum", "trunk"]},
+    {"key": "HECKKLAPPENSCHLOSS_SENSOR", "label": "Heckklappenschloss", "gruppe": "sicherheit",
+     "hinweis": "\"on\" = entriegelt, \"aus\"/off = verriegelt.",
+     "domains": ["binary_sensor"], "device_classes": ["lock"], "units": [], "liste": False, "pflicht": False,
+     "stichworte": ["heckklappe", "tailgate", "schloss", "lock"]},
+    {"key": "HAUBE_SENSOR", "label": "Motorhaube", "gruppe": "sicherheit",
+     "hinweis": "\"aus\"/off = zu.",
+     "domains": ["binary_sensor"], "device_classes": ["door", "opening"], "units": [], "liste": False, "pflicht": False,
+     "stichworte": ["haube", "hood", "bonnet", "motorhaube"]},
+    {"key": "NAECHSTER_OELWECHSEL_SENSOR", "label": "Nächster Ölwechsel (Datum)", "gruppe": "uebersicht",
+     "hinweis": "Vom Fahrzeug selbst gemeldete Fälligkeit, ergänzt die App-eigene Servicebuch-Prognose.",
+     "domains": ["sensor"], "device_classes": ["date", "timestamp"], "units": [], "liste": False, "pflicht": False,
+     "stichworte": ["ölwechsel", "oil", "service", "change"]},
+    {"key": "OELWECHSEL_STRECKE_SENSOR", "label": "Nächster Ölwechsel (Restkilometer)", "gruppe": "uebersicht",
+     "hinweis": "Meldet die Integration oft als negativen Countdown - die App zeigt nur den Betrag.",
+     "domains": ["sensor"], "device_classes": ["distance"], "units": ["km", "mi"], "liste": False, "pflicht": False,
+     "stichworte": ["ölwechsel", "oil", "distance", "strecke"]},
+    {"key": "NAECHSTE_INSPEKTION_SENSOR", "label": "Nächste Inspektion (Datum)", "gruppe": "uebersicht",
+     "hinweis": "Vom Fahrzeug selbst gemeldete Fälligkeit.",
+     "domains": ["sensor"], "device_classes": ["date", "timestamp"], "units": [], "liste": False, "pflicht": False,
+     "stichworte": ["inspektion", "inspection", "service"]},
+    {"key": "INSPEKTION_STRECKE_SENSOR", "label": "Nächste Inspektion (Restkilometer)", "gruppe": "uebersicht",
+     "hinweis": "Meldet die Integration oft als negativen Countdown - die App zeigt nur den Betrag.",
+     "domains": ["sensor"], "device_classes": ["distance"], "units": ["km", "mi"], "liste": False, "pflicht": False,
+     "stichworte": ["inspektion", "inspection", "distance", "strecke"]},
+    {"key": "STANDORT_LAT_SENSOR", "label": "GPS-Standort: Breitengrad", "gruppe": "standort",
+     "hinweis": "Breitengrad als eigener Sensor (z. B. flespi).",
+     "domains": ["sensor"], "device_classes": [], "units": [], "liste": False, "pflicht": False,
+     "stichworte": ["breitengrad", "latitude", "lat", "standort", "gps", "position", "ortung"]},
+    {"key": "STANDORT_LON_SENSOR", "label": "GPS-Standort: Längengrad", "gruppe": "standort",
+     "hinweis": "Längengrad als eigener Sensor (z. B. flespi).",
+     "domains": ["sensor"], "device_classes": [], "units": [], "liste": False, "pflicht": False,
+     "stichworte": ["längengrad", "longitude", "lon", "lng", "standort", "gps", "position", "ortung"]},
+]
+
+# Mehrere @state_trigger(f"...")-Dekoratoren (fahrterkennung.py,
+# fahrtabschluss.py, tankerkennung.py, reifenzaehler.py) backen diese drei
+# Felder beim Modul-Laden ein (siehe Kopfkommentar) - im Setup-Menü als
+# "wirkt erst nach Neustart"-Hinweis markiert.
+_TRIGGER_GEBUNDEN = {"ZUENDUNG_SENSOR", "KM_SENSOR", "TANK_SENSOR"}
+for _feld in FELDER:
+    _feld["trigger_gebunden"] = _feld["key"] in _TRIGGER_GEBUNDEN
+
+_SCHLUESSEL = {feld["key"] for feld in FELDER}
+
+# Schnappschuss der eingebauten Standardwerte aus einstellungen.py, genommen
+# BEVOR overrides_anwenden() jemals lief (Modul-Ebene, läuft beim `import
+# entitaeten` in frontend_api.py - vor dem @time_trigger("startup"), der
+# overrides_anwenden() erstmals aufruft). Notwendig fürs Setup-Menü
+# "Zurücksetzen": setattr() in overrides_anwenden() überschreibt das Attribut
+# auf dem laufenden einstellungen-Modul dauerhaft, ein einfaches Weglassen
+# des Overrides beim nächsten Speichern stellt den eingebauten Wert NICHT
+# wieder her (das Attribut bleibt ja gesetzt) - "Zurücksetzen" muss den
+# Standardwert stattdessen aktiv zurückschreiben.
+_STANDARDWERTE = {feld["key"]: getattr(einstellungen, feld["key"], None) for feld in FELDER}
+
+
+# --------------------------------------------------------------- JSON-I/O ---
+# Gleiches Muster wie profil.profil_lesen()/profil_schreiben(): io.open nur
+# über task.executor (pyscript-Einschränkung, siehe Kopfkommentar dort),
+# atomares Schreiben über eine .tmp-Datei + os.replace.
+
+def overrides_lesen():
+    """Liest die gespeicherten Zuordnungen, oder {} wenn die Datei fehlt bzw.
+    beschädigt ist.
+
+    Der try/except ist nicht Vorsicht um ihrer selbst willen: overrides_
+    anwenden() läuft in beim_start() VOR alles_veroeffentlichen(). Ohne die
+    Absicherung reißt eine einzige unlesbare Zeile in dieser Datei den
+    gesamten Startvorgang mit - das Panel bliebe komplett leer, ohne dass
+    irgendetwas auf die Ursache hindeutet."""
+    if not os.path.exists(OVERRIDES_PFAD):
+        return {}
+    f = task.executor(io.open, OVERRIDES_PFAD, "r")
+    inhalt = f.read()
+    f.close()
+    if not inhalt.strip():
+        return {}
+    try:
+        gelesen = json.loads(inhalt)
+    except ValueError as fehler:
+        log.error(
+            f"audi_dashboard: {OVERRIDES_PFAD} ist kein gültiges JSON ({fehler}). "
+            "Die eingebauten Standardwerte gelten weiter; die Zuordnung lässt sich "
+            "im Setup-Menü neu speichern."
+        )
+        return {}
+    if not isinstance(gelesen, dict):
+        log.error(f"audi_dashboard: {OVERRIDES_PFAD} enthält kein Objekt - wird ignoriert.")
+        return {}
+    return gelesen
+
+
+def overrides_schreiben(mapping):
+    """Schreibt nur bekannte Schlüssel (siehe FELDER); unbekannte werden
+    stillschweigend verworfen, damit ein späterer Katalog-Umbau keine
+    Datenleichen in entitaeten.json hinterlässt."""
+    bereinigt = {k: v for k, v in mapping.items() if k in _SCHLUESSEL}
+    os.makedirs(BASIS, exist_ok=True)
+    tmp = OVERRIDES_PFAD + ".tmp"
+    text = json.dumps(bereinigt, ensure_ascii=False, indent=2)
+    f = task.executor(io.open, tmp, "w")
+    f.write(text)
+    f.close()
+    os.replace(tmp, OVERRIDES_PFAD)
+
+
+# ------------------------------------------------------- Anwenden/Lesen ---
+
+def _ist_leer(wert):
+    """Leer heißt: keine Zuordnung. Auch eine Liste, die nur leere Einträge
+    enthält - das Setup-Menü schickt für unbelegte Positionen ["","",...],
+    und das ist inhaltlich dasselbe wie gar keine Liste.
+
+    Die Schleife steht hier bewusst statt eines any(...)-Generatorausdrucks:
+    pyscript kennt Generatorausdrücke nicht und wirft zur Laufzeit
+    "not implemented ast ast_generatorexp". Mengen-, Listen- und
+    Dict-Comprehensions funktionieren dagegen (siehe _SCHLUESSEL oben)."""
+    if wert in (None, ""):
+        return True
+    if isinstance(wert, list):
+        for eintrag in wert:
+            if eintrag:
+                return False
+        return True
+    return False
+
+
+def overrides_anwenden():
+    """Setzt für JEDES bekannte Feld den wirksamen Wert auf dem laufenden
+    einstellungen-Modul - den Override, wenn einer hinterlegt ist, sonst den
+    eingebauten Standardwert.
+
+    Wichtig ist das "jedes": Eine frühere Fassung übersprang leere Werte und
+    setzte nur die belegten. Weil setattr() das Modul-Attribut aber dauerhaft
+    verändert, blieb ein einmal gesetzter Wert danach für immer stehen -
+    "Zurücksetzen" im Setup-Menü hatte bei allen Feldern mit leerem
+    Standardwert (15 von 17) schlicht keine Wirkung, und die Oberfläche zeigte
+    beim nächsten Zeichnen wieder den alten Wert, als sei das Speichern
+    fehlgeschlagen. Umgekehrt wurde eine Liste aus leeren Einträgen gesetzt
+    statt übersprungen, was den Sicherheitscheck mit zwölf "unbekannt"-Zeilen
+    füllte und "Sicher abgestellt" dauerhaft grau werden ließ.
+
+    Jedes Feld bei jedem Durchlauf zu schreiben ist damit nicht nur korrekt,
+    sondern auch idempotent: der Zustand hängt allein an entitaeten.json,
+    nicht an der Reihenfolge vorheriger Aufrufe."""
+    overrides = overrides_lesen()
+    for key in _SCHLUESSEL:
+        wert = overrides.get(key)
+        setattr(einstellungen, key, _STANDARDWERTE[key] if _ist_leer(wert) else wert)
+
+
+def aktueller_stand():
+    """Katalog + aktuell wirksamer Wert je Feld (aus dem einstellungen-Modul
+    selbst gelesen, nicht direkt aus der JSON-Datei) - zeigt damit sowohl
+    bereits angewendete Overrides als auch die eingebauten Standardwerte
+    einheitlich. Grundlage für pyscript.audi_dashboard_entitaeten."""
+    werte = {feld["key"]: getattr(einstellungen, feld["key"], None) for feld in FELDER}
+    return {"katalog": FELDER, "werte": werte, "standardwerte": _STANDARDWERTE}

homeassistant/installationspaket/pyscript/modules/fahrtabschluss_logik.py

@@ -0,0 +1,196 @@
+"""Screening-Logik für den zweistufigen Fahrtabschluss (Bauauftrag §7.2).
+
+Importierbar aus anderen pyscript-Dateien mit `import fahrtabschluss_logik`.
+
+Der Kilometerstand kommt laut Datenquelle nicht sicher mit Fahrtende, sondern
+teils erst mit Beginn oder während der nächsten Fahrt (§10 Punkt 4). Statt auf
+einen festen Zeitpunkt zu warten, wird deshalb die Recorder-Historie des
+Kilometerstand-Sensors nach dem Wert durchsucht, dessen Zeitstempel am
+nächsten am Verbindungsabbruch liegt.
+
+Zugriff auf die Historie läuft über die HA-REST-API (/api/history/period),
+nicht über einen internen pyscript-Mechanismus - dafür gibt es in der
+pyscript-Referenz keinen dokumentierten Weg. Das erfordert ein Long-Lived
+Access Token, siehe README.
+
+WICHTIGER VORBEHALT: Der GPS-Fallback aus §7.2 (km_quelle="gps") ist hier noch
+NICHT umgesetzt, da die Erfassung von Start-/Endposition (device_tracker,
+Adressauflösung) ein eigenes Arbeitspaket ist. Fahrten ohne passenden
+Kilometerstand bleiben aktuell dauerhaft "offen" statt auf GPS-Distanz
+auszuweichen. Siehe die Restarbeiten im Abschlussbericht.
+"""
+
+import datetime
+import io
+import json
+import urllib.parse
+import urllib.request
+
+import frontend_veroeffentlichung
+import profil
+
+BASIS = "/config/audi_dashboard"
+TOKEN_PFAD = f"{BASIS}/ha_token.txt"
+HA_BASIS_URL = "http://localhost:8123"
+
+# Wie weit vor/zurück in der Historie gesucht wird, ausgehend vom
+# Verbindungsabbruch. 48h deckt auch länger stehende Fahrzeuge ab, ohne bei
+# jedem Screening die komplette Historie zu laden.
+SUCHFENSTER_STUNDEN = 48
+
+
+# ---------------------------------------------------------- HA-REST-Zugriff
+
+def _token_lesen():
+    # io.open über task.executor statt bloßem open() - siehe Kopfkommentar
+    # in profil.py.
+    f = task.executor(io.open, TOKEN_PFAD, "r")
+    inhalt = f.read()
+    f.close()
+    return inhalt.strip()
+
+
+def historie_abfragen(entity_id, start_iso, end_iso):
+    """Fragt die Verlaufsdaten des Kilometerstand-Sensors über die REST-API ab.
+
+    Beide blockierenden Schritte laufen über task.executor. Ein früherer Stand
+    rief urlopen() direkt auf - das lief jahrelang durch, bis Home Assistant
+    anfing, blockierende Aufrufe im Ereignisschleifen-Thread zu erkennen und
+    abzubrechen (real beobachtet ab 2026.8: "Caught blocking call to
+    putrequest ... inside the event loop"). Seitdem schlug jedes Screening
+    fehl, und manuell angelegte Fahrten blieben ohne Strecke - sichtbar nur
+    als Warnung im Protokoll, weil der Aufrufer den Fehler bewusst abfängt.
+
+    task.executor braucht echte externe Funktionen; urllib.request.urlopen und
+    die read-Methode der Antwort sind genau das (dieselbe Einschränkung wie bei
+    io.open in profil.py)."""
+    token = _token_lesen()
+    start_enc = urllib.parse.quote(start_iso)
+    end_enc = urllib.parse.quote(end_iso)
+    url = (
+        f"{HA_BASIS_URL}/api/history/period/{start_enc}"
+        f"?filter_entity_id={entity_id}&end_time={end_enc}"
+    )
+    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
+    resp = task.executor(urllib.request.urlopen, req, timeout=10)
+    rohdaten = task.executor(resp.read)
+    resp.close()
+    daten = json.loads(rohdaten.decode("utf-8"))
+    return daten[0] if daten else []
+
+
+# ------------------------------------------------------------- Kernlogik
+
+def naechster_wert(zielzeit, punkte):
+    """Wert aus der Historie, dessen Zeitstempel am nächsten an zielzeit
+    liegt. Gibt (wert, zeitdifferenz_s) zurück, oder (None, None). Öffentlich,
+    weil auch belegverarbeitung.py sie für den Tankfüllstand nutzt."""
+    beste_wert = None
+    beste_diff = None
+    for p in punkte:
+        try:
+            wert = float(p["state"])
+        except (ValueError, TypeError, KeyError):
+            continue
+        try:
+            zeit = datetime.datetime.fromisoformat(
+                p["last_changed"].replace("Z", "+00:00")
+            )
+        except (ValueError, KeyError):
+            continue
+        diff = abs((zeit - zielzeit).total_seconds())
+        if beste_diff is None or diff < beste_diff:
+            beste_wert = wert
+            beste_diff = diff
+    return beste_wert, beste_diff
+
+
+def _zeitpunkt_screenen(km_sensor, zielzeit):
+    start = (zielzeit - datetime.timedelta(hours=SUCHFENSTER_STUNDEN)).isoformat()
+    ende = (zielzeit + datetime.timedelta(hours=SUCHFENSTER_STUNDEN)).isoformat()
+    try:
+        punkte = historie_abfragen(km_sensor, start, ende)
+    except Exception as exc:
+        # Fehlt z. B. der Token (INSTALL.md Schritt 5) oder ist die API kurz
+        # nicht erreichbar, bleibt die Fahrt einfach offen statt den ganzen
+        # Screening-Lauf für alle anderen offenen Fahrten abzubrechen.
+        log.warning(f"audi_dashboard: Kilometerstand-Screening fehlgeschlagen: {exc}")
+        return None
+    wert, _ = naechster_wert(zielzeit, punkte)
+    return wert
+
+
+def screening_durchfuehren(km_sensor):
+    """Versucht, offene Fahrten mit Start-/Endkilometer zu vervollständigen.
+    Wird sowohl nach Ablauf der Pausenzeit (§7.1) als auch bei jeder Änderung
+    des Kilometerstand-Sensors aufgerufen."""
+    fahrten = profil.fahrten_lesen()
+    offene = [f for f in fahrten if f.get("status") == "offen"]
+    if not offene:
+        return
+
+    offene.sort(key=lambda f: f.get("ts_start", ""))
+
+    for fahrt in offene:
+        geaendert = False
+
+        if fahrt.get("odo_end") is None:
+            ts_end = datetime.datetime.fromisoformat(fahrt["ts_end"])
+            wert = _zeitpunkt_screenen(km_sensor, ts_end)
+            if wert is not None:
+                fahrt["odo_end"] = wert
+                geaendert = True
+
+        if fahrt.get("odo_start") is None:
+            ts_start = datetime.datetime.fromisoformat(fahrt["ts_start"])
+            wert = _zeitpunkt_screenen(km_sensor, ts_start)
+            if wert is not None:
+                fahrt["odo_start"] = wert
+                geaendert = True
+
+        if geaendert:
+            aenderungen = {"odo_start": fahrt.get("odo_start"), "odo_end": fahrt.get("odo_end")}
+            if fahrt.get("odo_start") is not None and fahrt.get("odo_end") is not None:
+                aenderungen["distance_km"] = round(fahrt["odo_end"] - fahrt["odo_start"], 1)
+                aenderungen["km_quelle"] = "odometer"
+                aenderungen["status"] = "vollständig"
+            profil.fahrt_aktualisieren(fahrt["trip_id"], aenderungen)
+
+    _lueckenlos_verketten()
+    frontend_veroeffentlichung.fahrten_veroeffentlichen()
+
+
+def _lueckenlos_verketten():
+    """Fahrt-Ende(N) == Fahrt-Start(N+1), solange dazwischen nicht gefahren
+    wurde (§7.2). Zwischen zwei in der Liste direkt aufeinanderfolgenden
+    Fahrten steht das Fahrzeug nur - der Kilometerstand ändert sich dabei
+    nicht, unabhängig davon, wie lange die Standzeit dauert. Ein bestätigter
+    Wert wird deshalb an den direkten Nachbarn weitergereicht, auch wenn
+    dessen eigenes Screening noch keinen Treffer hatte.
+
+    Annahme: die Fahrten-Liste enthält keine Lücken durch verpasste
+    Verbindungsereignisse (z. B. durch einen HA-Neustart mitten in einer
+    Fahrt). Das ist der Normalfall, aber keine Garantie - siehe
+    Abschlussbericht."""
+    fahrten = sorted(profil.fahrten_lesen(), key=lambda f: f.get("ts_start", ""))
+    geaendert_ids = []
+
+    for i in range(len(fahrten) - 1):
+        aktuelle, naechste = fahrten[i], fahrten[i + 1]
+
+        if aktuelle.get("odo_end") is not None and naechste.get("odo_start") is None:
+            naechste["odo_start"] = aktuelle["odo_end"]
+            geaendert_ids.append(naechste["trip_id"])
+        elif naechste.get("odo_start") is not None and aktuelle.get("odo_end") is None:
+            aktuelle["odo_end"] = naechste["odo_start"]
+            geaendert_ids.append(aktuelle["trip_id"])
+
+    for fahrt in fahrten:
+        if fahrt["trip_id"] not in geaendert_ids:
+            continue
+        aenderungen = {"odo_start": fahrt.get("odo_start"), "odo_end": fahrt.get("odo_end")}
+        if fahrt.get("odo_start") is not None and fahrt.get("odo_end") is not None:
+            aenderungen["distance_km"] = round(fahrt["odo_end"] - fahrt["odo_start"], 1)
+            aenderungen["km_quelle"] = "odometer"
+            aenderungen["status"] = "vollständig"
+        profil.fahrt_aktualisieren(fahrt["trip_id"], aenderungen)

homeassistant/installationspaket/pyscript/modules/frontend_veroeffentlichung.py

@@ -0,0 +1,198 @@
+"""Veröffentlicht Profil, Fahrten, Tankvorgänge und den Live-Fahrzeugstatus
+als pyscript-Zustandsentitäten, damit das Frontend sie über das ganz normale
+hass.states lesen kann - kein Service-Aufruf mit Rückgabewert nötig, dessen
+genaues Verhalten in der Home-Assistant-Weboberfläche nicht durchgängig
+dokumentiert ist (siehe Kopfkommentar in frontend_api.py).
+
+Importierbar mit `import frontend_veroeffentlichung`, aufgerufen sowohl
+periodisch (frontend_api.py) als auch direkt nach Schreibaktionen aus
+fahrterkennung.py, belegverarbeitung.py und reifenzaehler.py, damit sich die
+Oberfläche unmittelbar aktualisiert statt bis zum nächsten Intervall zu
+warten.
+
+BEKANNTE GRENZE: Zustands-Attribute in Home Assistant sind nicht für beliebig
+große Datenmengen gedacht (~16 KB Richtwert für die Aufzeichnung in der
+Recorder-Datenbank). Für das Profil und den aktuellen Stand ist das
+unkritisch; die Fahrten- und Tankvorgänge-Archive könnten das nach einigen
+Jahren überschreiten. Wird das relevant, müssten fahrten_veroeffentlichen()/
+tankvorgaenge_veroeffentlichen() auf einen Zeitraum eingeschränkt werden
+(z. B. nur das laufende Jahr), statt hier vorschnell zu vereinfachen.
+"""
+
+import einstellungen
+import entitaeten
+import profil
+
+
+def profil_veroeffentlichen():
+    daten = profil.profil_lesen()
+    if daten is None:
+        return
+    state.set("pyscript.audi_dashboard_profil", "aktuell", new_attributes={"daten": daten})
+
+
+def fahrten_veroeffentlichen():
+    state.set("pyscript.audi_dashboard_fahrten", "aktuell", new_attributes={"daten": profil.fahrten_lesen()})
+
+
+def tankvorgaenge_veroeffentlichen():
+    state.set("pyscript.audi_dashboard_tankvorgaenge", "aktuell", new_attributes={"daten": profil.tankvorgaenge_lesen()})
+
+
+def batterieverlauf_veroeffentlichen():
+    state.set("pyscript.audi_dashboard_batterieverlauf", "aktuell", new_attributes={"daten": profil.batterieverlauf_lesen()})
+
+
+def entitaeten_veroeffentlichen():
+    """Katalog + aktuell wirksame Zuordnung fürs Setup-Menü (Einstellungen ->
+    Fahrzeug einrichten -> Setup) - siehe entitaeten.py."""
+    state.set("pyscript.audi_dashboard_entitaeten", "aktuell", new_attributes={"daten": entitaeten.aktueller_stand()})
+
+
+def beleg_ergebnis_veroeffentlichen(daten):
+    """Ergebnis eines Beleg-Uploads (geparste Werte fürs Ausfüllen eines
+    Entwurfs, oder ein Fehler wie 'Falsches Belegdatum') fürs Frontend, nach
+    demselben Zustands-statt-Rückgabewert-Muster wie die übrigen
+    veroeffentlichen()-Funktionen hier (siehe Kopfkommentar)."""
+    state.set("pyscript.audi_dashboard_beleg_ergebnis", "aktuell", new_attributes={"daten": daten})
+
+
+def zustand_oder_none(entity_id):
+    """Sicherer Zustandszugriff: pyscripts state.get() wirft NameError, wenn
+    die Entity (noch) nicht existiert - real an einer Testinstanz beobachtet,
+    nicht nur vermutet. Genau das ist hier der Normalfall, solange manche der
+    in einstellungen.py hinterlegten Entity-IDs noch Platzhalter sind, und
+    bleibt auch danach relevant: fällt eine Datenquelle aus, soll die
+    Oberfläche das zeigen (§9), nicht an einem Fehler hängen bleiben."""
+    if not entity_id:
+        return None
+    try:
+        wert = state.get(entity_id)
+    except NameError:
+        return None
+    if wert in (None, "unknown", "unavailable"):
+        return None
+    return wert
+
+
+def _zu_zahl(wert):
+    try:
+        return float(wert)
+    except (TypeError, ValueError):
+        return None
+
+
+def _abs_zahl(wert):
+    zahl = _zu_zahl(wert)
+    return None if zahl is None else abs(zahl)
+
+
+def _standort():
+    """Live-GPS-Position des Fahrzeugs (Übersicht -> Standort-Kachel) - liest
+    STANDORT_LAT_SENSOR/STANDORT_LON_SENSOR, zwei eigene sensor-Entities für
+    Breiten-/Längengrad (flespi liefert Koordinaten so, nicht als Attribute
+    einer einzelnen device_tracker-Entity). Fehlt eine der beiden Entity-IDs
+    oder ist der Zustand (noch) nicht verfügbar, liefert diese Funktion
+    durchgehend None statt eines geratenen Werts - genau das
+    zustand_oder_none()-Muster von oben, hier als eigene Funktion, weil
+    zusätzlich zum Zustand noch der Aktualisierungszeitpunkt gebraucht wird:
+    state.get() liefert dafür ein StateVal (str-Unterklasse) mit
+    .last_updated als datetime-Attribut - kein eigenständiges
+    state.last_updated(), das gibt es in pyscript nicht."""
+    leer = {"lat": None, "lon": None, "genauigkeit_m": None, "zeit": None}
+
+    lat_id, lon_id = einstellungen.STANDORT_LAT_SENSOR, einstellungen.STANDORT_LON_SENSOR
+    if not lat_id or not lon_id:
+        return leer
+    try:
+        lat_wert = state.get(lat_id)
+        lon_wert = state.get(lon_id)
+    except NameError:
+        return leer
+    lat, lon = _zu_zahl(lat_wert), _zu_zahl(lon_wert)
+    if lat is None or lon is None:
+        return leer
+    zeit = None
+    try:
+        zeit = lat_wert.last_updated.isoformat()
+    except AttributeError:
+        pass
+    return {"lat": lat, "lon": lon, "genauigkeit_m": None, "zeit": zeit}
+
+
+POSITIONEN = ["vorne links", "vorne rechts", "hinten links", "hinten rechts"]
+
+
+def _sicherheitscheck():
+    """Liste der einzeln geprüften Punkte hinter "Sicher abgestellt" (§9),
+    fürs Frontend (Klick auf den Status öffnet diese Liste mit einem grünen/
+    roten/grauen Punkt je Zeile). "ok" ist None, wenn der Sensor fehlt oder
+    nicht verfügbar ist - genau daraus leitet sich auch die zusammengefasste
+    gesichert-Kennzahl unten ab, damit beide nie auseinanderlaufen können."""
+    eintraege = []
+    for pos, sensor in zip(POSITIONEN, einstellungen.TUER_SENSOREN):
+        w = zustand_oder_none(sensor)
+        eintraege.append({"label": f"Tür {pos}", "ok": None if w is None else w == "off"})
+    for pos, sensor in zip(POSITIONEN, einstellungen.FENSTER_SENSOREN):
+        w = zustand_oder_none(sensor)
+        eintraege.append({"label": f"Fenster {pos}", "ok": None if w is None else w == "off"})
+    for label, sensor in [
+        ("Heckklappe", einstellungen.HECKKLAPPE_SENSOR),
+        ("Heckklappenschloss", einstellungen.HECKKLAPPENSCHLOSS_SENSOR),
+        ("Motorhaube", einstellungen.HAUBE_SENSOR),
+    ]:
+        w = zustand_oder_none(sensor)
+        eintraege.append({"label": label, "ok": None if w is None else w == "off"})
+    return eintraege
+
+
+def fahrzeugstatus_veroeffentlichen():
+    """Bündelt die live aus Home Assistant gelesenen Fahrzeugwerte
+    Frontend-freundlich, damit die Oberfläche keine Entity-IDs kennen muss.
+    """
+    km = zustand_oder_none(einstellungen.KM_SENSOR)
+    tankprozent = zustand_oder_none(einstellungen.TANK_SENSOR)
+    reichweite = zustand_oder_none(einstellungen.RANGE_SENSOR)
+    batteriespannung = zustand_oder_none(einstellungen.BATTERIE_SENSOR)
+
+    # "Sicher abgestellt" (§9) - erst wenn WIRKLICH jeder einzeln geprüfte
+    # Punkt zu/verriegelt ist, gilt das Fahrzeug als gesichert; fehlt auch
+    # nur eine Meldung, ist der Status unbekannt statt geraten.
+    sicherheitscheck = _sicherheitscheck()
+    if any([e["ok"] is None for e in sicherheitscheck]):
+        gesichert = None
+    else:
+        gesichert = all([e["ok"] for e in sicherheitscheck])
+
+    standort = _standort()
+
+    daten = {
+        "km": _zu_zahl(km),
+        "tankprozent": _zu_zahl(tankprozent),
+        "reichweite_km": _zu_zahl(reichweite),
+        "batteriespannung": _zu_zahl(batteriespannung),
+        "gesichert": gesichert,
+        "sicherheitscheck": sicherheitscheck,
+        "standort_lat": standort["lat"],
+        "standort_lon": standort["lon"],
+        "standort_genauigkeit_m": standort["genauigkeit_m"],
+        "standort_zeit": standort["zeit"],
+        # Vom Fahrzeug selbst gemeldete Service-Fälligkeit (ergänzt die
+        # App-eigene Servicebuch-Berechnung, siehe fahrzeugMeldung() im
+        # Frontend) - die Streckensensoren liefern negative Restkilometer-
+        # Werte, hier deshalb der Betrag.
+        "oelwechsel_faellig_ts": zustand_oder_none(einstellungen.NAECHSTER_OELWECHSEL_SENSOR),
+        "oelwechsel_faellig_km": _abs_zahl(zustand_oder_none(einstellungen.OELWECHSEL_STRECKE_SENSOR)),
+        "inspektion_faellig_ts": zustand_oder_none(einstellungen.NAECHSTE_INSPEKTION_SENSOR),
+        "inspektion_faellig_km": _abs_zahl(zustand_oder_none(einstellungen.INSPEKTION_STRECKE_SENSOR)),
+    }
+    state.set("pyscript.audi_dashboard_fahrzeugstatus", "aktuell", new_attributes={"daten": daten})
+
+
+def alles_veroeffentlichen():
+    profil_veroeffentlichen()
+    fahrten_veroeffentlichen()
+    tankvorgaenge_veroeffentlichen()
+    fahrzeugstatus_veroeffentlichen()
+    batterieverlauf_veroeffentlichen()
+    entitaeten_veroeffentlichen()

homeassistant/installationspaket/pyscript/modules/profil.py

@@ -0,0 +1,280 @@
+"""Datenzugriff für Fahrzeugprofil, Fahrten und Tankvorgänge (Bauauftrag §6).
+
+Importierbar aus anderen pyscript-Dateien mit `import profil`.
+
+Drei getrennte Bestände, wie in §6.1 festgelegt:
+  - Fahrzeugprofil: eine JSON-Datei, alles Fahrzeugspezifische
+  - Fahrten: JSON Lines, eine Zeile je Fahrt
+  - Tankvorgänge: JSON Lines
+
+Drei Eigenheiten von pyscript, alle an einer echten Testinstanz beobachtet,
+nicht nur aus der Dokumentation übernommen:
+
+1. Das eingebaute `open()` existiert in pyscript nicht (NameError) - aus
+   Sicherheitsgründen bewusst nicht freigegeben. Der funktionierende Weg ist
+   `task.executor(io.open, pfad, modus)`: `io.open` ist eine echte externe
+   Funktion aus der Standardbibliothek, kein im pyscript-Ordner selbst
+   definierter Code.
+2. task.executor() akzeptiert generell nur solche echten externen Funktionen
+   - eigene, im pyscript-Ordner definierte Funktionen weist es mit "pyscript
+   functions can't be called from task.executor" zurück. Deshalb hier nur
+   `io.open` selbst über den Executor, Lesen/Schreiben/Schließen auf dem
+   zurückgegebenen Datei-Objekt direkt (das ist kein bare-name-Aufruf mehr,
+   sondern ein Methodenaufruf auf einem bereits vorhandenen Objekt).
+3. Variablen, die innerhalb eines `with ... as f:`-Blocks zugewiesen werden,
+   waren danach außerhalb nicht mehr auffindbar (NameError), deshalb kein
+   `with` - offen/lesen/schließen nacheinander.
+"""
+
+import io
+import json
+import os
+import uuid
+
+BASIS = "/config/audi_dashboard"
+PROFIL_PFAD = f"{BASIS}/fahrzeugprofil.json"
+FAHRTEN_PFAD = f"{BASIS}/fahrten.jsonl"
+TANKVORGAENGE_PFAD = f"{BASIS}/tankvorgaenge.jsonl"
+BATTERIEVERLAUF_PFAD = f"{BASIS}/batteriespannung.jsonl"
+BELEGE_ORDNER = f"{BASIS}/belege"
+
+
+# ---------------------------------------------------------------- Ordner ---
+
+def ordner_sicherstellen():
+    os.makedirs(BASIS, exist_ok=True)
+    os.makedirs(BELEGE_ORDNER, exist_ok=True)
+
+
+# ----------------------------------------------------------- Fahrzeugprofil
+
+def profil_lesen():
+    """Liest das Fahrzeugprofil, oder None wenn es fehlt bzw. beschädigt ist.
+
+    Ohne diese Prüfung reißt eine fehlende Datei (Installation unvollständig,
+    siehe INSTALL.md Schritt 2) jeden Trigger und jeden Service mit, der das
+    Profil braucht — bei laufenden Zeittriggern also im Minutentakt. Jeder
+    Aufrufer muss den None-Fall abfangen."""
+    if not os.path.exists(PROFIL_PFAD):
+        log.error(
+            f"audi_dashboard: {PROFIL_PFAD} fehlt. Siehe INSTALL.md Schritt 2 — "
+            "bis dahin bleiben alle Funktionen aus, die das Profil brauchen."
+        )
+        return None
+    f = task.executor(io.open, PROFIL_PFAD, "r")
+    inhalt = f.read()
+    f.close()
+    try:
+        return json.loads(inhalt)
+    except ValueError as fehler:
+        log.error(
+            f"audi_dashboard: {PROFIL_PFAD} ist kein gültiges JSON ({fehler}). "
+            "Letztes Backup aus audi_dashboard/backups/ zurückspielen."
+        )
+        return None
+
+
+def profil_schreiben(profil):
+    tmp = PROFIL_PFAD + ".tmp"
+    text = json.dumps(profil, ensure_ascii=False, indent=2)
+    f = task.executor(io.open, tmp, "w")
+    f.write(text)
+    f.close()
+    os.replace(tmp, PROFIL_PFAD)
+
+
+# --------------------------------------------------------- JSON-Lines-Basis
+
+def _zeilen_lesen(pfad):
+    if not os.path.exists(pfad):
+        return []
+    f = task.executor(io.open, pfad, "r")
+    inhalt = f.read()
+    f.close()
+    datensaetze = []
+    for zeile in inhalt.splitlines():
+        zeile = zeile.strip()
+        if zeile:
+            datensaetze.append(json.loads(zeile))
+    return datensaetze
+
+
+def _zeilen_schreiben(pfad, datensaetze):
+    tmp = pfad + ".tmp"
+    zeilen = [json.dumps(d, ensure_ascii=False) for d in datensaetze]
+    text = "\n".join(zeilen)
+    if zeilen:
+        text += "\n"
+    f = task.executor(io.open, tmp, "w")
+    f.write(text)
+    f.close()
+    os.replace(tmp, pfad)
+
+
+def _zeile_anhaengen(pfad, datensatz):
+    f = task.executor(io.open, pfad, "a")
+    f.write(json.dumps(datensatz, ensure_ascii=False) + "\n")
+    f.close()
+
+
+# ------------------------------------------------------------------ Fahrten
+
+def fahrten_lesen():
+    return _zeilen_lesen(FAHRTEN_PFAD)
+
+
+def fahrten_schreiben(fahrten):
+    _zeilen_schreiben(FAHRTEN_PFAD, fahrten)
+
+
+def fahrt_anhaengen(fahrt):
+    _zeile_anhaengen(FAHRTEN_PFAD, fahrt)
+
+
+def offene_fahrten():
+    """Alle Fahrten mit status == 'offen', ältere zuerst."""
+    fahrten = fahrten_lesen()
+    offen = [f for f in fahrten if f.get("status") == "offen"]
+    return sorted(offen, key=lambda f: f.get("ts_start", ""))
+
+
+def _datensatz_aktualisieren(zeilen, id_feld, id_wert, aenderungen, schreiben):
+    """Ersetzt ausgewählte Felder eines Datensatzes anhand seiner ID und
+    schreibt den gesamten Bestand neu. Manuell geänderte Felder
+    (edited_fields, analog zu §7.7 Regel 3) werden dabei nie überschrieben.
+    Gemeinsame Grundlage für Fahrten und Tankvorgänge - beide Archive
+    funktionieren nach demselben Muster."""
+    geaendert = False
+    for d in zeilen:
+        if d.get(id_feld) == id_wert:
+            geschuetzt = set(d.get("edited_fields", []))
+            for feld, wert in aenderungen.items():
+                if feld not in geschuetzt:
+                    d[feld] = wert
+            geaendert = True
+            break
+    if geaendert:
+        schreiben(zeilen)
+    return geaendert
+
+
+def fahrt_aktualisieren(trip_id, aenderungen):
+    return _datensatz_aktualisieren(fahrten_lesen(), "trip_id", trip_id, aenderungen, fahrten_schreiben)
+
+
+def fahrt_loeschen(trip_id):
+    fahrten = fahrten_lesen()
+    uebrig = [f for f in fahrten if f.get("trip_id") != trip_id]
+    if len(uebrig) == len(fahrten):
+        return False
+    fahrten_schreiben(uebrig)
+    return True
+
+
+# ------------------------------------------------------------ Tankvorgänge
+
+def tankvorgaenge_lesen():
+    return _zeilen_lesen(TANKVORGAENGE_PFAD)
+
+
+def tankvorgaenge_schreiben(tankvorgaenge):
+    _zeilen_schreiben(TANKVORGAENGE_PFAD, tankvorgaenge)
+
+
+def tankvorgang_anhaengen(tankvorgang):
+    _zeile_anhaengen(TANKVORGAENGE_PFAD, tankvorgang)
+
+
+def tankvorgang_aktualisieren(tank_id, aenderungen):
+    return _datensatz_aktualisieren(tankvorgaenge_lesen(), "tank_id", tank_id, aenderungen, tankvorgaenge_schreiben)
+
+
+def tankvorgang_loeschen(tank_id):
+    tankvorgaenge = tankvorgaenge_lesen()
+    uebrig = [t for t in tankvorgaenge if t.get("tank_id") != tank_id]
+    if len(uebrig) == len(tankvorgaenge):
+        return False
+    tankvorgaenge_schreiben(uebrig)
+    return True
+
+
+def letzter_tankvorgang():
+    """Der zeitlich jüngste bereits erfasste Tankvorgang (nach ts), oder None,
+    falls noch keiner existiert. Grundlage für die Gefahrene-Distanz-Berechnung
+    beim Anlegen eines neuen Tankvorgangs (§5.5)."""
+    tankvorgaenge = tankvorgaenge_lesen()
+    if not tankvorgaenge:
+        return None
+    return max(tankvorgaenge, key=lambda t: t.get("ts") or "")
+
+
+def distanz_seit_letzter_tankung(aktueller_km):
+    """Gefahrene Distanz seit dem vorherigen Tankvorgang, als Vorschlag für
+    das gleichnamige Formularfeld (§5.5) - frei überschreibbar, genau wie
+    odometer_km selbst. None, wenn kein Kilometerstand oder kein vorheriger
+    Tankvorgang vorliegt (erster Eintrag überhaupt). Gemeinsame Grundlage für
+    Beleg-Erfassung (belegverarbeitung.py) und automatische Tankerkennung
+    (tankerkennung.py)."""
+    if aktueller_km is None:
+        return None
+    letzter = letzter_tankvorgang()
+    if not letzter or letzter.get("odometer_km") is None:
+        return None
+    return round(aktueller_km - letzter["odometer_km"], 1)
+
+
+def tankvorgang_nach_id(tank_id):
+    for t in tankvorgaenge_lesen():
+        if t.get("tank_id") == tank_id:
+            return t
+    return None
+
+
+def tankvorgang_nach_receipt_key(receipt_key):
+    """Für §7.7 Regel: derselbe Beleg (receipt_key, minutengenau) erzeugt
+    keinen zweiten Datensatz."""
+    for t in tankvorgaenge_lesen():
+        if t.get("receipt_key") == receipt_key:
+            return t
+    return None
+
+
+# ------------------------------------------------------- Batteriespannung
+
+def batterieverlauf_lesen():
+    """Ein Eintrag pro Tag ({datum, min, min_ts, max, max_ts}), älteste
+    zuerst - siehe batterieverlauf.py für die Aufzeichnungslogik. min_ts/
+    max_ts sind die Zeitstempel (ISO, UTC) der jeweiligen Einzelmessung, für
+    die Datum/Uhrzeit-Anzeige beim Antippen des Diagrammpunkts im Frontend -
+    der Punkt selbst zeigt nur den Minimalwert (siehe dortiger Kommentar,
+    warum der aussagekräftig für die Entladung ist)."""
+    return _zeilen_lesen(BATTERIEVERLAUF_PFAD)
+
+
+def batterieverlauf_tageswert_aktualisieren(datum, ts, spannung):
+    """Trägt eine neue Messung in den Tageseintrag für `datum` ein: legt ihn
+    beim ersten Wert des Tages an, erweitert sonst nur min/max samt dem
+    Zeitstempel der jeweils neuen Extremmessung. Das Fahrzeug meldet die
+    Spannung künftig mehrfach pro Stunde (aktive Fahrt) statt nur einmal
+    täglich - der komplette Bestand wird deshalb bei jeder Messung neu
+    geschrieben (wie bei den übrigen JSON-Lines-Beständen hier), was bei
+    einem Eintrag pro Tag über Jahre hinweg unproblematisch bleibt."""
+    verlauf = batterieverlauf_lesen()
+    for eintrag in verlauf:
+        if eintrag.get("datum") == datum:
+            if spannung < eintrag["min"]:
+                eintrag["min"] = spannung
+                eintrag["min_ts"] = ts
+            if spannung > eintrag["max"]:
+                eintrag["max"] = spannung
+                eintrag["max_ts"] = ts
+            break
+    else:
+        verlauf.append({"datum": datum, "min": spannung, "min_ts": ts, "max": spannung, "max_ts": ts})
+    _zeilen_schreiben(BATTERIEVERLAUF_PFAD, verlauf)
+
+
+# --------------------------------------------------------------------- IDs
+
+def neue_id(praefix):
+    return f"{praefix}-{uuid.uuid4().hex[:12]}"