# Debugging-Guide

## Zweck
Schnelle Diagnose: "Wenn X passiert, pruefe Y" getrennt nach Simulation und Hardware.

## Voraussetzungen
- Box laeuft (Simulation oder Hardware)
- Zugriff auf `/status` und Datenfiles

## Schritt-fuer-Schritt
Nutze die Sektionen nach Symptomen.

## Simulation (IDE)
### GUI zeigt "Failed to fetch"
- API pruefen:
```
curl http://127.0.0.1:5001/api/boxes
```
- GUI API-Base pruefen:
  - GUI nutzt `/api/...` und Vite-Proxy.
  - `VITE_BACKEND_URL` zeigt auf das Backend (ohne `/api`).
  - Reverse-Proxy: `/api` muss auf Port 5001 zeigen (ohne doppeltes `/api`).

### Playback startet nicht
- Tags pruefen:
```
cat box/data/box.json
```
- Medienkatalog pruefen:
```
ls -la gui/backend/media
```
- Status pruefen:
```
curl http://127.0.0.1:8000/status
```
- Tag lokal vorhanden, aber nicht in DB:
  - GUI: "Tags nur auf dieser Box" pruefen.
  - Import ueber "Auf Server uebertragen".

### Resume bleibt leer
- State pruefen:
```
cat box/data/state.json
```
- Playback mit `nfc_off` beenden.

### Setup UI nicht erreichbar
- Port 9000 frei?
- Box laeuft?

### Box wird nicht erkannt (Backend)
- Server-URL in `box/data/box.json` pruefen (`server_url`).
- Backend laeuft auf Port 5001?
- `gui/backend/db/klangkiste.sqlite` pruefen.

### Box erscheint mehrfach
- `box_id` in `box/data/box.json` pruefen.
- Factory-Reset nur gezielt ausfuehren.

### Fingerprint aendert sich
- `secret_seed` in `box/data/secrets.enc` darf sich nicht aendern.
- `box/data/box.json` darf nicht geloescht werden.

### Pairing haengt
- `gui/backend/db/klangkiste.sqlite` pruefen: state, api_token.
- Box-Status: `pairing_state` in `/status` pruefen.

## Reale Box (Hardware)
### Box nicht im Browser erreichbar
- Stromversorgung ok?
- Im gleichen Netzwerk?
- Router-IP pruefen.

### NFC reagiert nicht
- UID in `box.json` vorhanden?
- NFC-Hardware (nicht implementiert) pruefen.

### Audio bleibt stumm
- Audio-Backend ist Mock im aktuellen Code.
- Nicht testbar mit aktuellem Code.

### Box wird nicht erkannt / erscheint mehrfach / Fingerprint wechselt / Pairing haengt
- Frontend-GUI (`http://127.0.0.1:5174`) pruefen.
- Box-IP/Server-IP/VLAN pruefen.
- Box-Logs pruefen.

## Files
- `box/data/box.json`: Identitaet, Tags, Settings
- `box/data/state.json`: Resume und WiFi-State
- `box/data/secrets.enc`: verschluesselte Secrets

## Statusfelder
- `wifi_state`, `ip_address`, `connected_ssid`
- `playback_state.state`, `playback_state.active_uid`
- `playback_state.position`, `playback_state.file_index`
- `playback_state.last_error`

## Troubleshooting
- 400 von `/command`:
  - Payload pruefen (Pflichtfelder).
- Keine Aenderung nach Command:
  - `/status` danach erneut abrufen.