audi-app/homeassistant/installationspaket/install.ps1

<#
.SYNOPSIS
  Installiert "Mein Audi" (DataMetric360) in einem Rutsch auf einer neuen
  Home-Assistant-Instanz - die Schritte 1-3 aus ANLEITUNG.md.

.BESCHREIBUNG
  Nimmt dem Erstaufsetzen die Handarbeit ab:
    1. pyscript\           -> <Ziel>\pyscript\
    2. data\               -> <Ziel>\audi_dashboard\   (Ordner wird umbenannt)
       fahrzeugprofil.example.json -> fahrzeugprofil.json
    3. www\                -> <Ziel>\www\
    4. configuration_snippet.yaml wird in <Ziel>\configuration.yaml eingefügt
    5. ha_token.txt wird geschrieben, wenn -Token übergeben wurde

  SICHERHEIT GEGENÜBER DER BESTEHENDEN HA-INSTALLATION
  ----------------------------------------------------
  Das Skript ist so gebaut, dass es eine laufende Home-Assistant-Installation
  (auch HA OS) nicht gefährden kann. Konkret und nachprüfbar:

    - Es LÖSCHT NIE etwas. Im gesamten Skript kommt kein Remove-Item vor, und
      kopiert wird bewusst ohne robocopy /MIR - fremde Dateien in pyscript\
      und www\ bleiben liegen, es wird nur ergänzt.
    - Es fasst .storage\ nicht an: keine Integrationen, keine Geräte, keine
      Entitäten, keine Benutzer, keine Automatisierungen. automations.yaml,
      scripts.yaml, scenes.yaml und secrets.yaml werden nicht gelesen und
      nicht geschrieben.
    - Es startet Home Assistant nicht neu und greift nicht in den laufenden
      Betrieb ein. Bis zum manuellen Neustart ändert sich am Verhalten der
      Instanz nichts.
    - Die einzige Datei außerhalb der eigenen Ordner, die überhaupt verändert
      wird, ist configuration.yaml - und das ist der einzige Weg, auf dem
      dieses Skript HA am Starten hindern könnte. Deshalb dort drei Netze:
      eine zeitgestempelte Sicherung vor jeder Änderung, ein Abbruch ohne
      jede Änderung falls dort schon fremde pyscript:/panel_custom:-Blöcke
      stehen, und eine Rücklese-Prüfung nach dem Schreiben, die bei der
      kleinsten Abweichung automatisch zurückrollt.
    - -Pruefen zeigt den kompletten Ablauf, ohne irgendetwas zu schreiben.
      Im Zweifel damit anfangen.

  Was das Skript NICHT kann: pyscript installieren (das macht HACS),
  pypdf nachinstallieren (braucht eine Shell auf der HA-Maschine) und HA
  neu starten. Diese Schritte stehen am Ende als Restliste.

  Grundsatz: nichts kaputtmachen, was schon da ist. Das Skript ist darauf
  ausgelegt, gefahrlos mehrfach zu laufen (etwa nach einem Abbruch):

    - Bestandsdaten (fahrzeugprofil.json, fahrten.jsonl, tankvorgaenge.jsonl,
      entitaeten.json, ha_token.txt) werden NIE überschrieben. Wer eine
      laufende Installation neu bespielt, behält sein Fahrzeugprofil, seine
      Fahrten, Tankvorgänge und Sensorzuordnung.
    - configuration.yaml wird vor jeder Änderung nach configuration.yaml.bak
      kopiert. Der eingefügte Teil steht zwischen zwei Markierungszeilen und
      wird bei einem erneuten Lauf ersetzt statt ein zweites Mal angehängt.
    - Stehen `pyscript:` oder `panel_custom:` dort schon aus anderer Quelle,
      fasst das Skript die Datei NICHT an, sondern zeigt an, was von Hand zu
      ergänzen ist. Zwei gleiche Top-Level-Schlüssel wären ungültiges YAML und
      HA würde nicht mehr starten - das ist keine Entscheidung, die ein
      Installer still für jemanden treffen sollte.

  Nicht automatisierbar und deshalb am Ende als Restliste ausgegeben:
  HA-Neustart, `pip install pypdf` (braucht eine Shell auf der HA-Maschine)
  und das Zuordnen der Sensoren im Setup-Menü der App.

.PARAMETER Ziel
  config-Verzeichnis der HA-Instanz, z. B. "\\homeassistant.local\config"
  (Samba-Add-on) oder ein lokal gemounteter Pfad. Ohne Angabe sucht das
  Skript die üblichen Samba-Namen selbst ab.

