# 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 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= PUBLIC_REPAIR_STATUS_BASE_URL= SMTP_HOST= SMTP_PORT=587 SMTP_USERNAME= SMTP_PASSWORD= SMTP_FROM_EMAIL= SMTP_FROM_NAME=Funktechnik Schubert SMTP_USE_TLS=true ``` 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= 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` - `/api/repairs/[id]/public-link` - `/api/repairs/[id]/notifications` - `/api/repairs/[id]/send-status-mail` 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. Ab v0.8.1 zeigt Athena deutsche Statuslabels, waehrend die API-Statuscodes englisch und stabil bleiben. Statuswechsel werden als Timeline mit Benutzer, Datum und Notiz angezeigt. Statuslink-Konzept: - Interne Verwaltung ueber `GET|POST|DELETE /repairs/{id}/public-link`. - RBAC-Permission: `repairs.public_link.manage`. - Tokens sind lang, zufaellig und werden nur gehasht gespeichert. - Der Klartexttoken wird nur einmal bei Erstellung zurueckgegeben. - `PUBLIC_REPAIR_STATUS_BASE_URL` kann auf die Website-Route zeigen, z. B. `https://test.funktechnik-schubert.de/status`. - Oeffentliche Statusdaten kommen spaeter ueber `GET /public/repairs/status/{token}`. - Die Antwort enthaelt keine Kundendaten, keine internen Notizen und keine nicht freigegebenen Diagnosen. Benachrichtigungen: - Vorlagen liegen in `backend/hermes/app/services/repair_notification_service.py`. - `repair_notification_events` dokumentiert jeden Versandversuch. - Beim Statuswechsel wird automatisch eine Statusmail verarbeitet. - Ohne SMTP-Konfiguration bleibt der Statuswechsel erfolgreich; der Versandversuch wird als `skipped` dokumentiert. - SMTP wird ueber `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_FROM_EMAIL`, `SMTP_FROM_NAME` und `SMTP_USE_TLS` konfiguriert. - `SMTP_PASSWORD` gehoert ausschliesslich in die Umgebung und nie ins Git oder in Logs. Vorbereitete Website-/Portal-Routen fuer spaeter: - `/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 ```