leistungsbilanz-ts/docs/development-workflow.md

Entwicklungs- und Contributor-Workflow

Erstes lokales Setup

Der empfohlene Einstieg ist Docker Compose:

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:

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:

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

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:

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