benjamin
132 lines
3.8 KiB
Markdown
132 lines
3.8 KiB
Markdown
# Entwicklungsworkflow
|
|
|
|
## Voraussetzungen
|
|
|
|
Das Projekt ist eine Angular-Anwendung mit Node.js-Abhängigkeiten aus `package.json`. Der CI-Workflow verwendet `node:20-bullseye`; lokale Entwicklung sollte daher eine kompatible Node-Version verwenden.
|
|
|
|
Installiere Abhängigkeiten mit:
|
|
|
|
```bash
|
|
npm ci -f
|
|
```
|
|
|
|
Die Option `-f` entspricht dem Gitea-CI-Workflow.
|
|
|
|
## Lokale Konfiguration
|
|
|
|
Für lokale Builds muss `src/environments/firebase.ts` existieren. Die Datei wird nicht versioniert und enthält die Firebase-Projektwerte.
|
|
|
|
Minimalstruktur:
|
|
|
|
```ts
|
|
export const firebase = {
|
|
apiKey: '...',
|
|
authDomain: '...',
|
|
databaseURL: 'https://worshipgenerator.firebaseio.com',
|
|
projectId: '...',
|
|
storageBucket: '...',
|
|
messagingSenderId: '...',
|
|
appId: '...',
|
|
};
|
|
```
|
|
|
|
Ohne diese Datei schlagen Angular-Builds fehl, weil `environment.ts` und `environment.prod.ts` sie importieren.
|
|
|
|
## Entwicklungsserver
|
|
|
|
Starte die Anwendung lokal mit:
|
|
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
Der Befehl führt `ng serve` aus. In `angular.json` ist `development` die Standardkonfiguration für `serve`.
|
|
|
|
## Build-Varianten
|
|
|
|
Development-Build:
|
|
|
|
```bash
|
|
npm run build:dev
|
|
```
|
|
|
|
Production-Build:
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
Der Production-Build nutzt `environment.prod.ts`, aktiviert Output-Hashing und schreibt nach `dist/wgenerator`. Firebase Hosting erwartet den Browser-Build unter `dist/wgenerator/browser`.
|
|
|
|
## Tests und Linting
|
|
|
|
Unit-Tests:
|
|
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
Linting mit automatischen Fixes:
|
|
|
|
```bash
|
|
npm run lint
|
|
```
|
|
|
|
Tests liegen als `*.spec.ts` neben den Implementierungen. Der Angular Unit-Test-Builder nutzt Vitest und lädt gemeinsame Testkonfiguration aus `src/test-vitest.ts`.
|
|
|
|
## Codeorganisation
|
|
|
|
Neue fachliche Funktionen sollten in das passende Feature-Modul unter `src/app/modules` einsortiert werden. Gemeinsame Services gehören nach `src/app/services`; wiederverwendbare UI-Komponenten, Pipes, Direktiven und Guards nach `src/app/widget-modules`.
|
|
|
|
Der bestehende Stil verwendet:
|
|
|
|
- TypeScript und Angular-Module mit lazy geladenen Feature-Modulen.
|
|
- Standalone-Komponenten dort, wo sie bereits im Code genutzt werden.
|
|
- LESS für Component-Styles.
|
|
- RxJS-Observables für Firestore-Livedaten.
|
|
- Services als fachliche Fassade über `DbService`.
|
|
|
|
## Datenzugriff in neuen Funktionen
|
|
|
|
Firestore-Zugriffe sollten über `DbService` oder vorhandene Fachservices erfolgen. Direkte AngularFire-Zugriffe sind nur sinnvoll, wenn der vorhandene Wrapper eine benötigte Operation nicht abbildet.
|
|
|
|
Bei neuen fachlichen Datenflüssen ist zu prüfen:
|
|
|
|
- ob ein Live-Observable oder ein einmaliger Promise-Zugriff benötigt wird,
|
|
- ob `shareReplay` sinnvoll ist, um Listener wiederzuverwenden,
|
|
- ob denormalisierte Felder wie `songUsage` oder `songIds` aktualisiert werden müssen,
|
|
- ob Firestore-Regeln und UI-Rollen die neue Aktion angemessen abdecken.
|
|
|
|
## Rollen und UI-Zugriff
|
|
|
|
Neue geschützte Routen sollten `AuthGuard` und bei Bedarf `RoleGuard` mit `requiredRoles` nutzen. Sichtbare Aktionen in Templates sollten über `*appRole` und bei besitzabhängigen Aktionen über `*appOwner` gesteuert werden.
|
|
|
|
Da Firestore-Regeln für fachliche Collections nur Login voraussetzen, müssen rollenbasierte Einschränkungen in Routing, UI und Services konsistent umgesetzt werden.
|
|
|
|
## Deployment-Ablauf
|
|
|
|
Für ein reguläres Deployment:
|
|
|
|
```bash
|
|
npm run deploy
|
|
```
|
|
|
|
Der Befehl baut die Production-Version und führt anschließend `firebase deploy` aus. Für einen Beta-Channel:
|
|
|
|
```bash
|
|
npm run deploy-beta
|
|
```
|
|
|
|
Vor Deployments sollten mindestens Build und relevante Tests lokal oder im CI erfolgreich sein.
|
|
|
|
## Manuelle Admin-Wartung
|
|
|
|
Das README beschreibt zwei manuelle Browser-Konsolenbefehle für Admins:
|
|
|
|
```js
|
|
await window.wgeneratorAdmin.rebuildSongUsage()
|
|
await window.wgeneratorAdmin.rebuildShowSongIds()
|
|
```
|
|
|
|
Diese Migrationen sind read-heavy und sollten bewusst ausgeführt werden, wenn historische Daten nachgezogen oder Indizes rekonstruiert werden müssen.
|