admin.schubert/Olympus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Olympus/CONTRIBUTING.md

12 KiB
Raw Blame History

Mitwirken an Olympus CRM

Dieses Dokument beschreibt verbindliche Entwicklungsregeln fuer Olympus CRM.

Ziel ist ein stabiler, nachvollziehbarer und produktionsfaehiger Entwicklungsprozess. Keine Quickfixes, keine Workarounds, keine Architektur-Abkuerzungen.

Branching-Modell

main bleibt immer lauffaehig.

Neue Arbeit erfolgt in eigenen Branches:

  • Features: feature/<name>
  • Bugfixes: fix/<name>
  • Dokumentation: docs/<name>

Beispiele:

feature/users-detail-page
feature/customer-module
fix/auth-cookie-localhost
docs/architecture

Direkte Commits auf main sind zu vermeiden.

Commit-Konventionen

Olympus verwendet Conventional Commits.

Format:

type(scope): kurze beschreibung

Beispiele:

feat(auth): add bff login route
feat(users): implement user detail page
fix(auth): accept forwarded origin behind proxy
docs: add architecture documentation
refactor(users): extract reusable data table

Zulaessige Typen:

  • feat: neue Funktion
  • fix: Fehlerbehebung
  • docs: Dokumentation
  • refactor: interne Umstrukturierung ohne Verhaltensaenderung
  • test: Tests
  • chore: Wartung, Build, Tooling

Commits sollen klein, fachlich zusammenhaengend und reviewbar sein.

Definition of Done

Eine Aenderung gilt erst als fertig, wenn diese Punkte erfuellt sind:

  • npm run lint erfolgreich in frontend/athena
  • npx next build --webpack erfolgreich in frontend/athena
  • python3 -m compileall backend/hermes/app erfolgreich im Projektroot
  • Alembic-Migrationen geprueft, falls Datenbankschema betroffen ist
  • uv run alembic history erfolgreich in backend/hermes
  • uv run alembic upgrade head erfolgreich in backend/hermes, wenn Migrationen betroffen sind
  • Docker Compose startet
  • keine .env im Git
  • keine node_modules im Git
  • keine .next im Git
  • keine .venv im Git
  • keine toten Imports
  • keine ungenutzten Dateien
  • keine Debug-Ausgaben oder Browser-Dialoge im Anwendungscode

Standard-Checks:

cd frontend/athena
npm run lint
npx next build --webpack

python3 -m compileall backend/hermes/app

cd backend/hermes
uv run alembic history
uv run alembic upgrade head

Coding Standards

Frontend

  • TypeScript strikt verwenden.
  • Next.js 16 App Router Konventionen einhalten.
  • Browser-API-Zugriffe nur ueber Athena /api/....
  • Wiederverwendbare Komponenten bevorzugen.
  • UI-Zustaende immer abbilden: Loading, Error, Empty State.
  • Erfolg und Fehler in mutierenden CRUD-Flows ueber den Toast-Provider melden.
  • Keine nativen Browser-Dialoge fuer produktive UI-Flows.
  • Keine Tokens in Browser-JavaScript speichern.
  • Datei-Uploads vom Browser laufen ueber Athena-BFF-Routen und werden serverseitig an Hermes weitergeleitet.

Backend

  • FastAPI sauber nach API, Schema, Repository und Core trennen.
  • SQLAlchemy 2.x Patterns verwenden.
  • Pydantic v2 fuer Request- und Response-Modelle verwenden.
  • HTTP-Fehler bewusst mit passenden Statuscodes ausgeben.
  • Fachliche Konflikte als 409 Conflict.
  • Nicht gefundene Ressourcen als 404 Not Found.
  • Authentifizierung serverseitig pruefen.
  • Berechtigungen mit require_permission, require_any_permission oder require_all_permissions pruefen.
  • Mutierende Kernaktionen mit Audit Logs erfassen, sofern fachlich relevant.
  • Sensible Felder vor Persistenz in Logs oder Audit-Daten maskieren.
  • Import- und Bootstrap-Flows duerfen keine Passwoerter, Tokens, Secrets oder vollstaendige CSV-Inhalte loggen.
  • Dateiablagen laufen ueber StorageService; direkte Dateioperationen in Fachservices sind nur mit guter Begruendung zulaessig.
  • Uploads muessen Dateityp, MIME-Type, Groesse, Dateiname und Storage-Pfad validieren.

