# Entwicklungsumgebung

## Voraussetzungen

| Werkzeug | Version | Zweck |
| --- | --- | --- |
| Go | 1.26+ | Backend, Agents, Migrationen |
| Node.js | 22+ | Weboberfläche |
| Docker | aktuell | lokale PostgreSQL-Instanz |

## Erstes Aufsetzen

```bash
make dev-env     # erzeugt .env mit zufälligem Datenbankpasswort
make dev-up      # startet PostgreSQL im Container
make migrate-up  # legt das Datenbankschema an
```

`make dev-env` erzeugt das Passwort lokal per `openssl rand`. Die entstehende `.env` ist von der Versionsverwaltung ausgeschlossen und erhält die Berechtigung `600`. Eine bestehende `.env` wird nie überschrieben.

## Täglicher Ablauf

```bash
make run-api     # API auf 127.0.0.1:8080
make web-dev     # Oberfläche auf 127.0.0.1:5173
make check       # alle Prüfungen wie in der CI
```

Der Entwicklungsserver der Oberfläche reicht `/api` und `/health` an den Go-Dienst weiter. Dadurch ist der Ursprung identisch und es wird lokal kein CORS benötigt.

## Konfiguration

Alle Einstellungen kommen aus Umgebungsvariablen mit dem Präfix `SYNCOVA_`. Die vollständige Liste steht in `.env.example`.

Zwei Eigenschaften sind bewusst so gestaltet:

- **Secrets haben keinen Standardwert.** Fehlt `SYNCOVA_DB_PASSWORD`, startet kein Dienst. Ein Standardpasswort wäre eine stillschweigend unsichere Konfiguration.
- **Alle Fehler werden gesammelt gemeldet.** Ein Start mit unvollständiger Konfiguration nennt sämtliche fehlenden Variablen auf einmal statt eine nach der anderen.

## Migrationen

```bash
make migrate-status   # aktueller Stand
make migrate-up       # alle ausstehenden Migrationen anwenden
make migrate-down     # genau eine Migration zurücknehmen
```

Regeln:

- Migrationen laufen **nie** automatisch beim Start eines Dienstes. Der API-Dienst prüft beim Start lediglich, ob das Schema zu seiner Programmversion passt, und verweigert andernfalls den Start.
- `down` nimmt immer nur **einen** Schritt zurück. Ein versehentlicher Rücklauf auf Version 0 würde die gesamte Control Plane löschen.
- In der Produktion verlangt `down` zusätzlich `SYNCOVA_MIGRATE_CONFIRM_DOWN=yes`.
- Migrationen sind in das Binary eingebettet. Eine Installation bringt damit immer genau die Migrationen mit, die zu ihrer Version gehören.

Eine neue Migration anlegen:

```bash
# Nummer fortlaufend erhöhen, beide Richtungen anlegen
touch migrations/000002_users.up.sql migrations/000002_users.down.sql
```

## Tests

```bash
make test           # Go-Tests mit Race-Detector
make test-coverage  # zusätzlich Coverage-Bericht
make web-test       # Frontend-Tests
```

Der Race-Detector ist Standard, nicht optional: die Backup Engine wird stark nebenläufig arbeiten, und eine Datenrace-Warnung ist dort ein potenzieller Integritätsfehler.

## Codekonventionen

**Go**

- Kommentare an allen exportierten Deklarationen; sprechende Bezeichner statt Kürzel.
- Fehler werden klassifiziert und mit Kontext weitergereicht, nie verschluckt.
- Interne Fehlerursachen gehören ins Log, niemals in eine API-Antwort.
- Verbindungszeichenketten werden ausschließlich in redigierter Form ausgegeben (`RedactedConnectionString`).

**TypeScript**

- `strict` samt `noUncheckedIndexedAccess` und `exactOptionalPropertyTypes`.
- Jede API-Antwort läuft über `requestApi`; Fehler kommen dort immer als `ApiError` an.
- Es werden nie Platzhalterwerte angezeigt. Solange kein echtes Ergebnis vorliegt, zeigt die Oberfläche „lädt“ oder eine Fehlermeldung.

## Fehlersuche

**Der API-Dienst startet nicht und meldet einen Schemastand**

Das Datenbankschema passt nicht zur Programmversion. `make migrate-status` zeigt den Stand, `make migrate-up` behebt es.

**`make dev-up` meldet einen fehlenden Docker-Daemon**

Docker Desktop starten und erneut versuchen.

**Ein Request lässt sich im Log nicht wiederfinden**

Jede Antwort trägt `X-Request-ID` und `X-Correlation-ID` im Header sowie `meta.request_id` im Body. Die Correlation ID steht in jeder zugehörigen Logzeile.