# Olympus CRM Entwicklungssetup

Dieses Dokument beschreibt das lokale Setup fuer neue Rechner und parallele Entwicklung auf mehreren Macs.

## Setup auf neuem Mac

Voraussetzungen:

- Git
- Docker Desktop
- Node.js passend zu Athena
- Python/uv fuer lokale Hermes-Checks

Repository klonen:

```bash
git clone <repository-url> Olympus
cd Olympus
```

Umgebung anlegen:

```bash
cp .env.example .env
```

Wichtige lokale Werte:

```env
AUTH_COOKIE_SECURE=false
ATHENA_PUBLIC_ORIGIN=http://localhost:3001
STORAGE_PROVIDER=local
STORAGE_BASE_PATH=/data/storage
STORAGE_MAX_UPLOAD_MB=50
STORAGE_HOST_PATH=./storage
OLYMPUS_REPAIR_INTAKE_TOKEN=
```

Wenn `SECRET_KEY` Sonderzeichen wie `$` enthaelt, den Wert in der Shell oder Compose-Umgebung korrekt quoten. Secrets gehoeren nicht ins Git.

## Docker Netzwerk

Das gemeinsame Compose-File nutzt ein externes Docker-Netzwerk:

```bash
docker network create olympus-network
```

Wenn das Netzwerk bereits existiert, meldet Docker das nur als Hinweis.

## Docker Compose Start

```bash
docker compose build
docker compose up -d
```

Hermes ist im gemeinsamen Stack nur intern im Docker-Netzwerk erreichbar. Athena ist lokal ueber den Browser erreichbar:

- Athena: `http://localhost:3001`
- Hermes intern: `http://hermes:8000`

Der Browser spricht nicht direkt mit Hermes.

## Migrationen

Migrationen ausfuehren:

```bash
scripts/migrate.sh
```

Alternativ lokal im Backend:

```bash
cd backend/hermes
uv run alembic upgrade head
```

## Initial Admin

Fuer neue Installationen ohne aktive Benutzer kann Hermes beim Startup einen initialen Admin anlegen.

```env
INITIAL_ADMIN_USERNAME=admin
INITIAL_ADMIN_EMAIL=admin@example.local
INITIAL_ADMIN_PASSWORD=<lokales-passwort>
INITIAL_ADMIN_FIRST_NAME=
INITIAL_ADMIN_LAST_NAME=
```

Diese Werte nur lokal oder sicher auf dem Zielsystem setzen. Nach dem ersten produktiven Login sollte das Passwort geaendert und die Bootstrap-Variablen wieder entfernt werden.

## Login

Nach Start und Migration:

1. Browser auf `http://localhost:3001` oeffnen.
2. Mit dem initialen Admin oder einem bestehenden Benutzer anmelden.
3. Athena setzt das HttpOnly-Cookie. Hermes setzt keine Browser-Cookies.

## Storage

Neue Dateiablagen laufen ueber das Storage Framework.

Lokaler Standard:

```env
STORAGE_HOST_PATH=./storage
STORAGE_BASE_PATH=/data/storage
```

VPS-Empfehlung:

```env
STORAGE_HOST_PATH=/opt/olympus-storage
STORAGE_BASE_PATH=/data/storage
```

Bestehende Knowledge-Dateien aus alten Setups unter `/data/knowledge` werden nicht automatisch verschoben. Vor einer manuellen Migration immer Backup erstellen.

## Knowledge Workflow

Die Wissensdatenbank folgt lokal und produktiv diesem Ablauf:

```text
Hersteller -> Gerät -> Dokument -> Notiz/Reparaturhinweis
```

Hermes legt beim Startup Standard-Hersteller an, wenn sie noch fehlen. Danach koennen Geraete angelegt werden. Dokumentuploads sind erst sinnvoll, wenn Hersteller und Geraet vorhanden sind; Athena blockiert unvollstaendige Uploads direkt im Formular.

## Reparaturmanagement

Das Reparaturmodul ist ab v0.8.0 aktiv.

Lokaler Ablauf:

```bash
cd backend/hermes
SECRET_KEY=local-check uv run alembic upgrade head
```

Athena erreicht Reparaturen ausschliesslich ueber BFF-Routen:

- `/api/repairs`
- `/api/repairs/[id]`
- `/api/repairs/[id]/status`
- `/api/repairs/[id]/history`

Hermes stellt zusaetzlich `POST /public/repair-intake` fuer die spaetere Website-Anbindung bereit. Der Endpunkt ist fuer Server-zu-Server-Kommunikation gedacht und erwartet `X-Olympus-Intake-Token`. Der Token wird ueber `OLYMPUS_REPAIR_INTAKE_TOKEN` gesetzt und darf nicht im Browser verwendet werden.

Vorbereitete Kundenportal-Routen fuer spaeter:

- `/status`
- `/reparatur/status`
- `/portal/login`

## Typische Fehler

Hermes restartet wegen fehlender Migration:

```bash
scripts/migrate.sh
docker compose restart hermes
```

`SECRET_KEY` mit `$` wird falsch interpretiert:

- Wert in `.env` korrekt escapen oder quoten.
- Keine Secrets in Commit oder Logs schreiben.

Docker Container Name Conflict:

```bash
docker compose down
docker ps -a
```

Danach blockierenden Altcontainer gezielt entfernen, wenn er wirklich nicht mehr gebraucht wird.

External network fehlt:

```bash
docker network create olympus-network
```

DB leer oder Admin fehlt:

- `INITIAL_ADMIN_*` Werte setzen.
- `scripts/migrate.sh` ausfuehren.
- `docker compose restart hermes`.

Athena nicht erreichbar:

- `docker compose ps` pruefen.
- Port `3001` auf dem Rechner pruefen.
- `scripts/healthcheck.sh` ausfuehren.

## MacBook und Mac mini parallel

Empfehlung:

- `.env` pro Rechner lokal pflegen und nicht committen.
- `STORAGE_HOST_PATH` pro Rechner bewusst setzen.
- Datenbank- und Storage-Backups nicht ungeprueft zwischen Rechnern ueberschreiben.
- Vor Branch-Wechseln Migrationen pruefen.
- Bei paralleler Arbeit keine Docker-Volumes loeschen, solange ungesicherte Uploads existieren.

## Qualitaetschecks

```bash
python3 -m compileall backend/hermes/app
cd frontend/athena
npm run lint
npx next build --webpack
```

Skripte pruefen:

```bash
bash -n scripts/*.sh
```