admin.schubert/Olympus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Olympus/README-DEV.md
Schubert Ferenc c58e212e3a feat(repairs): automatic repair status emails
2026-07-04 22:58:47 +02:00

6.5 KiB
Raw Permalink Blame History

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:

git clone <repository-url> Olympus
cd Olympus

Umgebung anlegen:

cp .env.example .env

Wichtige lokale Werte:

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:

docker network create olympus-network

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

Docker Compose Start

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:

scripts/migrate.sh

Alternativ lokal im Backend:

cd backend/hermes
uv run alembic upgrade head

Initial Admin

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

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:

STORAGE_HOST_PATH=./storage
STORAGE_BASE_PATH=/data/storage

VPS-Empfehlung:

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:

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:

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/<token>
  • /portal/login

Typische Fehler

Hermes restartet wegen fehlender Migration:

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:

docker compose down
docker ps -a

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

External network fehlt:

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

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

Skripte pruefen:

bash -n scripts/*.sh