jappel/leistungsbilanz-ts
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrite project documentation

Browse Source
This commit is contained in:
Julian Appel
2026-07-23 21:05:43 +02:00
parent 30d6f1a2e1
commit 6b6d2c2a42
17 changed files with 535 additions and 221 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+90 -194
View File
@@ -1,225 +1,121 @@
# Leistungsbilanz – Hauptdokumentation
# Leistungsbilanz
Diese Anwendung unterstützt die elektrische Fachplanung (TGA/ELT) bei der Erstellung und Pflege von Leistungsbilanzen und Stromkreislisten.
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.
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.
Das Projekt befindet sich in aktiver Entwicklung. Der lokale Entwicklungsbetrieb
mit SQLite und Docker Compose ist unterstützt. Ein Produktionsdeployment,
persistentes Undo/Redo, Projektversionen und der Revit-/IFCGUID-Datenaustausch sind
noch nicht implementiert.
## Sinn und Ziel der Anwendung
## Unterstützter Arbeitsablauf
Die Anwendung soll Planer dabei unterstützen:
- Projekte, Verteilungen, Etagen und Räume verwalten
- pro Verteilung eine Stromkreisliste mit festen Bereichen bearbeiten
- 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 innerhalb der aktuellen Editorsitzung rückgängig machen und wiederholen
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.
## Technik
Fachlich stehen folgende Begriffe im Zentrum:
- 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
- Projekt
- Verteilung
- Stromkreisliste
- Verbraucher/Gerät
- installierte Leistung
- Gleichzeitigkeitsfaktor
- berechnete Leistung
- Spannung (1-phasig / 3-phasig)
- Strom
## Schnellstart mit Docker
## Anforderungsbasis
Voraussetzungen:
Die fachliche Basis stammt aus [docs/electrical-load-balance-requirements-context-dump.md](docs/electrical-load-balance-requirements-context-dump.md).
- Git
- Docker Desktop mit Docker Compose
Die folgende Liste fasst die zentralen Anforderungen zusammen und zeigt den aktuellen Umsetzungsstand im Code.
```powershell
git clone <repository-url>
Set-Location leistungsbilanz-ts
docker compose up --build --detach
```
## Anforderungsliste mit Ist-Stand
Danach:
### 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`.
- Frontend: <http://localhost:3001>
- API-Healthcheck: <http://localhost:3000/health>
### 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`.
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.
### 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`).
```powershell
docker compose ps
docker compose logs --follow
docker compose down
```
### 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`.
Der Compose-Stack startet Entwicklungsserver mit Quellcode-Mounts. Er ist kein
Produktionsdeployment. Details stehen in
[Deployment und Betrieb](docs/deployment.md).
### 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`.
## Direkte lokale Entwicklung
### 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`.
Voraussetzungen:
### 7) Geräte zwischen global und Projekt kopieren
- Anforderung: Kopieren in beide Richtungen.
- Status: Erfüllt.
- Umsetzung: `copyGlobalDeviceToProject` und `copyProjectDeviceToGlobal`.
- Node.js 22
- npm
### 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.
```powershell
npm ci
npm run db:migrate
npm run db:verify:circuit-schema
npm run dev:api
```
### 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`.
In einem zweiten Terminal:
### 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.
```powershell
npm run dev:web
```
### 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.
Frontend und API laufen anschließend auf denselben Ports wie im Docker-Setup.
### 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.
## Qualitätssicherung
### 13) Sortieren, Filtern, Bulk-Edit
- Anforderung: erweiterte Tabellenfunktionen.
- Status: Erfüllt (Basisumfang).
- Umsetzung: Filterfeld, Sortierfeld/-richtung und Sammeländerung für Auswahlwerte.
```powershell
npm test
npm run build:api
npm run build:web
npx tsc --noEmit -p tsconfig.next.json
```
### 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.
Wichtige Datenbankbefehle:
### 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.
```powershell
npm run db:backup
npm run db:migrate
npm run db:verify:circuit-schema
npm run db:generate
```
### 16) Spaltensteuerung in der Tabelle
- Anforderung: Attribute ein-/ausblenden und Spaltenreihenfolge ändern.
- Status: Erfüllt.
- Umsetzung: Spaltenmanager in `circuit-lists/page.tsx`.
`db:backup` verwendet die SQLite-Online-Backup-API und prüft das Ergebnis auf
Integrität und Fremdschlüsselverletzungen. Vor jeder Migration einer bestehenden
Datenbank ist ein Backup erforderlich.
### 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.
`db:migrate:legacy-consumers` und `db:backfill:sections` sind ausschließlich
Upgrade-Werkzeuge für ältere Datenbanken. Neue Installationen benötigen sie nicht.
### 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`.
## Dokumentation
## Technische Architektur (für neue Entwickler)
- [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)
### 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
### Mit Docker (empfohlen fuer kurze Sessions)
Voraussetzung: Docker Desktop mit aktivem Docker-Compose-Plugin.
1. Sicherstellen, dass keine direkt gestartete API und kein direkt gestartetes Frontend mehr auf Port 3000/3001 laufen.
2. `npm run docker:up` (baut und startet beide Container im Hintergrund)
3. Frontend unter `http://localhost:3001` oeffnen.
Beim Start fuehrt der API-Container ausstehende Drizzle-Migrationen und die Circuit-First-Schemapruefung aus. Die vorhandene SQLite-Datenbank wird ueber `./data:/app/data` eingebunden und bleibt nach `npm run docker:down` erhalten. Quellcodeaenderungen unter `src/` werden von beiden Entwicklungsservern automatisch erkannt.
Weitere Docker-Befehle:
- `npm run docker:down` - Frontend und API stoppen
- `npm run docker:logs` - laufende Containerlogs anzeigen (`Ctrl+C` beendet nur die Logansicht)
- `docker compose ps` - Status und Healthchecks anzeigen
- `Invoke-WebRequest http://localhost:3000/health` - API-Healthcheck pruefen
Bewusster Datenbank-Reset unter PowerShell:
1. `npm run docker:down`
2. `npm run db:backup`
3. `Remove-Item -LiteralPath .\data\leistungsbilanz.db`
4. `npm run docker:up`
Der Reset entfernt die aktive lokale Datenbank. Die zuvor erzeugte Sicherung bleibt unter `data/backups/` erhalten.
### Ohne Docker
1. `npm install`
2. `npm run db:migrate`
3. `npm run db:verify:circuit-schema`
4. `npm run dev:api` (API auf Port 3000)
5. In einem zweiten Terminal `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](docs/electrical-load-balance-requirements-context-dump.md)
- Abgleich „Anforderung vs. Implementierung“: [docs/anforderungs-abgleich.md](docs/anforderungs-abgleich.md)
## Circuit-List Editor Dokumentation
- Architektur: [docs/circuit-list-editor-architecture.md](docs/circuit-list-editor-architecture.md)
- Interaktionen: [docs/circuit-list-editor-interactions.md](docs/circuit-list-editor-interactions.md)
- API: [docs/circuit-list-editor-api.md](docs/circuit-list-editor-api.md)
- Migration: [docs/circuit-list-editor-migration.md](docs/circuit-list-editor-migration.md)
- Bekannte Limitierungen: [docs/circuit-list-editor-known-limitations.md](docs/circuit-list-editor-known-limitations.md)
Diese Dokumente beschreiben den aktuellen circuit-first Editorstand und dienen als sichere Entwicklungsbasis fuer Folgeschritte.
Für LLM-gestützte Änderungen enthält [AGENTS.md](AGENTS.md) die verbindlichen
Domänenregeln, unterstützten Einstiegspunkte und Architekturgrenzen.