/* ================================================================
   Typen der Home-Assistant-Schnittstelle und der Fachdaten
   ================================================================
   Die Fachtypen (Fahrt, Tankvorgang, ...) sind aus SPECIFICATION.md §5
   "Data files" abgeleitet - also aus dem, was das Backend tatsächlich in
   fahrten.jsonl / tankvorgaenge.jsonl schreibt, nicht aus Wunschdenken.
   Felder, die laut §7 im Schema stehen, aber von keinem Codepfad je gefüllt
   werden (start_lat, avg_speed_kmh, route, ...), sind hier bewusst als
   optional markiert - sie können null/undefined sein und die Oberfläche darf
   sich nie darauf verlassen. */

/** Roher Zustand einer HA-Entität, wie ihn /api/states liefert. */
export interface HassState<A = Record<string, unknown>> {
  entity_id: string;
  state: string;
  attributes: A;
  last_changed: string;
  last_updated: string;
  context?: { id: string; parent_id: string | null; user_id: string | null };
}

/** Die Entitäten der Integration transportieren ihre Nutzlast im Attribut "daten". */
export interface DatenAttribute<T> {
  daten: T;
  [weitere: string]: unknown;
}

export type DatenEntity<T> = HassState<DatenAttribute<T>>;

/* ----------------------------------------------------------- Fachdaten */

export type Fahrtart = "privat" | "arbeitsweg";
export type FahrtStatus = "offen" | "vollständig";
export type FahrtQuelle = "ha" | "manual";

export interface Fahrt {
  trip_id: string;
  ts_start: string;
  ts_end: string;
  duration_s: number;
  distance_km: number | null;
  /** "odometer" ist der einzige Wert, den das Backend je erzeugt (§7.1). */
  km_quelle: "odometer" | "gps" | null;
  odo_start: number | null;
  odo_end: number | null;
  art: Fahrtart;
  source: FahrtQuelle;
  status: FahrtStatus;
  edited_fields?: string[];
  /* Ab FMM003 erstmals real befüllbar - bis dahin durchgehend null (§7.2). */
  avg_speed_kmh?: number | null;
  start_lat?: number | null;
  start_lon?: number | null;
  end_lat?: number | null;
  end_lon?: number | null;
  start_address?: string | null;
  end_address?: string | null;
  route?: unknown | null;
  pausen?: unknown[];
}

export type TankStatus = "unvollständig" | "vollständig";
export type TankQuelle = "auto" | "manual" | "beleg";

export interface Tankvorgang {
  tank_id: string;
  ts: string;
  liters: number | null;
  fuel_total_eur: number | null;
  /** Immer aus fuel_total_eur/liters berechnet, nie aus dem Beleg gelesen. */
  price_per_l: number | null;
  station_name?: string | null;
  station_id?: string | null;
  station_address?: string | null;
  fuel_type?: string | null;
  product_name?: string | null;
  discount?: number | null;
  discount_per_l?: number | null;
  list_price_per_l?: number | null;
  receipt_total_eur?: number | null;
  receipt_key?: string | null;
  receipt_no?: string | null;
  receipt_file?: string | null;
  odometer_km?: number | null;
  distance_km?: number | null;
  source: TankQuelle;
  status: TankStatus;
  edited_fields?: string[];
}

/** Einzelprüfung aus _sicherheitscheck: ok===null heißt "Sensor unbekannt".
    "gruppe" fasst mehrere Punkte zu einer Sammelzeile zusammen (verriegelt /
    tueren_klappen / fenster_dach / licht), siehe Fahrzeugstatus.tsx. */
export interface SicherheitsPunkt {
  label: string;
  ok: boolean | null;
  gruppe: "verriegelt" | "tueren_klappen" | "fenster_dach" | "licht";
}

/** Feldnamen an der laufenden Instanz abgelesen, nicht aus der Spezifikation
    abgeleitet: veroeffentlichung.py schreibt "tankprozent",
    "gesichert" und "sicherheitscheck" — ein früherer Entwurf dieser Datei
    hatte "tank_prozent"/"sicher_abgestellt"/"sicherheit" angenommen, womit
    die Oberfläche still überall undefined gelesen hätte. */
export interface Fahrzeugstatus {
  km?: number | null;
  tankprozent?: number | null;
  reichweite_km?: number | null;
  batteriespannung?: number | null;
  gesichert?: boolean | null;
  sicherheitscheck?: SicherheitsPunkt[];
  /** Zündung an = fährt gerade. `null`/fehlend heißt „kein Zündungssensor
      zugeordnet", also unbekannt — ausdrücklich nicht „steht". */
  zuendung?: boolean | null;
  standort_lat?: number | null;
  standort_lon?: number | null;
  standort_genauigkeit_m?: number | null;
  standort_zeit?: string | null;
  oelwechsel_faellig_ts?: string | null;
  oelwechsel_faellig_km?: number | null;
  inspektion_faellig_ts?: string | null;
  inspektion_faellig_km?: number | null;
  [weitere: string]: unknown;
}

