# 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/` - Bugfixes: `fix/` - Dokumentation: `docs/` 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 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 ``` ```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 Browser-Dialoge wie `alert()` oder `confirm()`. - 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. ### 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. - 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 - 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/` - 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 unter `KNOWLEDGE_STORAGE_PATH`. - Audit Logs duerfen keine Datei-Inhalte enthalten. - Keine Pfade aus unvalidierten Benutzereingaben zusammensetzen. Paperless-ngx ist nur vorbereitet. `paperless_document_id` und `external_url` duerfen gepflegt werden, aber es werden keine Paperless-Secrets oder API-Keys eingefuehrt. ### 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. Knowledge-Dateien benoetigen ein persistentes Docker-Volume. Vor produktiven Deployments muessen `KNOWLEDGE_STORAGE_PATH` und `KNOWLEDGE_MAX_UPLOAD_MB` bewusst gesetzt oder die Defaults akzeptiert werden. ### Neue Permissions Neue Module muessen eigene stabile Permission-Strings erhalten. Namensschema: ```text . ``` 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 ## 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.