# 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
- `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:

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

```bash
python3 -m compileall backend/hermes/app
```

```bash
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
- Reparaturen
- 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:

```text
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:

```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
- 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:

```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.
