forked from jappel/leistungsbilanz-ts
Julian Appel
7222398628
tsx runs tests without type checking and tsconfig.json covers only src, so 71 type errors had accumulated unnoticed. tsconfig.tests.json now checks every test and helper, and npm run typecheck includes it. Fixtures gain the fields the DTOs have grown since they were written (manualQuantity, circuit apparent power/cos phi, downstream board loads, section totals, building, cover and board info fields). Repository lookups that return "row ?? null" now declare the null in their type, which their callers already handle. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
128 lines
4.3 KiB
Markdown
128 lines
4.3 KiB
Markdown
# Entwicklungs- und Contributor-Workflow
|
|
|
|
## Erstes lokales Setup
|
|
|
|
Der empfohlene Einstieg ist Docker Compose:
|
|
|
|
```powershell
|
|
docker compose up --build --detach
|
|
docker compose ps
|
|
```
|
|
|
|
Ein sauberer Clone enthält keine SQLite-Datenbank. Beim ersten Start werden
|
|
`data/leistungsbilanz.db`, alle Tabellen und Migrationseinträge automatisch
|
|
angelegt. Das Frontend ist unter <http://localhost:3001> erreichbar.
|
|
|
|
Dieser Standard-Stack verwendet gebauten Anwendungscode. Für die Entwicklung
|
|
mit Quellcode-Mounts und Hot Reload stattdessen
|
|
`docker compose -f compose.dev.yaml up --build --detach` verwenden; die Dienste
|
|
sind dabei nur über die Loopback-Ports des Entwicklungsrechners erreichbar.
|
|
|
|
Für direkte Node.js-Entwicklung:
|
|
|
|
```powershell
|
|
npm ci
|
|
npm run db:migrate
|
|
npm run db:verify:circuit-schema
|
|
```
|
|
|
|
Danach `npm run dev:api` und `npm run dev:web` in getrennten Terminals starten.
|
|
|
|
## Leere lokale Datenbank
|
|
|
|
Eine bestehende lokale Datenbank lässt sich recoverable ersetzen:
|
|
|
|
```powershell
|
|
docker compose down
|
|
npm run db:backup
|
|
Move-Item -LiteralPath .\data\leistungsbilanz.db .\data\leistungsbilanz.previous.db
|
|
docker compose up --build --detach
|
|
```
|
|
|
|
Die verschobene Datei und das verifizierte Backup bleiben lokal erhalten. Vor dem
|
|
Verschieben müssen die Container beendet sein, damit keine WAL-Sidecar-Datei aktiv
|
|
ist.
|
|
|
|
## Sichere Beispieldaten
|
|
|
|
Es gibt aktuell keinen versionierten Seed-Datensatz. Dadurch gelangen keine
|
|
Projekt- oder Kundendaten versehentlich ins Repository. Für einen lokalen
|
|
Testbestand:
|
|
|
|
1. In der UI ein Projekt `Demo` anlegen.
|
|
2. Im Projekt eine Verteilung `UV-01` erstellen. Die Stromkreisliste enthält
|
|
danach Hauptschalter, Überspannungsableiter und je eine Gruppe für
|
|
Beleuchtung, 1-phasige und 3-phasige Stromkreise.
|
|
3. Ein Projektgerät mit unkritischen Fantasiewerten anlegen.
|
|
4. Die erzeugte Stromkreisliste öffnen und das Gerät in eine passende Gruppe
|
|
ziehen.
|
|
5. Optional eine zweite Gruppe derselben Kategorie, einen Gruppen-FI und ein
|
|
zusätzliches Verteilergerät anlegen. Damit lassen sich Gruppensortierung,
|
|
explizite Neunummerierung, Stromkreiswechsel und persistentes Undo/Redo ohne
|
|
reale Projekt- oder Kundendaten prüfen.
|
|
|
|
Dateien unter `data/` und `data/backups/` dürfen nicht committed werden.
|
|
|
|
## Arbeitsablauf für Änderungen
|
|
|
|
1. Von einem aktuellen Branch einen kleinen Feature- oder Fix-Branch erstellen.
|
|
2. Relevante Domänenregeln in `AGENTS.md` und die aktuelle Architektur lesen.
|
|
3. Änderungen in einem fachlich geschlossenen Paket umsetzen.
|
|
4. Tests und Dokumentation proportional zur Änderung aktualisieren.
|
|
5. Alle erforderlichen Prüfungen ausführen.
|
|
6. Mit einer kurzen, prägnanten Nachricht committen.
|
|
|
|
Empfohlene Commitnachrichten sind imperativ und beschreiben das Ergebnis, zum
|
|
Beispiel `Preserve circuit blocks during filtering`.
|
|
|
|
## Pflichtprüfungen
|
|
|
|
```powershell
|
|
npm test
|
|
npm run build:api
|
|
npm run build:web
|
|
npm run typecheck:scripts
|
|
npm run typecheck:tests
|
|
npx tsc --noEmit -p tsconfig.next.json
|
|
git diff --check
|
|
```
|
|
|
|
Bei Docker- oder Laufzeitänderungen zusätzlich:
|
|
|
|
```powershell
|
|
docker compose up --build --detach
|
|
docker compose ps
|
|
Invoke-WebRequest http://localhost:3001/health
|
|
Invoke-WebRequest http://localhost:3001/web-health
|
|
```
|
|
|
|
Bei sichtbaren Editoränderungen ist außerdem ein kurzer GUI-Test erforderlich.
|
|
Testaufbau, der vollständige Projektstrukturen direkt einfügt, gehört nach
|
|
`tests/support`. Produktions-Repositories dürfen nicht nur für Testfixtures
|
|
erneut direkte Schreibmethoden erhalten.
|
|
|
|
## Migrationen
|
|
|
|
1. Schema unter `src/db/schema/` ändern.
|
|
2. `npm run db:generate` ausführen.
|
|
3. Das generierte SQL vollständig prüfen; es darf nur die beabsichtigte Änderung
|
|
enthalten.
|
|
4. Upgrade-/Erhaltungstest ergänzen, wenn Spalten oder Beziehungen geändert
|
|
werden.
|
|
5. `npm test`, `npm run db:migrate` und
|
|
`npm run db:verify:circuit-schema` ausführen.
|
|
|
|
`0000` ist die saubere Baseline für leere Neuinstallationen. Vor-Baseline-
|
|
Entwicklungsdatenbanken werden nicht aktualisiert. Nach Veröffentlichung der
|
|
ersten Version dürfen angewendete SQL-Migrationen nicht geändert oder neu
|
|
sortiert werden; Korrekturen erfolgen dann immer über eine neue Migration.
|
|
|
|
## Pull-Request-Handoff
|
|
|
|
Die Beschreibung sollte enthalten:
|
|
|
|
- fachliches Ergebnis
|
|
- Datenmodell- und API-Auswirkung
|
|
- ausgeführte Tests
|
|
- erforderliche manuelle Migration oder GUI-Prüfung
|
|
- bekannte Einschränkungen oder bewusst verschobene Arbeit
|