# Configuration Reference

Die Anwendung wird über `data/config.json` konfiguriert.

## Gesamtstruktur

```json
{
  "app": {},
  "api": {},
  "admin": {},
  "alerts": {
    "webhooks": [],
    "emails": []
  },
  "machines": []
}
```

## Bereich `app`

Beispiel:

```json
{
  "name": "Getränkeautomat Monitor",
  "timezone": "Europe/Berlin",
  "dashboard_refresh_seconds": 15,
  "default_from_email": "monitor@example.local",
  "base_path": ""
}
```

Felder:

- `name`
  - Anzeigename der Anwendung im Dashboard
- `timezone`
  - Standardzeitzone für die Anwendung
- `dashboard_refresh_seconds`
  - Polling-Intervall für das Dashboard
- `default_from_email`
  - Absenderadresse für `mail()`
- `base_path`
  - optionaler URL-Pfad für Deployments unterhalb der Domain
  - leer lassen für Betrieb direkt unter `/`
  - Beispiel für `domain.de/auswertung/`: `"/auswertung"`
  - führende und abschließende Slashes werden beim Speichern normalisiert

Beispiel für einen Betrieb unter `https://domain.de/auswertung/`:

```json
{
  "name": "Getränkeautomat Monitor",
  "timezone": "Europe/Berlin",
  "dashboard_refresh_seconds": 15,
  "default_from_email": "monitor@example.local",
  "base_path": "/auswertung"
}
```

## Bereich `api`

Beispiel:

```json
{
  "bearer_token": "demo-esp32-token"
}
```

Felder:

- `bearer_token`
  - statisches Token für die Sensor-API
  - wird von Clients im Authorization-Header gesendet

## Bereich `admin`

Beispiel:

```json
{
  "username": "admin",
  "password_hash": "$2y$10$..."
}
```

Felder:

- `username`
  - Admin-Benutzername
- `password_hash`
  - bcrypt-Hash des Passworts
  - wird vom Adminpanel automatisch erzeugt, wenn ein neues Passwort gespeichert wird

## Bereich `alerts.webhooks`

Beispiel:

```json
[
  {
    "id": "lager-webhook",
    "name": "Lager Webhook",
    "url": "https://example.com/hooks/lager",
    "enabled": true,
    "headers": {
      "X-App-Token": "replace-me"
    }
  }
]
```

Felder:

- `id`
  - technische Kennung
  - wird von Slots referenziert
- `name`
  - Anzeigename im Adminpanel
- `url`
  - Zieladresse für den POST-Webhook
- `enabled`
  - aktiviert oder deaktiviert den Versand
- `headers`
  - optionales JSON-Objekt für zusätzliche HTTP-Header

## Bereich `alerts.emails`

Beispiel:

```json
[
  {
    "id": "lager-team",
    "name": "Lager Team",
    "address": "lager@example.com",
    "enabled": true
  }
]
```

Felder:

- `id`
  - technische Kennung
  - wird von Slots referenziert
- `name`
  - Anzeigename im Adminpanel
- `address`
  - Zieladresse für Alarmmails
- `enabled`
  - aktiviert oder deaktiviert den Versand

## Bereich `machines`

Hier werden alle Automaten definiert.

Beispiel:

```json
[
  {
    "id": "automat-lobby",
    "name": "Lobby Automat",
    "location": "Erdgeschoss",
    "slots": []
  }
]
```

Felder:

- `id`
  - eindeutige Kennung des Automaten
- `name`
  - Anzeigename im Dashboard
- `location`
  - optionaler Standorttext
- `slots`
  - Liste der Fächer dieses Automaten

## Bereich `machines[].slots`

Jedes Fach repräsentiert einen Sensor und eine zugeordnete Produktposition.

Beispiel:

```json
{
  "sensor_id": "fach-a1",
  "label": "A1",
  "product_name": "Cola 0,5l",
  "full_distance_mm": 80,
  "empty_distance_mm": 360,
  "distance_per_unit": 40,
  "alert_below_units": 2,
  "webhook_ids": ["lager-webhook"],
  "email_ids": ["lager-team"]
}
```

Felder:

- `sensor_id`
  - eindeutige Kennung des Sensors innerhalb des Automaten
- `label`
  - Kurzlabel für Anzeige und Alarmtexte
- `product_name`
  - Klartextbezeichnung des Produkts
- `full_distance_mm`
  - Sensorwert, der als "voll" gilt
- `empty_distance_mm`
  - Sensorwert, der als "leer" gilt
- `distance_per_unit`
  - Differenz im Messwert pro Flasche oder Einheit
- `alert_below_units`
  - kritische Schwelle
- `webhook_ids`
  - Liste von Webhook-IDs aus `alerts.webhooks`
- `email_ids`
  - Liste von Email-IDs aus `alerts.emails`

## Kalibrierung eines Fachs

Für eine brauchbare Bestandsschätzung sollten pro Fach mindestens diese Werte sauber kalibriert werden:

1. Sensorwert bei vollem Fach messen und als `full_distance_mm` eintragen.
2. Sensorwert bei leerem Fach messen und als `empty_distance_mm` eintragen.
3. Mehrere Messungen zwischen zwei benachbarten Füllständen machen.
4. Die durchschnittliche Differenz pro Flasche als `distance_per_unit` eintragen.
5. Einen passenden Schwellwert für `alert_below_units` festlegen.

## Referenzen zwischen Bereichen

Slots referenzieren Alarmziele nicht direkt über URLs oder Email-Adressen, sondern über IDs:

- `webhook_ids` referenziert `alerts.webhooks[].id`
- `email_ids` referenziert `alerts.emails[].id`

Das macht die Konfiguration wartbarer, weil ein Alarmziel zentral geändert werden kann.

## Tipps für produktive Nutzung

- IDs nur aus stabilen ASCII-Zeichen vergeben
- `machine_id` und `sensor_id` niemals nachträglich leichtfertig ändern
- für jeden neuen Sensor zuerst Kalibrierwerte eintragen
- Testalarme mit einem absichtlich kritischen Messwert prüfen
- Beispiel-Tokens und Default-Zugangsdaten vor dem Live-Betrieb ersetzen