# 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.

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.
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

```powershell
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:

```powershell
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