Allgemein

  • Keine Platzhalter-Kommentare als Ersatz fuer fertige Implementierung.
  • Keine Quickfixes.
  • Keine Workarounds.
  • Keine ungeprueften Annahmen bei Auth, Datenbank oder Docker.
  • Bestehende Architektur respektieren.

Architekturregeln

Diese Regeln sind verbindlich:

  • Browser spricht niemals direkt mit Hermes.
  • Alle Frontend-API-Zugriffe laufen ueber Athena /api.
  • Athena ruft Hermes serverseitig auf.
  • Hermes bleibt Cookie-frei.
  • Authentifizierung bleibt serverseitig.
  • Hermes erwartet JWT Bearer Tokens.
  • Athena setzt und loescht das HttpOnly Cookie.
  • Keine Cross-Origin-Cookie-Loesungen.
  • RBAC wird serverseitig in Hermes durchgesetzt.
  • Frontend-Permissions dienen nur der UI und ersetzen keine Backend-Pruefung.
  • Audit Logs werden serverseitig in Hermes geschrieben.
  • Neue Plattform-Endpunkte sollen das einheitliche API-Response-Format nutzen.
  • Header- und Benutzerkontext wird ueber GET /api/me geladen; hart codierte Benutzernamen sind unzulaessig.

Wenn eine Aufgabe diese Regeln zu verletzen scheint, muss zuerst die Architekturentscheidung geklaert werden.

Neue Module

Neue CRM-Module sollen die bestehenden Muster wiederverwenden.

Beispiele fuer spaetere Module:

  • Kunden
  • Projekte
  • Lieferanten
  • Kontakte
  • Mitarbeiter

Verbindliche Wiederverwendung:

  • DataTable fuer tabellarische Listen
  • ConfirmDialog fuer destruktive Aktionen
  • SearchInput fuer Suchfelder
  • StatusBadge oder aehnliche Badge-Komponenten fuer Statusanzeigen
  • ToastProvider fuer Erfolg und Fehler bei mutierenden Aktionen
  • api Client aus frontend/athena/lib/api.ts
  • Athena API-Routes als BFF-Schicht
  • konsistente Fehlerbehandlung
  • zentrale Permission-Helfer aus frontend/athena/lib/permissions.ts

Neue Module sollen mindestens diese UI-Zustaende unterstuetzen:

  • Ladezustand
  • Fehlerzustand
  • Empty State
  • Validierung
  • Erfolg ohne Page Reload

CRM-Modulstandard

Ein neues CRM-Modul soll sich am Kundenmodul orientieren:

  • SQLAlchemy-Modell in backend/hermes/app/models
  • Pydantic-Schemas in backend/hermes/app/schemas
  • Repository in backend/hermes/app/repositories
  • FastAPI-Router in backend/hermes/app/api
  • Alembic-Migration fuer Schemaaenderungen
  • Athena-BFF-Routen unter frontend/athena/app/api
  • Frontend-Seiten unter frontend/athena/app/<module>
  • wiederverwendbare UI-Komponenten unter frontend/athena/components
  • RBAC-Permissions vor der UI-Integration definieren
  • Audit-Log-Ereignisse fuer relevante Create/Update/Delete-Aktionen definieren
  • keine Fake-Daten fuer noch nicht existierende Unterbereiche

Dashboard-Widgets fuer noch nicht implementierte Module muessen Empty States anzeigen statt hart codierter Beispieldaten.

Kundenimport

