# Getting Started

Diese Anleitung bringt eine lokale Entwicklungsumgebung fuer das Boilerplate zum
Laufen. Sie setzt voraus, dass MySQL 8 und ein OIDC Provider bereits verfuegbar
sind.

## Voraussetzungen

- Node.js `24.18.0` aus `.nvmrc`
- npm `11.x`
- Docker fuer Image-Builds und spaetere Auslieferung
- MySQL 8 mit `utf8mb4`
- OIDC Client mit Authorization Code Flow, PKCE und Discovery Endpoint

Das Repository ist ein npm-Workspace-Monorepo. Abhaengigkeiten werden immer aus
dem Root installiert.

```bash
npm ci
cp .env.example .env
```

## Lokale Konfiguration

Trage in `.env` mindestens folgende Werte ein:

- `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME`, `DATABASE_USER`, `DATABASE_PASSWORD`
- `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`
- `SESSION_SECRET` mit mindestens 32 zufaelligen Zeichen
- `SESSION_ENCRYPTION_KEY` mit mindestens 32 zufaelligen Zeichen
- `APP_BASE_URL=http://localhost:3000`
- `FRONTEND_BASE_URL=http://localhost:4200`
- `CORS_ORIGINS=http://localhost:4200,http://localhost:3000`

Der OIDC Provider muss als Redirect URI diese URL erlauben:

```text
http://localhost:3000/api/auth/callback
```

Falls der Provider RP-Initiated Logout validiert, muss ausserdem
`http://localhost:4200` beziehungsweise die konfigurierte `FRONTEND_BASE_URL` als
Post-Logout-Redirect erlaubt sein. Wenn Discovery keinen `end_session_endpoint`
liefert, setze `OIDC_LOGOUT_URL`.

## Datenbank vorbereiten

Die Anwendung fuehrt Migrationen beim normalen Start nicht automatisch aus.
Fuehre sie bewusst aus:

```bash
npm run migration:status
npm run migration:run
```

Wenn Migrationen fehlen, verweigert das Backend den Start beziehungsweise
`/health/ready` bleibt nicht bereit.

## Entwicklung starten

```bash
npm run dev
```

Das startet:

- Frontend: `http://localhost:4200`
- Backend: `http://localhost:3000`
- API: `http://localhost:3000/api`
- Health: `http://localhost:3000/health/live` und `/health/ready`
- Swagger, falls `SWAGGER_ENABLED=true`: `http://localhost:3000/api/docs`

Das Frontend proxyt `/api` ueber `apps/frontend/proxy.conf.json` an das Backend.
Dadurch kann lokal mit Cookie-basierter Authentifizierung gearbeitet werden.

## Erster Login

1. Oeffne `http://localhost:4200`.
2. Melde dich ueber den OIDC Provider an.
3. Der erste lokal angelegte Benutzer erhaelt automatisch die Rollen `user` und
   `admin`.
4. Weitere Benutzer erhalten initial die Rolle `user`.

Systemrollen und Permissions werden beim Login synchronisiert. Permissions sind
im Code definiert und werden nicht frei in der UI angelegt.

## Haefige Probleme

- `Ungueltige Konfiguration`: `.env` verletzt das Schema in `apps/backend/src/config/env.ts`.
- `MIGRATION_MISSING`: `npm run migration:run` ausfuehren.
- `UNAUTHORIZED`: Session abgelaufen, Benutzer deaktiviert oder OIDC-Konfiguration falsch.
- `CSRF_INVALID`: Schreibender Request ohne `X-CSRF-Token`; im Angular-Client erledigt das der Interceptor.
- OIDC Callback schlaegt fehl: Redirect URI, Issuer, Client Secret und erlaubte Algorithmen pruefen.