feat(rbac): add roles and permissions

CONTRIBUTING.md

@@ -0,0 +1,270 @@
+# 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:
+
+```text
+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:
+
+```text
+type(scope): kurze beschreibung
+```
+
+Beispiele:
+
+```text
+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:
+
+```bash
+cd frontend/athena
+npm run lint
+npx next build --webpack
+```
+
+```bash
+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:
+
+```text
+<module>.<action>
+```
+
+Beispiele:
+
+```text
+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:
+
+```bash
+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:
+
+```env
+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.