Rewrite project documentation

2026-07-23 21:05:43 +02:00
parent 30d6f1a2e1
commit 6b6d2c2a42
17 changed files with 535 additions and 221 deletions
@@ -0,0 +1,110 @@
+# 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
+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.
+
+## 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