Initial commit

docs/using-as-template.md

@@ -0,0 +1,97 @@
+# Als Projektvorlage Verwenden
+
+Dieses Boilerplate ist bewusst nah an einer realen internen Business-Anwendung.
+Beim Start eines neuen Projekts solltest du zuerst Namen, Branding,
+Runtime-Konfiguration und Demo-Fachlichkeit ersetzen, aber die Sicherheits- und
+Betriebsentscheidungen beibehalten.
+
+## Empfohlener Start
+
+1. Repository kopieren oder als Template verwenden.
+2. Paketnamen und Beschreibungen in `package.json`, `apps/*/package.json` und
+   `packages/api-client/package.json` anpassen.
+3. UI-Name `Business App` in `apps/frontend/src/app/layout/app-shell.ts` ersetzen.
+4. Swagger-Titel und Beschreibung in `apps/backend/src/main.ts` ersetzen.
+5. Docker-Image-Namen in README, CI und Compose auf den Projektnamen aendern.
+6. `.env.example` auf die Zielumgebung zuschneiden, aber keine Secrets eintragen.
+7. Lizenz, Repository-URL, Ownership und Open-Source-Metadaten bewusst setzen.
+
+## Was du behalten solltest
+
+- Backend-for-Frontend Authentifizierung: OIDC-Tokens bleiben im Backend.
+- Server-seitige Sessions in MySQL.
+- CSRF-Schutz fuer alle schreibenden Requests.
+- TypeORM-Migrationen statt `synchronize`.
+- Controller delegieren an Services; Datenbankzugriff liegt in Repositories oder
+  klar benannten Persistence-Services.
+- Permissions sind Code, Rollen sind Daten.
+- Keine UI-Library als versteckte Projektbindung.
+- Striktes TypeScript ohne `any`.
+
+## Demo-Fachlichkeit entfernen oder ersetzen
+
+Das Modul `items` ist ein Beispiel fuer ein einfaches fachliches CRUD-Modul mit
+optimistischer Versionierung und Soft Delete. Fuer ein neues Projekt gibt es zwei
+saubere Optionen:
+
+- Behalten und in das erste echte Fachmodul umbenennen.
+- Entfernen und anhand der Struktur ein neues Modul erstellen.
+
+Wenn du `items` entfernst, pruefe mindestens:
+
+- Backend-Import in `apps/backend/src/app.module.ts`
+- Entity-Export in `apps/backend/src/database/entities.ts`
+- Initiale Migration und neue Migration fuer Schema-Aenderungen
+- Permissions in `apps/backend/src/roles/permissions.ts`
+- Routen in `apps/frontend/src/app/app.routes.ts`
+- Navigation in `apps/frontend/src/app/layout/app-shell.ts`
+- API-Client-Generator in `scripts/generate-api-client.mjs`
+- Frontend-Pages und Tests unter `apps/frontend/src/app/features/items`
+
+## Ein neues Feature anlegen
+
+Backend:
+
+1. Feature-Ordner unter `apps/backend/src/<feature>` anlegen.
+2. Entity, DTOs, Repository, Service, Controller und Module erstellen.
+3. Controller nur mit Services verdrahten.
+4. Datenbankzugriff im Repository kapseln.
+5. Permissions in `roles/permissions.ts` ergaenzen.
+6. Controller-Methoden mit `@RequirePermissions(...)` schuetzen.
+7. Entity in `database/entities.ts` aufnehmen.
+8. Migration erzeugen und pruefen.
+9. Verhaltenstests fuer Service oder Controller schreiben.
+
+Frontend:
+
+1. Page unter `apps/frontend/src/app/features/<feature>` erstellen.
+2. Route in `app.routes.ts` anlegen.
+3. Navigation in `app-shell.ts` ergaenzen.
+4. Permission im Route-`data` und in der Navigation konsistent setzen.
+5. API-Client ueber `packages/api-client` verwenden.
+6. Verhaltenstests fuer relevante UI-Logik schreiben.
+
+API-Client:
+
+Aktuell schreibt `scripts/generate-api-client.mjs` den Client reproduzierbar aus
+einer gepflegten Vorlage. Wenn die API waechst, muss der Generator erweitert oder
+durch eine echte OpenAPI-Codegenerierung ersetzt werden. Der Client selbst ist
+generierter Code und sollte nicht manuell editiert werden.
+
+## Open-Source-Veroeffentlichung
+
+Vor einer Veroeffentlichung als Open-Source-Projekt:
+
+- `license` in `package.json` bewusst setzen.
+- `LICENSE` und optional `NOTICE` hinzufuegen.
+- Namen, Screenshots, Domaenen, Beispiel-Registry und interne Hinweise entfernen.
+- Beispiel-Secrets in `.env.example` nur als Platzhalter belassen.
+- Pruefen, ob alle Dependencies und generierten Artefakte lizenzkompatibel sind.
+- Sicherheitsmodell in README und `docs/security.md` aktuell halten.
+
+## Projektgrenzen
+
+Dieses Boilerplate ist fuer eine einzelne deploybare Business-Anwendung gebaut.
+Es ist kein Microservice-Framework, kein Nx-Workspace und keine Multi-Tenant
+Plattform. Wenn ein Projekt diese Grenzen braucht, sollte die Architektur zuerst
+bewusst erweitert werden, statt sie indirekt ueber Feature-Code einzuschleppen.