# Leistungsbilanz

Leistungsbilanz ist eine Webanwendung für die elektrische Ausführungsplanung. Im
Mittelpunkt steht ein tabellenähnlicher Stromkreislisten-Editor, der Stromkreise,
Gerätezeilen und wiederverwendbare Projektgeräte fachlich getrennt behandelt.

Das Projekt befindet sich in aktiver Entwicklung. Unterstützt sind der lokale
Entwicklungsbetrieb (`compose.yaml`) und ein Einzelbenutzer-Deployment im
vertrauenswürdigen Netz (`compose.prod.yaml`). Authentifizierung,
Mehrbenutzerbetrieb und der Revit-/IFCGUID-Datenaustausch sind noch nicht
implementiert.

## Unterstützter Arbeitsablauf

- Projekte, Verteilungen, Etagen und Räume verwalten
- pro Verteilung geschützte Stromkreisgruppen für Beleuchtung, 1-phasige und
  3-phasige Stromkreise verwalten
- Hauptschalter, Überspannungsableiter, Gruppenschutz und zusätzliche
  Verteilergeräte in der Stromkreisliste abbilden
- Schutzgeräte je Stromkreis und optional je Gruppe konfigurieren
- leere, einzeilige und mehrzeilige Stromkreise abbilden
- Stromkreise und Gerätezeilen per Drag-and-drop umstrukturieren
- Projektgeräte einfügen, verknüpfen und kontrolliert synchronisieren
- komplette Stromkreisblöcke filtern und sortieren
- BMKs stabil halten und nur auf ausdrücklichen Befehl neu nummerieren
- Änderungen projektweit und auch nach einem Reload rückgängig machen und wiederholen
- benannte Sicherungspunkte anlegen, wiederherstellen und Revisionen einsehen
- automatische Sicherungspunkte mit begrenzter Aufbewahrung nutzen

## Technik

- Next.js 16, React 19 und TypeScript für das Frontend
- Express 5 und Zod für die API
- SQLite, `better-sqlite3` und Drizzle ORM für die Persistenz
- eigener Spreadsheet-Grid statt eines Bootstrap-Tabellenframeworks
- Node.js-Test-Runner für Domain-, Grid- und SQLite-Integrationstests

## Schnellstart mit Docker

Voraussetzungen:

- Git
- Docker Desktop mit Docker Compose

```powershell
git clone <repository-url>
Set-Location leistungsbilanz-ts
docker compose up --build --detach
```

Danach:

- Frontend: <http://localhost:3001>
- API-Healthcheck: <http://localhost:3000/health>

Der API-Container führt ausstehende Migrationen und die Schemaprüfung beim Start
automatisch aus. Die SQLite-Datei liegt auf dem Host unter
`data/leistungsbilanz.db` und bleibt beim Stoppen erhalten.

```powershell
docker compose ps
docker compose logs --follow
docker compose down
```

`compose.yaml` startet Entwicklungsserver mit Quellcode-Mounts, veröffentlicht
seine Ports nur auf `127.0.0.1` und ist **kein Produktionsdeployment**. Es
gehört nicht in den Dauerbetrieb: `next dev` und `tsx watch` erzeugen auch ohne
Benutzer dauerhaft Last und wachsen im Speicher.

## Deployment

```bash
docker compose -f compose.prod.yaml up --build --detach
```

Startet die kompilierte API und `next start` in getrennten Containern, mit
Speicherlimits und ohne Dateibeobachter. Das Frontend hört auf Port 3090, die
API ist nur intern erreichbar. Vorbereitung eines bestehenden Datenvolumes und
weitere Details stehen in [Deployment und Betrieb](docs/deployment.md).

## Direkte lokale Entwicklung

Voraussetzungen:

- Node.js 22
- npm

```powershell
npm ci
npm run db:migrate
npm run db:verify:circuit-schema
npm run dev:api
```

In einem zweiten Terminal:

```powershell
npm run dev:web
```

Frontend und API laufen anschließend auf denselben Ports wie im Docker-Setup.

## Qualitätssicherung

```powershell
npm test
npm run build:api
npm run build:web
npm run typecheck:scripts
npx tsc --noEmit -p tsconfig.next.json
```

Wichtige Datenbankbefehle:

```powershell
npm run db:backup
npm run db:migrate
npm run db:verify:circuit-schema
npm run db:generate
```

`db:backup` verwendet die SQLite-Online-Backup-API und prüft das Ergebnis auf
Integrität und Fremdschlüsselverletzungen. Migration `0000` ist die
Release-Baseline für eine leere Datenbank; nachfolgende nummerierte Migrationen
entwickeln diese Baseline additiv weiter. Datenbanken aus Entwicklungsständen
vor der Baseline werden nicht unterstützt.

## Dokumentation

- [Dokumentationsübersicht](docs/README.md)
- [Aktuelle Architektur](docs/current-architecture.md)
- [Editor-Interaktionen](docs/circuit-list-editor-interactions.md)
- [API des Stromkreislisten-Editors](docs/circuit-list-editor-api.md)
- [Entwicklungs- und Contributor-Workflow](docs/development-workflow.md)
- [Bekannte Einschränkungen](docs/circuit-list-editor-known-limitations.md)
- [Roadmap](docs/spec/07-implementation-phases-todo.md)

Für LLM-gestützte Änderungen enthält [AGENTS.md](AGENTS.md) die verbindlichen
Domänenregeln, unterstützten Einstiegspunkte und Architekturgrenzen.