leistungsbilanz-ts/README.md

Leistungsbilanz – Hauptdokumentation

Diese Anwendung unterstützt die elektrische Fachplanung (TGA/ELT) bei der Erstellung und Pflege von Leistungsbilanzen und Stromkreislisten.

Sie ist als praxisnahe Webanwendung für kleine Teams gedacht (ca. 2–3 gleichzeitige Nutzer), mit Schwerpunkt auf schneller tabellarischer Bearbeitung statt komplexer Enterprise-Strukturen.

Sinn und Ziel der Anwendung

Die Anwendung soll Planer dabei unterstützen:

1. Projekte anzulegen und zu verwalten.
2. Verteilungen pro Projekt anzulegen.
3. Verbraucher strukturiert in Stromkreislisten zu erfassen.
4. Installierte Leistung, Gleichzeitigkeitsleistung und Strom automatisch zu berechnen.
5. Gerätevorlagen global sowie projektbezogen zu verwalten und wiederzuverwenden.
6. Planungsdaten schrittweise zu vervollständigen, ohne unnötige Pflichtfeldhürden.

Fachlich stehen folgende Begriffe im Zentrum:

• Projekt
• Verteilung
• Stromkreisliste
• Verbraucher/Gerät
• installierte Leistung
• Gleichzeitigkeitsfaktor
• berechnete Leistung
• Spannung (1-phasig / 3-phasig)
• Strom

Anforderungsbasis

Die fachliche Basis stammt aus docs/electrical-load-balance-requirements-context-dump.md.

Die folgende Liste fasst die zentralen Anforderungen zusammen und zeigt den aktuellen Umsetzungsstand im Code.

Anforderungsliste mit Ist-Stand

1) Projektverwaltung

• Anforderung: Projekte erstellen und anzeigen.
• Status: Erfüllt.
• Umsetzung: UI in src/app/projects/page.tsx, API in src/server/controllers/project.controller.ts.

2) Verteilungen pro Projekt

• Anforderung: Mehrere Verteilungen pro Projekt.
• Status: Erfüllt.
• Umsetzung: src/server/controllers/distribution-board.controller.ts, src/app/projects/[projectId]/page.tsx.

3) Genau eine Stromkreisliste pro Verteilung

• Anforderung: Jede Verteilung besitzt genau eine Stromkreisliste.
• Status: Erfüllt.
• Umsetzung: Beim Erstellen einer Verteilung wird automatisch eine Stromkreisliste angelegt (createDistributionBoard + CircuitListRepository.createForDistributionBoard).

4) Tabellarische Stromkreisbearbeitung

• Anforderung: Einträge als Tabellenzeilen anlegen, bearbeiten, löschen.
• Status: Erfüllt.
• Umsetzung: src/app/projects/[projectId]/circuit-lists/page.tsx, API src/server/controllers/consumer.controller.ts.

5) Bis zu drei parallele Stromkreislisten

• Anforderung: 1–3 Listen parallel, Standard = 1, inkl. Kopieren zwischen Listen.
• Status: Erfüllt.
• Umsetzung: activeListCount, Slot-Logik und Kopierfunktionen in src/app/projects/[projectId]/circuit-lists/page.tsx.

6) Geräteverwaltung global + projektbezogen

• Anforderung: Globale Geräteliste und Projektgeräteliste.
• Status: Erfüllt.
• Umsetzung: Seiten src/app/projects/page.tsx und src/app/projects/[projectId]/page.tsx, API-Routen für global-devices und project-devices.

7) Geräte zwischen global und Projekt kopieren

• Anforderung: Kopieren in beide Richtungen.
• Status: Erfüllt.
• Umsetzung: copyGlobalDeviceToProject und copyProjectDeviceToGlobal.

8) name + displayName bei Geräten

• Anforderung: Interner Name und Anzeigename getrennt.
• Status: Erfüllt.
• Umsetzung: DB-Schema, Validierung, UI und Copy-Flows sind angepasst.

9) Geräte-Link an Stromkreiseinträgen

• Anforderung: Eintrag kann mit Projektgerät verknüpft/entkoppelt werden; verknüpfte Einträge aktualisieren sich bei Geräteänderung.
• Status: Erfüllt.
• Umsetzung: Felder projectDeviceId + isLinkedToDevice, Sync in syncLinkedConsumersFromProjectDevice.

10) Unvollständige Einträge zulassen

• Anforderung: Einträge sollen grundsätzlich auch unvollständig möglich sein.
• Status: Teilweise erfüllt.
• Umsetzung: Backend akzeptiert optionale Kernfelder und setzt Defaults.
• Hinweis: Das manuelle Schnellformular im UI verlangt weiterhin einen Namen für den direkten Anlege-Flow.

11) Add Count (mehrere Einträge aus einem Gerät erzeugen)

