115 lines
3.5 KiB
Markdown
115 lines
3.5 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.
|
|
|
|
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
|