leistungsbilanz-ts/README.md

# 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. Für SQLite stehen ein
Docker-Server-Stack mit gebautem Anwendungscode und ein separater
Entwicklungsstack bereit. Ein vollständig unterstütztes Produktionsdeployment
für mehrere gleichzeitig arbeitende Prozesse und ein vollständig unterstütztes
Produktionsdeployment fehlen weiterhin. Anmeldung und zwei feste Rollen sind
vorhanden. Die Backend- und Persistenzgrundlage der bisherigen
Revit-CSV-/IfcGUID-Anbindung ist durch den XLSX-Austausch des Linear-Plugins mit
Worksharing-ID als externem Schlüssel ersetzt. R0 bis R10 sind abgeschlossen;
die eigene Revit-Seite unterstützt Einstellungen, Erst- und Folgeimport,
virtuelle Objektbearbeitung, Editorzuordnung und strukturtreue Rückgabe.
Die Phase-14-Kette ist Ende zu Ende und mit 5.000 synthetischen Objekten geprüft.

## Unterstützter Arbeitsablauf

- Projekte und Verteilungen verwalten; Gebäude, Etagen und Räume auf einer
  eigenen Seite pflegen, Räume optional mit Fläche und Summen je Etage und
  Gebäude
- 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
- Leitungsquerschnitte für einzelne Stromkreise auf Anforderung nach
  DIN VDE 0298-4 berechnen und ausdrücklich übernehmen
- 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
- Seitenansicht mit Deckblatt, Verteilerübersicht und Verteilerplänen öffnen
  und über den Browser als PDF drucken; Büroangaben und Logo zentral pflegen
- grobe Leistungsbilanzen für LPH 2/3 nach Kostengruppen führen, mit der
  detaillierten Bilanz vergleichen und einzelne Zeilen als Projektgerät
  übernehmen
- Linear-XLSX-Dateien verlustarm lesen und schreiben; Erst- und Folgeimporte
  prüfen, Revit-Objekte zuordnen und geplante Werte strukturerhaltend an
  Linear zurückgeben

## 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
$env:AUTH_BOOTSTRAP_USERNAME = "admin"
$env:AUTH_BOOTSTRAP_PASSWORT = "<eigenes Startpasswort mit mindestens 12 Zeichen>"
docker compose up --build --detach
```

Danach:

- Frontend: <http://localhost:3001>
- API-Healthcheck: <http://localhost:3001/health> (über den Next.js-Rewrite)

Beim ersten Start erzeugen diese beiden Variablen genau einen Administrator,
solange die Benutzertabelle noch leer ist. Danach werden sie ignoriert. Für
einen dauerhaften Serverbetrieb gehören die Werte in eine nicht versionierte
`.env` neben `compose.yaml`; Details stehen unter
[Anmeldung und Benutzerverwaltung](docs/authentication.md).

Die Express-API ist nicht auf dem Host veröffentlicht. Sämtliche fachlichen
API-Routen verlangen eine gültige Anmeldung; der Zugriff läuft über den
Rewrite im Web-Dienst.

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.

Das Laufzeit-Image läuft als Benutzer `node` (UID 1000), nicht als root. Ein
`data/`-Verzeichnis, das ein früherer root-Container angelegt hat, braucht
deshalb einmalig `sudo chown -R 1000:1000 data` auf dem Host.

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

`compose.yaml` startet den Produktionsstand: gebautes `dist/` und `next start`,
ohne Quellcode-Mounts und ohne Datei-Watcher, mit Speichergrenzen und ohne
root-Rechte im Container. Details stehen in
[Deployment und Betrieb](docs/deployment.md).

Für die Entwicklung mit Hot Reload gibt es einen eigenen Stack mit
Quellcode-Mounts und Watchern:

```powershell
docker compose -f compose.dev.yaml up --build --detach
docker compose -f compose.dev.yaml logs --follow
docker compose -f compose.dev.yaml down
```

Die Watcher darin laufen im Polling-Modus, weil Bind-Mounts unter Windows und
macOS keine inotify-Events durchreichen. Das kostet dauerhaft CPU, auch wenn
niemand die Anwendung benutzt — deshalb gehört dieser Stack nicht auf einen
Server.

## Direkte lokale Entwicklung

Voraussetzungen:

- Node.js 24
- npm

```powershell
npm ci
npm run db:migrate
npm run db:verify:circuit-schema
$env:AUTH_BOOTSTRAP_USERNAME = "admin"
$env:AUTH_BOOTSTRAP_PASSWORT = "<eigenes Startpasswort mit mindestens 12 Zeichen>"
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)
- [Seitenansicht und PDF-Export](docs/print-view.md)
- [Gebäudestruktur und Raumflächen](docs/building-structure.md)
- [Grobe Leistungsbilanz](docs/estimate-balance.md)
- [Leitungsberechnung](docs/cable-sizing-module.md)
- [Anmeldung und Benutzerverwaltung](docs/authentication.md)
- [Entwicklungs- und Contributor-Workflow](docs/development-workflow.md)
- [Bekannte Einschränkungen](docs/circuit-list-editor-known-limitations.md)
- [Revit-Integration über Linear-Excel](docs/spec/revit-excel-integration-requirements.md)
- [Phase-14-Plan R0–R10](docs/spec/revit-excel-phase-14-plan.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.