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.

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.
3. Ein Projektgerät mit unkritischen Fantasiewerten anlegen.
4. Die erzeugte Stromkreisliste öffnen und das Gerät in einen passenden Bereich ziehen.

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
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:3000/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. Bestehende lokale Datenbank sichern: npm run db:backup.
2. Schema unter src/db/schema/ ändern.
3. npm run db:generate ausführen.
4. Das generierte SQL vollständig prüfen; es darf nur die beabsichtigte Änderung enthalten.
5. Upgrade-/Erhaltungstest ergänzen, wenn Spalten oder Beziehungen geändert werden.
6. npm test, npm run db:migrate und npm run db:verify:circuit-schema ausführen.

Bereits angewendete SQL-Migrationen dürfen nicht geändert oder neu sortiert werden. Korrekturen erfolgen 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