Olympus/CONTRIBUTING.md

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.