.PARAMETER Token
  Long-Lived Access Token aus HA (Profil-Avatar -> "Long-lived access
  tokens"). Wird nur nach audi_dashboard\ha_token.txt geschrieben und für das
  Kilometerstand-Screening gebraucht. Ohne Angabe wird die Datei nicht
  angelegt und der Schritt landet in der Restliste. Eine schon vorhandene
  Datei bleibt in jedem Fall unangetastet.

.PARAMETER Pruefen
  Nur anzeigen, was passieren würde - es wird nichts geschrieben.

.BEISPIEL
  .\install.ps1
  .\install.ps1 -Ziel "\\192.168.1.50\config"
  .\install.ps1 -Ziel "\\homeassistant.local\config" -Token "eyJhb..."
  .\install.ps1 -Pruefen
#>
param(
    [string]$Ziel,
    [string]$Token,
    [switch]$Pruefen
)

$ErrorActionPreference = "Stop"
$hier = $PSScriptRoot

function Schritt($text)  { Write-Host "`n$text" -ForegroundColor Cyan }
function Gut($text)      { Write-Host "  [ok]   $text" -ForegroundColor Green }
function Info($text)     { Write-Host "  [info] $text" -ForegroundColor DarkGray }
function Warnung($text)  { Write-Host "  [!]    $text" -ForegroundColor Yellow }

# Sammelt alles ein, was der Mensch am Ende noch selbst tun muss.
$restliste = New-Object System.Collections.ArrayList

Write-Host ""
Write-Host "  Mein Audi - Installation" -ForegroundColor White
Write-Host "  ========================" -ForegroundColor White
if ($Pruefen) { Warnung "Pruefmodus - es wird nichts geschrieben." }

# ---------------------------------------------------------------- Ziel finden
if (-not $Ziel) {
    Schritt "Suche Home Assistant ..."
    # Die Reihenfolge ist Absicht: der kurze Name antwortet in den meisten
    # Heimnetzen schneller als der .local-Name über mDNS.
    $kandidaten = @(
        "\\homeassistant\config",
        "\\homeassistant.local\config",
        "\\hassio\config"
    )
    foreach ($k in $kandidaten) {
        Info "probiere $k"
        if (Test-Path $k) { $Ziel = $k; break }
    }
    if (-not $Ziel) {
        Write-Host ""
        Warnung "Keine HA-Instanz automatisch gefunden."
        Write-Host "  Bitte den config-Pfad angeben, z. B. \\192.168.1.50\config"
        Write-Host "  (Samba-Share-Add-on in HA muss laufen und verbunden sein.)"
        Write-Host ""
        $Ziel = Read-Host "  config-Pfad"
        if (-not $Ziel) { throw "Kein Ziel angegeben - Abbruch." }
    }
}

if (-not (Test-Path $Ziel)) {
    throw "Ziel nicht erreichbar: $Ziel - Samba-Share verbunden? Pfad korrekt?"
}
Gut "Ziel: $Ziel"

# Ein config-Verzeichnis ohne configuration.yaml ist mit hoher Wahrscheinlichkeit
# der falsche Ordner - lieber hier abbrechen als Dateien irgendwohin streuen.
$configYaml = Join-Path $Ziel "configuration.yaml"
if (-not (Test-Path $configYaml)) {
    throw "In $Ziel liegt keine configuration.yaml - ist das wirklich das config-Verzeichnis von HA?"
}

# pyscript wird über HACS installiert, nicht von hier - ohne die Integration
# läuft das komplette Backend nicht, deshalb früh darauf hinweisen.
if (-not (Test-Path (Join-Path $Ziel "custom_components\pyscript"))) {
    Warnung "custom_components\pyscript fehlt - pyscript ist offenbar noch nicht über HACS installiert."
    [void]$restliste.Add("pyscript über HACS installieren (HACS -> Integrationen -> 'pyscript' -> Download), danach dieses Skript erneut laufen lassen.")
}

# --------------------------------------------------------------- 1. pyscript
Schritt "1/5  pyscript-Backend kopieren"
if ($Pruefen) {
    Info "würde kopieren: $hier\pyscript\*  ->  $Ziel\pyscript\"
} else {
    New-Item -ItemType Directory -Force -Path (Join-Path $Ziel "pyscript") | Out-Null
    # Bewusst kein robocopy /MIR: das würde fremde Skripte im selben Ordner
    # löschen. Hier wird nur ergänzt und überschrieben.
    Copy-Item (Join-Path $hier "pyscript\*") (Join-Path $Ziel "pyscript") -Recurse -Force
    Gut "pyscript\ kopiert"
}

# ------------------------------------------------------- 2. data -> audi_dashboard
Schritt "2/5  Datenverzeichnis anlegen (data -> audi_dashboard)"
$datenZiel = Join-Path $Ziel "audi_dashboard"
# Dateien, die einer laufenden Installation gehören - nie überschreiben.
$bestandsdaten = @(
    "fahrzeugprofil.json",
    "fahrten.jsonl",
    "tankvorgaenge.jsonl",
    "entitaeten.json",
    "ha_token.txt"
)
if (-not $Pruefen) { New-Item -ItemType Directory -Force -Path $datenZiel | Out-Null }

foreach ($datei in Get-ChildItem (Join-Path $hier "data") -File) {
    # fahrzeugprofil.example.json ist die Vorlage und heißt am Ziel anders.
    $zielName = $datei.Name
    if ($zielName -eq "fahrzeugprofil.example.json") { $zielName = "fahrzeugprofil.json" }
    $zielPfad = Join-Path $datenZiel $zielName

    if (($bestandsdaten -contains $zielName) -and (Test-Path $zielPfad)) {
        Info "$zielName existiert bereits - bleibt unverändert"
        continue
    }
    if ($Pruefen) {
        Info "würde schreiben: $zielPfad"
    } else {
        Copy-Item $datei.FullName $zielPfad -Force
        Gut "$zielName"
    }
}

# --------------------------------------------------------------- 3. Frontend
Schritt "3/5  Frontend kopieren"
if ($Pruefen) {
    Info "würde kopieren: $hier\www\*  ->  $Ziel\www\"
} else {
    New-Item -ItemType Directory -Force -Path (Join-Path $Ziel "www") | Out-Null
    Copy-Item (Join-Path $hier "www\*") (Join-Path $Ziel "www") -Recurse -Force

    # Wie in update.ps1: die Versionsdatei bestimmt, ob Browser den neuen Code
    # ziehen. Immer frisch schreiben, sonst zeigt ein Browser, der die App
    # schon einmal geladen hatte, weiter den alten Stand.
    # Zwei Zahlen mit verschiedenen Aufgaben, siehe VERSIONIERUNG.md:
    #   version = Unix-Sekunden, bricht den Browser-Cache, bei jedem Deploy neu
    #   app     = der Stand aus der Datei VERSION, identifiziert die Fassung
    # Die App-Version kommt aus der mitgelieferten Datei und wird ÜBERNOMMEN,
    # nicht neu erfunden - sonst verlöre die iOS-App ihren Vergleichswert und
    # könnte ihre eigene Veraltung nicht mehr erkennen.
    $version = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
    $appVersion = ""
    $quellVersion = Join-Path $hier "www\audi-dashboard-version.json"
    if (Test-Path $quellVersion) {
        try { $appVersion = (Get-Content $quellVersion -Raw | ConvertFrom-Json).app } catch { $appVersion = "" }
    }
    $versionsDatei = Join-Path $Ziel "www\audi-dashboard-version.json"
    $inhaltVersion = if ($appVersion) { "{ ""version"": $version, ""app"": ""$appVersion"" }" }
                     else             { "{ ""version"": $version }" }
    [System.IO.File]::WriteAllText($versionsDatei, $inhaltVersion, (New-Object System.Text.UTF8Encoding($false)))
    Gut "www\ kopiert (Version $version)"
}

# ---------------------------------------------------- 4. configuration.yaml
Schritt "4/5  configuration.yaml ergänzen"
$markeAuf = "# >>> Mein Audi (DataMetric360) - automatisch eingefügt, nicht von Hand bearbeiten"
$markeZu  = "# <<< Mein Audi (DataMetric360)"

# Beide Dateien ausdrücklich als UTF-8 lesen: Get-Content nimmt in
# PowerShell 5.1 sonst die ANSI-Codepage an und macht aus "Ergänzung" ein
# "Ergänzung", das dann so in der configuration.yaml landet.
$utf8OhneBom = New-Object System.Text.UTF8Encoding($false)
$snippet = [System.IO.File]::ReadAllText((Join-Path $hier "configuration_snippet.yaml"), $utf8OhneBom)
$inhalt = [System.IO.File]::ReadAllText($configYaml, $utf8OhneBom)
if ($null -eq $inhalt) { $inhalt = "" }

$block = "$markeAuf`r`n$snippet`r`n$markeZu`r`n"
$schonDa = $inhalt.Contains($markeAuf)

# Top-Level-Schlüssel aus fremder Quelle? Dann Finger weg (siehe Kopfkommentar).
$ohneUnserenBlock = $inhalt
if ($schonDa) {
    $ohneUnserenBlock = [regex]::Replace(
        $inhalt,
        "(?ms)" + [regex]::Escape($markeAuf) + ".*?" + [regex]::Escape($markeZu) + "\r?\n?",
        ""
    )
}
$fremdePyscript = [regex]::IsMatch($ohneUnserenBlock, "(?m)^pyscript:")
$fremdePanel    = [regex]::IsMatch($ohneUnserenBlock, "(?m)^panel_custom:")

if ($fremdePyscript -or $fremdePanel) {
    Warnung "configuration.yaml enthält bereits eigene Einträge - sie wird NICHT verändert."
    if ($fremdePyscript) { Info "gefunden: pyscript:" }
    if ($fremdePanel)    { Info "gefunden: panel_custom:" }
    Write-Host ""
    Write-Host "  Bitte von Hand zusammenführen (Inhalt aus configuration_snippet.yaml):" -ForegroundColor Yellow
    Write-Host "    - unter pyscript:     allow_all_imports: true"
    Write-Host "    -                     hass_is_global: true"
    Write-Host "    - unter panel_custom: den Listeneintrag 'audi-dashboard-panel'"
    [void]$restliste.Add("configuration.yaml von Hand ergänzen (siehe Hinweis oben) - zwei gleiche Top-Level-Schlüssel wären ungültiges YAML.")
} elseif ($Pruefen) {
    if ($schonDa) { Info "würde den vorhandenen Mein-Audi-Block ersetzen" }
    else          { Info "würde den Mein-Audi-Block anhängen" }
} else {
    # Zeitgestempelte Sicherung statt einer festen .bak: die feste Datei wurde
    # bei einem zweiten Lauf von der bereits geänderten Fassung überschrieben -
    # ausgerechnet das Original, auf das man im Notfall zurückwill, war dann weg.
    $sicherung = "$configYaml.bak"
    $stempel = Get-Date -Format "yyyyMMdd-HHmmss"
    $sicherungZeit = "$configYaml.$stempel.bak"
    Copy-Item $configYaml $sicherungZeit -Force
    if (-not (Test-Path $sicherung)) { Copy-Item $configYaml $sicherung -Force }
    Info "Sicherung: $(Split-Path $sicherungZeit -Leaf)"

    if ($schonDa) {
        $neu = [regex]::Replace(
            $inhalt,
            "(?ms)" + [regex]::Escape($markeAuf) + ".*?" + [regex]::Escape($markeZu) + "\r?\n?",
            [System.Text.RegularExpressions.MatchEvaluator]{ param($m) $block }
        )
    } else {
        $trenner = ""
        if ($inhalt.Length -gt 0 -and -not $inhalt.EndsWith("`n")) { $trenner = "`r`n" }
        $neu = $inhalt + $trenner + "`r`n" + $block
    }
    # Ohne BOM schreiben - HA liest die Datei als YAML, ein BOM hat da nichts
    # zu suchen (Out-File -Encoding utf8 setzt in PowerShell 5.1 eines).
    [System.IO.File]::WriteAllText($configYaml, $neu, (New-Object System.Text.UTF8Encoding($false)))

    # Rücklesen und prüfen, bevor wir die Datei so stehen lassen. Eine kaputte
    # configuration.yaml ist der einzige Weg, auf dem dieses Skript eine
    # laufende Home-Assistant-Installation lahmlegen könnte (HA startet dann
    # nicht mehr) - deshalb wird das Ergebnis hier verifiziert und im
    # Zweifelsfall sofort zurückgerollt, statt es dem Nutzer zu überlassen.
    $kontrolle = [System.IO.File]::ReadAllText($configYaml, $utf8OhneBom)
    $bestandNoch = [regex]::Replace(
        $kontrolle,
        "(?ms)" + [regex]::Escape($markeAuf) + ".*?" + [regex]::Escape($markeZu) + "\r?\n?",
        ""
    )
    $treffer = ([regex]::Matches($kontrolle, [regex]::Escape($markeAuf))).Count
    $heil = $true
    $grund = ""
    if ($kontrolle.Length -lt $inhalt.Length) {
        $heil = $false; $grund = "die Datei ist kürzer geworden als vorher"
    } elseif ($treffer -ne 1) {
        $heil = $false; $grund = "der Mein-Audi-Block steht $treffer mal statt genau einmal darin"
    } elseif ($bestandNoch.Trim() -ne $ohneUnserenBlock.Trim()) {
        $heil = $false; $grund = "der bisherige Inhalt der Datei hat sich verändert"
    }

    if (-not $heil) {
        Copy-Item $sicherungZeit $configYaml -Force
        Warnung "configuration.yaml wurde zurückgerollt - $grund."
        Write-Host "  Die Datei ist unverändert wie vor dem Start dieses Skripts." -ForegroundColor Yellow
        [void]$restliste.Add("configuration.yaml von Hand ergänzen (Inhalt aus configuration_snippet.yaml) - der automatische Weg wurde aus Sicherheitsgründen zurückgenommen.")
    } elseif ($schonDa) {
        Gut "vorhandenen Block ersetzt (geprüft)"
    } else {
        Gut "Block angehängt (geprüft)"
    }
}

# --------------------------------------------------------------- 5. Token
Schritt "5/5  Zugriffstoken"
$tokenDatei = Join-Path $datenZiel "ha_token.txt"
if (Test-Path $tokenDatei) {
    Info "ha_token.txt existiert bereits - bleibt unverändert"
} elseif ($Token) {
    if ($Pruefen) {
        Info "würde schreiben: $tokenDatei"
    } else {
        [System.IO.File]::WriteAllText($tokenDatei, $Token.Trim(), (New-Object System.Text.UTF8Encoding($false)))
        Gut "ha_token.txt geschrieben"
    }
} else {
    Info "kein -Token übergeben"
    [void]$restliste.Add("Long-Lived Access Token anlegen (HA: Profil-Avatar unten links -> 'Long-lived access tokens' -> Token erstellen) und den Wert in $tokenDatei speichern - nur den Token, keine Anführungszeichen. Wird fürs Kilometerstand-Screening gebraucht.")
}

# --------------------------------------------------------------- Restliste
# Bewusst nicht automatisch eingefügt: der recorder-Block ist eine Entscheidung
# über den Plattenplatz der Instanz (ein Jahr Fahrzeugverlauf sind grob 1-1,5 GB,
# siehe Kopf von recorder_snippet.yaml), und viele Instanzen haben bereits einen
# eigenen recorder:-Block mit anderen Einstellungen. Zusammenführen ist Handarbeit.
[void]$restliste.Add("ZEITKRITISCH - Datenaufbewahrung: den Block aus recorder_snippet.yaml in die configuration.yaml übernehmen. Home Assistant löscht Sensor-Verläufe sonst nach 10 Tagen; was weg ist, lässt sich auch mit 'Daten importieren aus Home Assistant' nicht mehr nachtragen. Je früher der Block drin ist, desto mehr Vergangenheit bleibt erhalten. VORHER Einstellungen -> System -> Speicher prüfen: ein Jahr Verlauf braucht grob 1-1,5 GB. Bei wenig freiem Platz (SD-Karte, kleine eMMC) mit purge_keep_days: 90 anfangen - Details im Kopf der Datei.")
[void]$restliste.Add("Home Assistant neu starten: Einstellungen -> System -> Neu starten.")
[void]$restliste.Add("Nur für Tankbeleg-Upload: auf der HA-Maschine 'pip install pypdf' ausführen (Terminal-&-SSH-Add-on oder docker exec).")
[void]$restliste.Add("Nach dem Neustart in der App: Einstellungen -> Fahrzeug einrichten -> Setup - Sensoren zuordnen. Im Auslieferstand ist KEIN Sensor vorbelegt; zwingend für die Fahrterkennung ist der Zündungs-/ACC-Sensor (binary_sensor, meist vom Teltonika FMM003). Danach einmal neu starten - die drei trigger-gebundenen Felder (Zündung, Kilometerstand, Tankfüllstand) werden erst dann wirksam.")
[void]$restliste.Add("Optional, sobald die Sensoren zugeordnet sind: Einstellungen -> Einrichten -> 'Daten importieren aus Home Assistant' holt Fahrten, Tankvorgänge und Spannungswerte aus dem bereits aufgezeichneten HA-Verlauf nach.")

Write-Host ""
if ($Pruefen) {
    Write-Host "  Pruefmodus beendet - es wurde nichts geschrieben." -ForegroundColor Yellow
} else {
    Write-Host "  Dateien sind kopiert." -ForegroundColor Green
}
Write-Host ""
Write-Host "  Das fehlt noch:" -ForegroundColor White
$nr = 1
foreach ($punkt in $restliste) {
    Write-Host "   $nr. $punkt"
    $nr++
}
Write-Host ""
Write-Host "  Danach erscheint 'Mein Audi' in der Seitenleiste." -ForegroundColor White
Write-Host "  Spätere Updates: update.ps1 statt install.ps1 - das lässt audi_dashboard\ in Ruhe."
Write-Host ""