Kundenimporte muessen die bestehende Kundenarchitektur nutzen und ueber Athena-BFF-Routen laufen. Der Browser darf keine Hermes-URL kennen.

CSV-Vorgaben:

  • UTF-8 bevorzugen
  • Semikolon und Komma unterstuetzen
  • leere Zeilen ignorieren
  • Fehler und Warnungen pro Zeile zurueckgeben
  • Preview darf keine Datenbank-Aenderungen ausloesen
  • Commit schreibt Audit Logs ohne CSV-Rohinhalt

Importmodi:

  • create_only
  • update_existing
  • upsert

Die Excel-freundliche Vorlage liegt unter GET /api/customers/import/template.

Wissensdatenbank

Das Knowledge-Modul folgt dem bestehenden Modulstandard:

  • SQLAlchemy-Modell in backend/hermes/app/models/knowledge.py
  • Pydantic-Schemas in backend/hermes/app/schemas/knowledge.py
  • Repository in backend/hermes/app/repositories/knowledge_repository.py
  • Service-Logik in backend/hermes/app/services/knowledge_service.py
  • FastAPI-Router in backend/hermes/app/api/knowledge.py
  • Athena-BFF unter /api/knowledge/...
  • Frontend-Seiten unter /knowledge

Upload-Regeln:

  • Browser sendet Dateien nur an Athena.
  • Athena leitet FormData serverseitig an Hermes weiter.
  • Hermes validiert Dateityp, MIME-Type, Dateigroesse und Speicherpfad.
  • Lokale Dateien liegen ueber Docker unter STORAGE_BASE_PATH; alte Knowledge-Pfade bleiben nur als Legacy-Fallback erhalten.
  • Dokumentuploads benoetigen Hersteller, Geraet, Dokumenttyp und Datei.
  • Ein Geraet muss serverseitig zum ausgewaehlten Hersteller gehoeren.
  • Fehlende Upload-Voraussetzungen muessen im Formular sichtbar sein und duerfen keinen Upload starten.
  • Audit Logs duerfen keine Datei-Inhalte enthalten.
  • Keine Pfade aus unvalidierten Benutzereingaben zusammensetzen.

Workflow-Regel:

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

Knowledge-Listen sollen EmptyState nutzen, wenn Daten fehlen oder Suche/Filter keinen Treffer liefern.

Paperless-ngx ist nur vorbereitet. paperless_document_id und external_url duerfen gepflegt werden, aber es werden keine Paperless-Secrets oder API-Keys eingefuehrt.

Storage

Neue Dateiablagen muessen das zentrale Storage Framework verwenden.

Regeln:

  • Keine unvalidierten Pfade aus Benutzereingaben zusammensetzen.
  • Keine absoluten User-Pfade akzeptieren.
  • Keine Path-Traversal-Moeglichkeiten zulassen.
  • Originaldateinamen und gespeicherte Dateinamen fachlich unterscheiden.
  • SHA256 fuer gespeicherte Dateien berechnen, sofern das Modul Datei-Metadaten persistiert.
  • Keine Datei-Inhalte loggen.
  • Bestehende Dateien nicht automatisch verschieben oder loeschen.

Der lokale Provider nutzt STORAGE_BASE_PATH; Docker mountet den Host-Pfad aus STORAGE_HOST_PATH nach /data/storage.

Deployment

Neue Installationen koennen optional ueber INITIAL_ADMIN_* einen initialen Administrator anlegen. Diese Variablen werden nur von Hermes gelesen und duerfen nicht im Frontend oder in Logs erscheinen.

Dateien benoetigen einen persistenten Storage-Mount. Vor produktiven Deployments muessen STORAGE_PROVIDER, STORAGE_BASE_PATH, STORAGE_MAX_UPLOAD_MB und STORAGE_HOST_PATH bewusst gesetzt oder die Defaults akzeptiert werden.

