rewrite

README.md

@@ -1,31 +1,177 @@
-# Leistungsbilanz
+# Leistungsbilanz – Hauptdokumentation
 
-TypeScript backend for electrical power-balance planning.
+Diese Anwendung unterstützt die elektrische Fachplanung (TGA/ELT) bei der Erstellung und Pflege von Leistungsbilanzen und Stromkreislisten.
 
-## Setup
+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](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`
-5. `npm run dev:web`
+4. `npm run dev:api` (API auf Port 3000)
+5. `npm run dev:web` (Frontend auf Port 3001)
 
-## Commands
+## Wichtige Befehle
 
-- `npm run dev:api`: Start API server on port 3000
-- `npm run dev:web`: Start Next.js frontend on port 3001
-- `npm run build:api`: TypeScript backend build
-- `npm run build:web`: Next.js frontend build
-- `npm run test`: Calculation tests
-- `npm run db:generate`: Generate migrations
-- `npm run db:migrate`: Apply migrations
+- `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
 
-## Current API
+## Ergänzende Dokumente
 
-- `GET /health`
-- `GET /api/projects`
-- `POST /api/projects`
-- `GET /api/projects/:projectId/distribution-boards`
-- `POST /api/projects/:projectId/distribution-boards`
-- `GET /api/consumers/projects/:projectId`
-- `POST /api/consumers`
+- Anforderungen (Quelle): [docs/electrical-load-balance-requirements-context-dump.md](docs/electrical-load-balance-requirements-context-dump.md)
+- Abgleich „Anforderung vs. Implementierung“: [docs/anforderungs-abgleich.md](docs/anforderungs-abgleich.md)