287 lines
7.7 KiB
Markdown
287 lines
7.7 KiB
Markdown
# 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
|
|
|
|
### 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
|
|
- keine Fake-Daten fuer noch nicht existierende Unterbereiche
|
|
|
|
Dashboard-Widgets fuer noch nicht implementierte Module muessen Empty States anzeigen statt hart codierter Beispieldaten.
|
|
|
|
### 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.
|