Die Skripte unter scripts/ sind die bevorzugte Grundlage fuer Migration, Healthcheck, Deploy, Backup und Restore.

Neue Permissions

Neue Module muessen eigene stabile Permission-Strings erhalten.

Namensschema:

<module>.<action>

Beispiele:

customers.read
customers.create
projects.update
tickets.delete

Regeln:

  • Permission in backend/hermes/app/rbac/defaults.py ergaenzen.
  • Rollen-Mapping in ROLE_PERMISSION_NAMES pruefen.
  • Falls noetig Alembic-Migration fuer bestehende Installationen ergaenzen.
  • Hermes-Endpunkte mit require_permission(...) schuetzen.
  • Athena UI-Aktionen mit hasPermission(...) ausblenden oder deaktivieren.
  • Backend bleibt immer massgeblich.

Review-Checkliste

Vor Merge pruefen:

  • Auth-Architektur nicht gebrochen
  • Browser ruft Hermes nicht direkt auf
  • Docker laeuft
  • Migrationen vorhanden, falls Schema geaendert wurde
  • Migrationen getestet
  • UI konsistent mit bestehenden Komponenten
  • keine Secrets committed
  • keine .env committed
  • keine toten Imports
  • keine ungenutzten Dateien
  • keine Debug-Ausgaben
  • keine Build-Artefakte committed
  • keine neuen CORS- oder Cookie-Workarounds
  • Permission-Pruefung fuer neue Endpunkte vorhanden
  • Permission-UI nur als Komfort, nicht als Sicherheitsgrenze
  • Audit Logs fuer relevante Aenderungen vorhanden
  • API-Fehlerantworten konsistent
  • Toasts fuer mutierende UI-Aktionen vorhanden
  • Dateiablagen verwenden StorageService
  • Storage-Pfade sind gegen Path Traversal geschuetzt
  • Backup-/Restore-Auswirkungen fuer Dateiablagen dokumentiert

Migrationsregeln

Datenbankschema wird ausschliesslich ueber Alembic geaendert.

Regeln:

  • Jede Schemaaenderung braucht eine Migration.
  • Migrationen werden ins Repository aufgenommen.
  • alembic upgrade head muss getestet werden.
  • Downgrade sollte sinnvoll sein, sofern moeglich.
  • Keine manuellen Produktions-DB-Aenderungen ohne Dokumentation.

Typischer Ablauf:

cd backend/hermes
alembic upgrade head

Sicherheitsregeln

Verbindlich:

  • Keine Secrets im Code.
  • Keine Secrets in Commits.
  • Keine Tokens im Browser-JavaScript.
  • Keine Auth in localStorage.
  • Keine Auth in sessionStorage.
  • Keine CORS-Cookie-Workarounds.
  • Keine Cross-Origin-Cookies.
  • Produktiv nur HTTPS.
  • AUTH_COOKIE_SECURE=true in Produktion.
  • SECRET_KEY stark und geheim halten.

Bei Auth-Aenderungen muessen Login, Logout, geschuetzte Seiten und Athena-API-Routes gemeinsam geprueft werden.

Bei RBAC-Aenderungen muessen Rollen, Permissions, betroffene API-Endpunkte, Navigation und UI-Aktionen gemeinsam geprueft werden.

Lokale Entwicklung

Lokaler Betrieb kann ueber Docker Compose erfolgen.

Wichtige lokale Einstellungen:

AUTH_COOKIE_SECURE=false
ATHENA_PUBLIC_ORIGIN=http://localhost:3001

Diese Werte sind nur fuer lokale HTTP-Entwicklung gedacht. In Produktion muessen sichere Werte verwendet werden.

Dokumentationspflicht

Architekturentscheidungen, neue Module, neue Umgebungsvariablen und Datenbankmigrationen muessen dokumentiert werden.

Wenn sich die BFF-Architektur, Authentifizierung, Docker-Konfiguration oder Datenbankstruktur aendert, muss ARCHITECTURE.md aktualisiert werden.