# Olympus CRM Architektur ## Projektueberblick Olympus CRM ist als mehrschichtige CRM-Anwendung aufgebaut. Die Architektur trennt klar zwischen Browser, Frontend/BFF, Backend-API und Datenbank. Die zentrale Regel lautet: **Der Browser kommuniziert ausschliesslich mit Athena. Athena kommuniziert serverseitig mit Hermes. Hermes kommuniziert mit PostgreSQL.** Diese Trennung ist verbindlich, besonders fuer Authentifizierung, API-Zugriffe und spaetere Modul-Erweiterungen wie Kunden, Projekte, Lieferanten, Kontakte und Mitarbeiter. ## Systemkomponenten ### Athena: Next.js 16 Frontend Athena liegt unter `frontend/athena` und ist das Frontend sowie die BFF-Schicht des Systems. Aufgaben: - rendert die Benutzeroberflaeche mit Next.js 16 App Router - stellt eigene API-Routes unter `/api/...` bereit - setzt und loescht das HttpOnly-Auth-Cookie - ruft Hermes serverseitig auf - schuetzt Seiten ueber `proxy.ts` Der Browser darf keine Hermes-URLs direkt aufrufen. ### Hermes: FastAPI Backend Hermes liegt unter `backend/hermes` und stellt die interne Backend-API bereit. Aufgaben: - validiert Requests mit Pydantic v2 - verarbeitet Fachlogik und Persistenz - prueft JWT Bearer Tokens - stellt REST-Endpunkte bereit - nutzt SQLAlchemy 2.x fuer Datenbankzugriffe - setzt keine Browser-Cookies Hermes bleibt Cookie-frei. Authentifizierte Hermes-Endpunkte erwarten `Authorization: Bearer `. ### PostgreSQL Datenbank PostgreSQL ist die relationale Datenbank fuer Olympus CRM. Hermes greift ueber SQLAlchemy darauf zu. Schemaaenderungen erfolgen ueber Alembic-Migrationen. Manuelle Datenbankeingriffe sind nur in Notfaellen zulaessig und muessen nachvollziehbar dokumentiert werden. ### Docker Compose Die gemeinsame Docker-Compose-Konfiguration liegt im Projektroot in `docker-compose.yml`. Sie verbindet: - `hermes` - `athena` - das konfigurierte Docker-Netzwerk - die notwendigen Runtime-Umgebungsvariablen Im gemeinsamen Compose-Stack wird Athena am Host veroeffentlicht. Hermes wird nur intern im Docker-Netzwerk exponiert und von Athena ueber `HERMES_INTERNAL_URL` erreicht. ## BFF-Architektur Olympus nutzt eine Backend-for-Frontend-Architektur. Regeln: - Browser spricht ausschliesslich mit Athena. - Athena spricht serverseitig mit Hermes. - Hermes setzt keine Browser-Cookies. - Cross-Origin-Cookies werden nicht verwendet. - Frontend-API-Zugriffe laufen ueber relative Athena-Routen wie `/api/users`. Der Datenfluss bleibt dadurch kontrolliert, sicher und leichter hinter Reverse Proxies betreibbar. ## Authentifizierungsfluss ### Login 1. Der Browser sendet Benutzername und Passwort an Athena: `POST /api/login`. 2. Athena ruft serverseitig Hermes auf: `POST /auth/login`. 3. Hermes validiert die Zugangsdaten. 4. Hermes gibt JWT, Ablaufzeit und Benutzerdaten als JSON zurueck. 5. Athena setzt das JWT in einem HttpOnly-Cookie. 6. Der Browser wird auf eine geschuetzte Seite weitergeleitet. Hermes setzt kein Cookie. ### Logout 1. Der Browser sendet `POST /api/logout` an Athena. 2. Athena loescht das HttpOnly-Cookie. 3. Der Benutzer wird zur Login-Seite gefuehrt. ### Aktueller Benutzer Athena stellt `GET /api/me` bereit und ruft dafuer serverseitig Hermes `GET /auth/me` auf. Der Header laedt den aktuellen Benutzer ausschliesslich ueber diese BFF-Route und zeigt bevorzugt Vorname plus Nachname, danach den Benutzernamen und vor dem Laden `Benutzer`. Der Browser erhaelt dabei kein Token und ruft Hermes nicht direkt auf. ### HttpOnly Cookie Das Auth-Cookie wird von Athena gesetzt. Eigenschaften: - `HttpOnly` - `SameSite=Lax` - `Path=/` - `Secure` in Produktion - Ablaufzeit orientiert sich an der JWT-Ablaufzeit Tokens duerfen nicht in `localStorage` oder `sessionStorage` gespeichert werden. ### JWT Hermes erzeugt JWT Access Tokens. Wichtige Claims: - `sub`: Benutzername - `exp`: Ablaufzeit - `iat`: Ausstellungszeitpunkt - `iss`: konfigurierter Issuer - `type`: Token-Typ, aktuell `access` ### Issuer Der Issuer wird ueber `JWT_ISSUER` konfiguriert. Hermes prueft den Issuer bei der Token-Validierung. ### Ablaufzeit Die Ablaufzeit wird ueber `ACCESS_TOKEN_EXPIRE_MINUTES` konfiguriert. Athena nutzt die von Hermes gelieferte Ablaufzeit fuer das Cookie. ### `proxy.ts` Athena schuetzt Routen ueber `frontend/athena/proxy.ts`. Aufgaben: - geschuetzte Bereiche ohne Cookie auf `/login` umleiten - eingeloggte Benutzer von `/login` auf `/dashboard` umleiten ## API-Datenfluss Standardfluss: ```text Browser -> Athena /api/... -> Hermes -> PostgreSQL ``` Beispiel Benutzerliste: ```text Browser GET /api/users Athena GET {HERMES_INTERNAL_URL}/users Authorization: Bearer Hermes SQLAlchemy Query gegen PostgreSQL ``` Athena ist die einzige API-Oberflaeche fuer den Browser. ## Dashboard Das Dashboard liegt in Athena unter `/dashboard` und bezieht seine Daten ueber die BFF-Route `GET /api/dashboard/summary`. Hermes stellt dafuer `GET /dashboard/summary` bereit. Der Endpunkt ist mit `dashboard.read` geschuetzt und liefert nur Datenbloecke, fuer die der aktuelle Benutzer weitere Berechtigungen besitzt. Beispiele: - Kundenstatistiken nur mit `customers.read` - Benutzerstatistiken nur mit `users.read` - Rollenstatus nur mit `roles.read` Nicht vorhandene Module wie Aufgaben, Tickets oder Projekte werden nicht mit Fake-Daten gefuellt. Stattdessen liefert das Dashboard leere Widgets mit klarer Meldung. ### Activity Feed Der Activity Feed ist Teil der v0.5.0-Qualitaetsplattform. Athena ruft `GET /api/activity-feed` auf. Die BFF-Route ruft serverseitig Hermes `GET /activity-feed` auf. Der Feed basiert auf persistenten Audit Logs und zeigt die letzten relevanten Aktivitaeten. Hermes filtert die Eintraege anhand der Berechtigungen des aktuellen Benutzers. Ein Benutzer sieht dadurch nur Aktivitaeten zu Bereichen, fuer die er Leserechte besitzt. ## RBAC: Rollen und Berechtigungen Olympus verwendet ein serverseitiges RBAC-System als Grundlage fuer alle CRM-Module. Konzepte: - Benutzer besitzen genau eine primaere Rolle. - Rollen besitzen mehrere Berechtigungen. - Berechtigungen sind stabile String-Keys wie `users.read`. - Hermes prueft Berechtigungen serverseitig ueber Dependencies. - Athena darf Permissions fuer UI-Sichtbarkeit nutzen, aber niemals als Auth-Quelle. Tabellen: - `roles` - `permissions` - `role_permissions` - `users.role_id` Das alte `users.role`-Feld bleibt vorerst als Legacy-Kompatibilitaet erhalten. Neue Logik verwendet `users.role_id` und die `roles`-Beziehung. ### Standardrollen - `administrator` - `management` - `sales` - `technician` - `support` - `warehouse` - `guest` `administrator` erhaelt alle Berechtigungen. `management` erhaelt mindestens Lesezugriff auf Dashboard, Benutzer, Kunden, Projekte und Tickets. `guest` erhaelt minimal `dashboard.read`. ### Standardberechtigungen Benutzer: - `users.read` - `users.create` - `users.update` - `users.delete` - `users.password.update` Rollen: - `roles.read` - `roles.create` - `roles.update` - `roles.delete` - `roles.assign` Kunden: - `customers.read` - `customers.create` - `customers.update` - `customers.delete` Knowledge: - `knowledge.read` - `knowledge.create` - `knowledge.update` - `knowledge.delete` - `knowledge.upload` - `knowledge.download` ### Initial Admin Bootstrap Hermes prueft beim Startup nach dem RBAC-Seed, ob mindestens ein aktiver Benutzer existiert. Existiert ein aktiver Benutzer, wird kein Benutzer automatisch erstellt. Existiert kein aktiver Benutzer, kann Hermes ueber optionale Umgebungsvariablen einen initialen Administrator anlegen: - `INITIAL_ADMIN_USERNAME` - `INITIAL_ADMIN_EMAIL` - `INITIAL_ADMIN_PASSWORD` - `INITIAL_ADMIN_FIRST_NAME` - `INITIAL_ADMIN_LAST_NAME` Benutzername, E-Mail und Passwort sind fuer die automatische Anlage erforderlich. Fehlen Werte oder ist die E-Mail ungueltig, startet Hermes weiter und schreibt nur eine Warnung ohne Secrets. Das Passwort wird mit der bestehenden `hash_password`-Funktion gehasht. Der Benutzer erhaelt `role_id` der Systemrolle `administrator` und das Legacy-Feld `role=administrator`. ### Kundenimport Hermes stellt fuer CSV-Importe zwei Endpunkte bereit: - `POST /customers/import/preview` - `POST /customers/import/commit` Athena stellt die Browser-BFF-Routen bereit: - `POST /api/customers/import/preview` - `POST /api/customers/import/commit` - `GET /api/customers/import/template` Der Browser sendet Multipart-FormData nur an Athena. Athena leitet die Datei serverseitig mit Bearer Token aus dem HttpOnly-Cookie an Hermes weiter. Hermes begrenzt CSV-Dateien auf 5 MB, bevorzugt UTF-8, erkennt Semikolon und Komma und ignoriert leere Zeilen. Importmodi: - `create_only`: neue Kunden erstellen, bestehende Kundennummern ueberspringen - `update_existing`: bestehende Kunden anhand der Kundennummer aktualisieren - `upsert`: bestehende Kunden aktualisieren und neue Kunden erstellen RBAC: - Preview benoetigt `customers.read` - Commit mit `create_only` benoetigt `customers.create` - Commit mit `update_existing` benoetigt `customers.update` - Commit mit `upsert` benoetigt `customers.create` und `customers.update` CSV-Spalten: ```text customer_number;company_name;legal_name;customer_type;status;industry;website;email;phone;tax_number;vat_id;notes;address_type;street;postal_code;city;state;country;address_is_primary;contact_first_name;contact_last_name;contact_position;contact_email;contact_phone;contact_mobile;contact_is_primary;contact_notes ``` Pflichtfeld ist `company_name`. Wenn `customer_number`, `customer_type` oder `status` fehlen, erzeugt der Import fuer neue Kunden eine Kundennummer bzw. nutzt produktive Defaults und weist in der Preview darauf hin. Vollstaendige CSV-Inhalte werden nicht im Audit Log gespeichert. Projekte: - `projects.read` - `projects.create` - `projects.update` - `projects.delete` Tickets: - `tickets.read` - `tickets.create` - `tickets.update` - `tickets.delete` Dashboard und System: - `dashboard.read` - `system.settings.read` - `system.settings.update` Audit: - `audit_logs.read` ### Berechtigungspruefung Zentrale Hermes-Dependencies: - `get_current_user` - `get_current_active_user` - `require_permission("permission.name")` - `require_any_permission([...])` - `require_all_permissions([...])` Backend-Endpunkte muessen immer selbst pruefen. Frontend-Helfer wie `hasPermission` dienen nur dazu, Buttons oder Navigation auszublenden. ### Rollen-API Hermes: - `GET /roles` - `GET /roles/{id}` - `POST /roles` - `PUT /roles/{id}` - `DELETE /roles/{id}` - `PUT /roles/{id}/permissions` - `GET /permissions` Athena stellt entsprechende BFF-Routen unter `/api/roles`, `/api/permissions` und `/api/me` bereit. ## Benutzerverwaltung Die Benutzerverwaltung ist das erste Enterprise-Modul und dient als Vorlage fuer weitere Module. Funktionen: - Benutzerliste - Detailseite - Erstellen - Bearbeiten - Loeschen - Passwort separat aendern - Suche, Filter, Sortierung und Pagination im Frontend Backend-Endpunkte in Hermes: - `GET /users` - `GET /users/{id}` - `POST /users` - `PUT /users/{id}` - `PUT /users/{id}/password` - `DELETE /users/{id}` Athena stellt die passenden BFF-Routen unter `/api/users` und `/api/users/[id]` bereit. Diese Endpunkte sind per RBAC geschuetzt: - `GET /users` und `GET /users/{id}`: `users.read` - `POST /users`: `users.create` und fuer Rollenzuweisung `roles.assign` - `PUT /users/{id}`: `users.update`; Rollenwechsel benoetigt `roles.assign` - `PUT /users/{id}/password`: `users.password.update` - `DELETE /users/{id}`: `users.delete` ### Passwortaenderung Wenn beim Bearbeiten kein Passwort uebergeben wird, bleibt das bestehende Passwort unveraendert. Wenn ein Passwort gesetzt wird, wird es in Hermes mit `pwdlib` neu gehasht. ### Self-Delete-Schutz Der aktuell angemeldete Benutzer darf sich nicht selbst loeschen. Hermes verhindert dies serverseitig. ### Rollenmodell Benutzer besitzen eine primaere RBAC-Rolle ueber `role_id`. Die Rolle bestimmt die serverseitigen Berechtigungen. ## Kundenmodul Das Kundenmodul ist das zweite Enterprise-Modul und folgt den gleichen Grundsaetzen wie die Benutzerverwaltung: - Hermes stellt REST-Endpunkte bereit. - Athena proxyt diese Endpunkte ueber `/api/customers`. - Der Browser spricht nicht direkt mit Hermes. - Berechtigungen werden serverseitig in Hermes geprueft. - Die UI nutzt Permissions nur fuer Sichtbarkeit und Bedienkomfort. Hermes-Endpunkte: - `GET /customers` - `GET /customers/{id}` - `POST /customers` - `PUT /customers/{id}` - `DELETE /customers/{id}` - `GET /customers/{id}/contacts` - `POST /customers/{id}/contacts` - `PUT /customers/{id}/contacts/{contact_id}` - `DELETE /customers/{id}/contacts/{contact_id}` Athena-BFF-Routen: - `GET /api/customers` - `POST /api/customers` - `GET /api/customers/[id]` - `PUT /api/customers/[id]` - `DELETE /api/customers/[id]` - `GET /api/customers/[id]/contacts` - `POST /api/customers/[id]/contacts` - `PUT /api/customers/[id]/contacts/[contactId]` - `DELETE /api/customers/[id]/contacts/[contactId]` Tabellen: - `customers` - `customer_addresses` - `customer_contacts` Kunden-Permissions: - `customers.read` - `customers.create` - `customers.update` - `customers.delete` Kontakte und Adressen gehoeren fachlich zum Kunden und werden aktuell ueber `customers.read` beziehungsweise `customers.update` gesteuert. Ein Kunden-Delete entfernt aktuell den Kunden inklusive Adressen und Ansprechpartnern. Fuer spaetere Projekte oder Tickets ist ein fachlicher Loeschschutz vorzubereiten, sobald diese Module existieren. ## Audit Logs Audit Logs sind die zentrale Nachvollziehbarkeitsschicht fuer v0.5.0. Hermes persistiert relevante Ereignisse in der Tabelle `audit_logs`. Erfasste Informationen: - handelnder Benutzer - Aktion, z. B. `users.update` oder `customers.delete` - Objekttyp und Objekt-ID - lesbares Objektlabel - IP-Adresse und User-Agent - Vorher-/Nachher-Daten fuer Aenderungen - Metadaten fuer Kontextinformationen - Erstellungszeitpunkt Sensible Felder wie Passwoerter, Tokens und Secrets werden vor dem Schreiben maskiert. Audit Logs werden aktuell fuer diese Bereiche geschrieben: - Login erfolgreich/fehlgeschlagen - Benutzer erstellen, bearbeiten, loeschen, Passwort aendern - Rollen erstellen, bearbeiten, loeschen, Berechtigungen aendern - Kunden erstellen, bearbeiten, loeschen - Ansprechpartner erstellen, bearbeiten, loeschen Hermes-Endpunkte: - `GET /audit-logs` - `GET /activity-feed` Athena-BFF-Routen: - `GET /api/audit-logs` - `GET /api/activity-feed` Die Audit-Log-UI liegt unter `frontend/athena/app/audit-logs` und ist ueber `audit_logs.read` sichtbar. ## API-Response-Standard Neue Plattform-Endpunkte verwenden eine einheitliche Response-Huelle: ```json { "success": true, "data": {}, "message": "Daten geladen" } ``` Fehlerantworten aus Hermes verwenden ein konsistentes Format mit `success`, `message`, `error_code` und `details`. Fuer bestehende Athena-Fehlerbehandlung bleibt `detail` zusaetzlich erhalten. ## Logging Hermes konfiguriert Logging zentral ueber `backend/hermes/app/core/logging.py`. HTTP-Requests werden strukturiert mit Methode, Pfad, Statuscode und Dauer geloggt. Fachliche Ereignisse bleiben in den API-Modulen als strukturierte Logeintraege erhalten. Das Runtime-Loglevel wird ueber `LOG_LEVEL` gesteuert. ## Frontend-Feedback Athena nutzt einen globalen Toast-Provider fuer konsistente Erfolgs- und Fehlermeldungen. Aktuell werden Toasts in den CRUD-Flows fuer Benutzer, Rollen, Kunden und Ansprechpartner genutzt. Inline-Fehler bleiben dort erhalten, wo sie fuer Formulare und Dialoge hilfreich sind. ## Wissensdatenbank / Service Library v0.6.0 fuehrt das Modul Wissensdatenbank ein. Es verwaltet Hersteller, Geraete und Modelle, Dokumente sowie Reparaturhinweise fuer Funktechnik, Elektronikreparatur und Werkstattbetrieb. Hermes stellt dafuer Tabellen mit dem Prefix `knowledge_` bereit: - `knowledge_manufacturers` - `knowledge_devices` - `knowledge_documents` - `knowledge_notes` - `knowledge_categories` Athena stellt die BFF-Routen unter `/api/knowledge/...` bereit. Der Browser spricht weiterhin ausschliesslich mit Athena. ### Knowledge-Workflow Seit v0.7.1 fuehrt die UI Benutzer explizit durch den fachlichen Ablauf: ```text Hersteller -> Gerät -> Dokument -> Notiz/Reparaturhinweis ``` Dokumente wie Schaltplaene, Service Manuals oder Abgleichanleitungen werden immer einem konkreten Geraet zugeordnet. Der Upload wird in Athena deaktiviert, solange Hersteller oder Geraet fehlen. Empty States erklaeren, was fehlt, und bieten die naechste sinnvolle Aktion an. Upload-Voraussetzungen: - Hersteller ist Pflicht. - Geraet ist Pflicht. - Dokumenttyp ist Pflicht. - Datei ist Pflicht bei neuen Uploads. - Das Geraet muss zum ausgewaehlten Hersteller gehoeren. Hermes validiert diese Regeln serverseitig und liefert Benutzerfehler mit klaren Meldungen statt 500er-Antworten. ### Standard-Hersteller-Seeding Hermes legt beim Startup idempotent Standard-Hersteller an, sofern sie noch nicht existieren: - Stabo - President - Albrecht - Marconi - Rohde & Schwarz - HP - CRT - Alinco - Motorola - Team Das Seeding ueberschreibt bestehende Hersteller nicht. Fehlende Slugs werden ergaenzt. Websites und Notizen bleiben leer, solange keine sicheren Stammdaten gepflegt sind. ### Empty States Athena verwendet fuer Knowledge-Listen die zentrale Komponente `EmptyState`. Sie wird eingesetzt fuer: - leere Herstellerliste - leere Geraeteliste - leere Dokumentliste - leere Notizliste - Suche oder Filter ohne Treffer Jeder Empty State erklaert kurz den fehlenden Zustand und bietet eine passende Aktion an. ### Knowledge-Dateispeicherung Seit v0.7.0 laufen Knowledge-Dateien ueber das zentrale Storage Framework. KnowledgeService speichert, liest und loescht Dateien nicht mehr direkt ueber verstreute Dateioperationen, sondern ueber `StorageService`. Neue Uploads werden im Namespace `knowledge/documents/` gespeichert. Die Datenbank-Metadaten bleiben kompatibel: `knowledge_documents.file_path` enthaelt den Storage-Key fuer neue Dateien oder einen bestehenden Legacy-Pfad fuer alte Dateien. Konfiguration: - `STORAGE_PROVIDER`, Default `local` - `STORAGE_BASE_PATH`, Default `/data/storage` - `STORAGE_MAX_UPLOAD_MB`, Default `50` - `KNOWLEDGE_STORAGE_PATH`, Legacy-Fallback fuer bestehende Installationen - `KNOWLEDGE_MAX_UPLOAD_MB`, Legacy-Fallback fuer bestehende Installationen Docker Compose bindet den Host-Pfad aus `STORAGE_HOST_PATH` nach `/data/storage` ein. Fuer den VPS ist `/opt/olympus-storage` empfohlen. Bestehende Dateien unter `/data/knowledge` werden nicht automatisch verschoben; wenn Migration noetig ist, muss sie kontrolliert geplant und vorher gebackupt werden. Erlaubte Uploadtypen: - PDF - JPG/JPEG - PNG - WEBP - TXT - ZIP Hermes normalisiert Dateinamen, erzeugt eindeutige gespeicherte Dateinamen, validiert Extension und MIME-Type, begrenzt die Uploadgroesse, berechnet SHA256 und verhindert Path Traversal. ## Storage Framework Das Storage Framework liegt unter `backend/hermes/app/storage`. Bestandteile: - `StorageProvider` als Interface - `LocalDiskStorageProvider` als erste Implementierung - `StorageService` als zentrale API fuer Fachmodule - Storage-Schemas und eigene Storage-Exceptions Zentrale Operationen: - `save_file()` - `open_file()` - `delete_file()` - `file_exists()` - `get_file_metadata()` - `calculate_checksum()` - `safe_filename()` - `validate_file_type()` - `validate_file_size()` Der aktuelle Provider ist `local`. Die Architektur ist bewusst fuer spaetere Provider vorbereitet: - NAS - S3 - MinIO - Paperless - Azure Blob - Backblaze / Wasabi Pfadstruktur im lokalen Provider: ```text /data/storage/ knowledge/ documents/ thumbnails/ customers/ projects/ tickets/ imports/ temp/ ``` Datei-Inhalte werden nicht geloggt. Browser greifen nie direkt auf Storage oder Hermes-Dateipfade zu; Downloads laufen ueber Athena-BFF und Hermes-Berechtigungspruefung. ## Backup und Deployment Im Projektroot liegen robuste Bash-Skripte fuer Betrieb und Deployment: - `scripts/migrate.sh` - `scripts/healthcheck.sh` - `scripts/deploy.sh` - `scripts/backup.sh` - `scripts/restore.sh` `deploy.sh` baut Images, startet Docker Compose, fuehrt Migrationen aus und startet den Healthcheck. Es erzwingt kein `git pull`. `backup.sh` sichert PostgreSQL, wenn `POSTGRES_CONTAINER` oder `DATABASE_URL` mit lokalem `pg_dump` verfuegbar ist, und archiviert den Storage-Host-Pfad. `.env` wird bewusst nicht automatisch ins Backup kopiert und muss sicher separat verwaltet werden. `restore.sh` ist bewusst bestaetigungspflichtig und startet erst nach Eingabe von `RESTORE`. ### Knowledge-RBAC Neue Berechtigungen: - `knowledge.read` - `knowledge.create` - `knowledge.update` - `knowledge.delete` - `knowledge.upload` - `knowledge.download` Standardrollen: - `administrator`: alle Knowledge-Rechte - `management`: `knowledge.read`, `knowledge.download` - `technician`: `knowledge.read`, `knowledge.create`, `knowledge.update`, `knowledge.upload`, `knowledge.download` - `support`: `knowledge.read`, `knowledge.download` - `guest`: keine Knowledge-Rechte Hermes erzwingt diese Rechte serverseitig. Athena nutzt sie nur fuer Navigation und UI. ### Paperless-Vorbereitung Eine echte Paperless-ngx-Integration ist in v0.6.0 nicht aktiv. Dokumente enthalten bereits `paperless_document_id` und `external_url`, damit spaeter ein PaperlessConnector angebunden werden kann. API-Keys oder verpflichtende Paperless-Umgebungsvariablen werden in v0.6.0 nicht eingefuehrt. Spaetere Verknuepfungen sind fuer Kunden, Projekte, Tickets und Reparaturen vorgesehen. ## Verzeichnisstruktur ```text backend/hermes app/ api/ audit/ core/ db/ models/ repositories/ schemas/ alembic/ alembic.ini dockerfile pyproject.toml frontend/athena app/ api/ audit-logs/ customers/ roles/ users/ components/ lib/ types/ proxy.ts Dockerfile package.json docker-compose.yml ``` ## Umgebungsvariablen ### Hermes `DATABASE_URL` : PostgreSQL-Verbindungsstring. `SECRET_KEY` : Signierschluessel fuer JWTs. Muss geheim bleiben. `JWT_ISSUER` : Erwarteter JWT-Issuer, z. B. `hermes`. `ACCESS_TOKEN_EXPIRE_MINUTES` : Ablaufzeit fuer Access Tokens in Minuten. `LOG_LEVEL` : Runtime-Loglevel fuer Hermes, z. B. `INFO`, `WARNING` oder `ERROR`. `STORAGE_PROVIDER` : Storage Provider. Aktuell produktiv implementiert: `local`. `STORAGE_BASE_PATH` : Interner Storage-Basispfad in Hermes. Default `/data/storage`. `STORAGE_MAX_UPLOAD_MB` : Maximale Uploadgroesse fuer Storage-Dateien in MB. Default `50`. `STORAGE_HOST_PATH` : Docker-Host-Pfad, der nach `/data/storage` gemountet wird. Lokal z. B. `./storage`, auf dem VPS empfohlen `/opt/olympus-storage`. `KNOWLEDGE_STORAGE_PATH` : Legacy-Fallback fuer bestehende Knowledge-Dateien. Neue Installationen sollen `STORAGE_*` verwenden. `KNOWLEDGE_MAX_UPLOAD_MB` : Legacy-Fallback fuer die maximale Knowledge-Uploadgroesse. ### Athena `HERMES_INTERNAL_URL` : Serverseitige URL, ueber die Athena Hermes erreicht. `AUTH_COOKIE_SECURE` : Steuert das `Secure`-Flag des Cookies. In Produktion `true`. ## Datenbankmigrationen Olympus verwendet Alembic fuer Datenbankmigrationen. Regeln: - Schemaaenderungen immer ueber Alembic. - Migrationen muessen ins Repository aufgenommen werden. - Vor Deployment `alembic upgrade head` testen. - Keine manuellen DB-Aenderungen ausser in Notfaellen. Typischer Ablauf: ```bash cd backend/hermes alembic upgrade head ``` ## Sicherheitsprinzipien Verbindliche Regeln: - Keine Tokens im `localStorage`. - Keine Tokens im `sessionStorage`. - Keine Browserzugriffe auf Hermes. - Keine Cross-Origin-Cookies. - Hermes bleibt Cookie-frei. - Athena setzt HttpOnly Cookies. - Mutierende Athena-API-Routes pruefen Same-Origin. - Hermes prueft JWTs serverseitig. - Hermes prueft RBAC-Berechtigungen serverseitig. - Secrets gehoeren in Umgebungsvariablen, nicht in den Code. ## Produktionshinweise Fuer Produktion gilt: - HTTPS ist erforderlich. - `AUTH_COOKIE_SECURE=true` setzen. - Reverse Proxy ist moeglich und soll Forwarded Header korrekt setzen. - `HERMES_INTERNAL_URL` muss serverseitig erreichbar sein. - `SECRET_KEY` muss stark, geheim und stabil sein. - Datenbankmigrationen vor App-Rollout ausfuehren. Lokaler HTTP-Betrieb ist nur fuer Entwicklung gedacht. In Produktion duerfen keine unsicheren Cookie-Einstellungen verwendet werden.