• Anforderung: getrennt von quantity.
• Status: Erfüllt.
• Umsetzung: addCount bei „Projektgerät übernehmen“ in der Stromkreislistenansicht.

12) Duplizieren und Kopieren von Einträgen

• Anforderung: Duplizieren in derselben Liste + Kopieren in andere Listen.
• Status: Erfüllt.
• Umsetzung: Zeilenaktionen „Dupl.“ und Listenkopie, plus Auswahl-Kopie.

13) Sortieren, Filtern, Bulk-Edit

• Anforderung: erweiterte Tabellenfunktionen.
• Status: Erfüllt (Basisumfang).
• Umsetzung: Filterfeld, Sortierfeld/-richtung und Sammeländerung für Auswahlwerte.

14) Räume und Etagen

• Anforderung: Projektbezogene Räume/Etagen und Zuordnung zu Einträgen.
• Status: Erfüllt.
• Umsetzung: Floors/Rooms in Projektansicht und Raumzuordnung in Stromkreisliste.

15) Projektspezifische Spannungsstandards (1-ph/3-ph)

• Anforderung: 230 V / 400 V als Standard, in Projekteigenschaften editierbar, in Berechnung verwendet.
• Status: Erfüllt.
• Umsetzung: Projekteinstellungen + Nutzung in Berechnungsservice.

16) Spaltensteuerung in der Tabelle

• Anforderung: Attribute ein-/ausblenden und Spaltenreihenfolge ändern.
• Status: Erfüllt.
• Umsetzung: Spaltenmanager in circuit-lists/page.tsx.

17) Feste Auswahllisten für Domänenfelder

• Anforderung: feste Werte für Felder wie deviceType, phaseType, Schutz/Kabel usw.
• Status: Erfüllt.
• Umsetzung: zentrale Listen in src/shared/constants/consumer-option-lists.ts, Validierung über z.enum(...), UI-Selects.

18) Tests über reine Formeln hinaus

• Anforderung: zusätzliche Tests für Link-/Eintragsverhalten.
• Status: Erfüllt.
• Umsetzung: tests/consumer-linking.service.test.ts und tests/consumer-schema-options.test.ts.

Technische Architektur (für neue Entwickler)

Backend

• Node.js + Express
• Einstieg: src/server/index.ts
• API-Module:
  • Projekte/Verteilungen/Räume/Etagen
  • Verbraucher (Stromkreiseinträge)
  • globale und projektbezogene Geräte

Frontend

• Next.js (App Router) + React + Bootstrap
• Hauptseiten:
  • src/app/projects/page.tsx (Projektliste + globale Geräte)
  • src/app/projects/[projectId]/page.tsx (Projektdetails, Verteilungen, Räume/Etagen, Projektgeräte)
  • src/app/projects/[projectId]/circuit-lists/page.tsx (Stromkreislisten-Editor)

Datenbank

• SQLite + Drizzle ORM
• Schema unter src/db/schema
• Migrationen unter src/db/migrations

Domänen- und Rechenlogik

• Berechnung: src/domain/calculations/power-calculation.ts
• Anreicherung/Businesslogik: src/domain/services/power-balance.service.ts
• Geräte-Link-Logik: src/domain/services/consumer-linking.service.ts

Schneller Entwicklungsstart

1. npm install
2. npm run db:generate
3. npm run db:migrate
4. npm run dev:api (API auf Port 3000)
5. npm run dev:web (Frontend auf Port 3001)

Wichtige Befehle

• npm run dev:api – API lokal starten
• npm run dev:web – Frontend lokal starten
• npm run build:api – Backend bauen
• npm run build:web – Frontend bauen
• npm test – Testlauf
• npm run db:generate – Migrationen generieren
• npm run db:migrate – Migrationen ausführen

Circuit-First lokale Migration

• npm run db:backup – lokale SQLite sichern
• npm run db:migrate – pending Migrationen ausführen
• npm run db:verify:circuit-schema – Circuit-First Tabellenprüfung
• npm run db:backfill:sections – Default-Sections für bestehende Listen anlegen
• npm run db:migrate:legacy-consumers – Legacy-Consumers explizit in Circuit-First überführen

Siehe auch: docs/local-db-circuit-first-migration.md

Ergänzende Dokumente

• Anforderungen (Quelle): docs/electrical-load-balance-requirements-context-dump.md
• Abgleich „Anforderung vs. Implementierung“: docs/anforderungs-abgleich.md

Circuit-List Editor Dokumentation

• Architektur: docs/circuit-list-editor-architecture.md
• Interaktionen: docs/circuit-list-editor-interactions.md
• API: docs/circuit-list-editor-api.md
• Migration: docs/circuit-list-editor-migration.md
• Bekannte Limitierungen: docs/circuit-list-editor-known-limitations.md

Diese Dokumente beschreiben den aktuellen circuit-first Editorstand und dienen als sichere Entwicklungsbasis fuer Folgeschritte.