initial

docs/development.md

@@ -0,0 +1,119 @@
+# Entwicklung
+
+Diese Datei beschreibt die normalen Entwicklungsablaeufe im Monorepo.
+
+## Installation
+
+```bash
+npm ci
+```
+
+Abhaengigkeiten werden nur im Root installiert. Workspace-spezifische Befehle
+werden ueber Root-Scripts oder `npm --workspace ...` ausgefuehrt.
+
+## Lokaler Start
+
+```bash
+npm run dev
+```
+
+Alternativ getrennt:
+
+```bash
+npm run dev:frontend
+npm run dev:backend
+```
+
+Das Frontend nutzt den Proxy in `apps/frontend/proxy.conf.json`, damit `/api`
+lokal an das Backend weitergereicht wird.
+
+## Feature-Workflow
+
+1. Backend-DTOs und Entities modellieren.
+2. Repository fuer Datenzugriff erstellen oder erweitern.
+3. Service mit Fachlogik implementieren.
+4. Controller nur als HTTP-Rand und Permission-Deklaration verwenden.
+5. Permission in `roles/permissions.ts` ergaenzen, falls noetig.
+6. Migration erzeugen und kontrollieren.
+7. API-Client-Generator aktualisieren.
+8. Frontend-Route, Navigation und Page bauen.
+9. Tests fuer Verhalten schreiben.
+10. Qualitaetsbefehle ausfuehren.
+
+## Migrationen
+
+Status anzeigen:
+
+```bash
+npm run migration:status
+```
+
+Migration erzeugen:
+
+```bash
+npm run migration:generate
+```
+
+Migration ausfuehren:
+
+```bash
+npm run migration:run
+```
+
+Generierte Migrationen muessen reviewed werden. Sie duerfen keine
+versehentlichen Datenverluste, falsche Defaults oder umgebungsspezifische Namen
+enthalten.
+
+## API-Client
+
+Nach API-Aenderungen:
+
+```bash
+npm run api:generate
+```
+
+Der Client unter `packages/api-client/src` ist generiert. Aendere stattdessen den
+Generator oder ersetze ihn spaeter bewusst durch einen OpenAPI-basierten
+Generator.
+
+## Tests
+
+```bash
+npm test
+npm run test:backend
+npm run test:frontend
+```
+
+Tests sollen Verhalten pruefen, nicht nur Existenz. Backend-Tests fuer Services
+sollen fachliche Regeln, Fehlerfaelle, Permissions und Datenbankinteraktionen
+abdecken. Frontend-Tests sollen sichtbares Verhalten, Guards, Interaktionen und
+API-Fehlerpfade abdecken.
+
+Integrationstests gegen MySQL muessen eine separate Testdatenbank verwenden,
+deren Name eindeutig `test` enthaelt. Tests duerfen niemals gegen
+Produktionsdatenbanken laufen.
+
+## Qualitaet vor Abschluss
+
+```bash
+npm run lint
+npm run format:check
+npm run typecheck
+npm test
+npm run build
+docker build .
+```
+
+Diese Befehle sind die Mindestpruefung fuer Merge und Release.
+
+## Fehlerformat
+
+Backend-Fehler werden ueber `ApiExceptionFilter` in ein konsistentes Format
+gebracht. Neue fachliche Fehler sollten `ApiError` und `ErrorCode` verwenden,
+damit Frontend und Logs stabil bleiben.
+
+## Logging
+
+`pino-http` redigiert sensible Header und Token-Felder. Neue Logs duerfen keine
+Secrets, Session-IDs, Cookies, Access Tokens, Refresh Tokens oder ID Tokens
+enthalten.