admin.schubert/Olympus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Olympus/CONTRIBUTING.md
Schubert Ferenc 694b7bd09a feat(rbac): add roles and permissions
2026-07-02 23:05:59 +02:00

7 KiB
Raw Permalink 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
  • 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 wie console.log, alert oder confirm

Standard-Checks:

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

python3 -m compileall backend/hermes/app

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.
  • Keine Browser-Dialoge wie alert() oder confirm().
  • Keine Tokens in Browser-JavaScript speichern.

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.

Allgemein

  • Keine TODOs 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.

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
  • 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

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

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.