98 lines
4.1 KiB
Markdown
98 lines
4.1 KiB
Markdown
# 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.
|