/** Das Profil ist ein großer, frei geformter JSON-Blob (§5). Die Oberfläche
    greift gezielt auf Abschnitte zu; ein vollständiger Typ wäre hier nur
    scheingenau, solange das Backend ihn nicht erzwingt. */
export interface Profil {
  fahrzeug?: Record<string, unknown>;
  einstellungen?: Record<string, unknown>;
  versicherung?: Record<string, unknown>;
  steuer?: Record<string, unknown>;
  reifen?: Record<string, unknown>;
  service?: Record<string, unknown>;
  /* Beide sind Listen von Gruppen, keine Objekte - an der echten
     fahrzeugprofil.json abgelesen. Ein früherer Entwurf hatte sie wie die
     übrigen Abschnitte als Record deklariert. */
  technik?: unknown[];
  ausstattung?: unknown[];
  [weitere: string]: unknown;
}

/** Ergebnis eines Historien-Imports (custom_components/audi_dashboard/historienimport.py). Die
    Zählwerte fehlen, solange der Lauf noch nicht fertig ist; `meldung` steht
    nur im Fehlerfall. */
export interface ImportErgebnis {
  von?: string;
  bis?: string;
  /** Frühester Zeitpunkt mit Aufzeichnung im gewählten Fenster — erklärt ein
      leeres Ergebnis („weiter zurück bewahrt HA nichts mehr auf"). */
  ab_wann_daten?: string | null;
  fahrten_angelegt?: number;
  fahrten_uebersprungen?: number;
  fahrten_zu_kurz?: number;
  tankvorgaenge_angelegt?: number;
  tankvorgaenge_uebersprungen?: number;
  batterie_tage?: number;
  meldung?: string;
}

/** Das OTA-Bündel, das die Integration mit ausliefert (siehe
    custom_components/audi_dashboard/koordinator.py `_buendel_lesen()` und
    companion-app/scripts/ota-paket.ps1). `null`, solange keine
    bundle.json neben der Integration liegt — ein völlig normaler Zustand,
    kein Fehler: wer nur das Panel nutzt, braucht kein App-Bündel. */
export interface Buendelangabe {
  version: string;
  sha256: string;
  bytes: number;
  gebaut: string;
  /** Pfad relativ zur Home-Assistant-Basis-URL, z. B.
      "/audi_dashboard_static/app/bundle.zip". Von der Integration
      angehängt, steht nicht in bundle.json selbst. */
  url: string;
}

/** Ergebnis der letzten "Auf Update prüfen"/"Update installieren"-Aktion
    (custom_components/audi_dashboard/aktualisierung.py, dienste.py). `null`,
    solange noch nie geprüft wurde - ein normaler Zustand, kein Fehler.
    Ersetzt install.ps1 als Update-Weg, weil Windows Smart App Control es
    zuverlässig blockiert. */
export interface IntegrationUpdateAngabe {
  verfuegbar: boolean;
  version: string | null;
  geprueft_am: string;
  /** true unmittelbar nach einer erfolgreichen Installation - dann ist ein
      Neustart von Home Assistant nötig, damit die neue Fassung geladen wird. */
  installiert: boolean;
  fehler: string | null;
}

/** Nutzlast von sensor.audi_dashboard_app_version. */
export interface AppVersionAngabe {
  app: string | null;
  buendel: Buendelangabe | null;
  integration_update: IntegrationUpdateAngabe | null;
}

/* -------------------------------------------------- Entitäts-Verzeichnis */

/** Alle vom Backend veröffentlichten Entitäten an einer Stelle.
    Kein Hardcoding über die App verstreut: wer eine Entität umbenennt,
    ändert genau diese Tabelle.

    Die Namen sind ein Vertrag mit custom_components/audi_dashboard/const.py;
    das HA-Panel führt dieselbe Tabelle in audi-dashboard-app.js. Bis
    2026-08-23 hießen sie pyscript.audi_dashboard_*, weil pyscript sie
    bereitstellte und die Domain besaß. Seit dem Umbau zur eigenen Integration
    sind es echte Entitäten dieser Integration. */
export const ENTITAETEN = {
  profil: "sensor.audi_dashboard_profil",
  fahrten: "sensor.audi_dashboard_fahrten",
  tankvorgaenge: "sensor.audi_dashboard_tankvorgaenge",
  fahrzeugstatus: "sensor.audi_dashboard_fahrzeugstatus",
  batterieverlauf: "sensor.audi_dashboard_batterieverlauf",
  belegErgebnis: "sensor.audi_dashboard_beleg_ergebnis",
  importStatus: "sensor.audi_dashboard_import_status",
  appVersion: "sensor.audi_dashboard_app_version",
} as const;

export type EntitaetsSchluessel = keyof typeof ENTITAETEN;

/** Die Domain, unter der das Backend seine Dienste anbietet:
    `audi_dashboard.<name>`. Früher `pyscript.audi_dashboard_<name>` - der
    doppelte Präfix war nur nötig, weil sich alle pyscript-Dienste eine Domain
    teilten. Siehe custom_components/audi_dashboard/dienste.py. */
export const DIENST_DOMAIN = "audi_dashboard";
