From 60771b59296808206f0133e29849cbd59d6c7857 Mon Sep 17 00:00:00 2001 From: Julian Appel Date: Sun, 3 May 2026 19:14:44 +0200 Subject: [PATCH] rewrite --- README.md | 188 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 167 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 13d9ec3..f9d378b 100644 --- a/README.md +++ b/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)