Merge remote-tracking branch 'origin/main' into feature/cable-sizing

docs/current-architecture.md

@@ -27,9 +27,18 @@ Next.js App Router ── /api/* Rewrite ──▶ Express API :3000
                               data/leistungsbilanz.db (SQLite)
 ```
 
-Im Docker-Entwicklungssetup laufen Frontend und API in getrennten Containern. Das
-Frontend leitet `/api/*` über `API_INTERNAL_URL` an die API weiter. Die Datenbank
-liegt über einen Host-Mount außerhalb des Containers.
+In beiden Docker-Stacks laufen Frontend und API in getrennten Containern.
+`compose.yaml` startet den gebauten Stand, `compose.dev.yaml` die Entwicklung
+mit Hot Reload. Das Frontend leitet `/api/*` über `API_INTERNAL_URL` an die API
+weiter; beim gebauten Stand wird das Ziel zur Build-Zeit festgelegt. Die
+Datenbank liegt über einen Host-Mount außerhalb des Containers.
+
+Neue IDs für Stromkreise, Gerätezeilen, Gruppen und Verteilerkomponenten erzeugt
+der Editor über `src/frontend/utils/client-id.ts` (`createClientId`). Die
+Hilfsfunktion nutzt `crypto.randomUUID()`, sofern verfügbar, andernfalls
+`crypto.getRandomValues()` mit UUID-v4-Format. Damit funktioniert das Anlegen
+auch beim HTTP-Zugriff im LAN ohne sicheren Browserkontext. Die IDs entstehen
+vor dem Command und bleiben über Undo/Redo unverändert.
 
 ## Wichtige Einstiegspunkte
 
@@ -232,8 +241,9 @@ und Historienstapel teilen dieselbe Transaktion. Create, Import aus der globalen
 Gerätebibliothek und Delete laufen über dieselbe Command-Grenze; ihre Antworten
 liefern Gerät und aktualisierten Historienstand an die Projektseite zurück.
 `project.update-settings` versioniert Projektname, interne und externe
-Projektnummer, Bauherr, Beschreibung, die Kennzeichnung als öffentliches
-Gebäude, beide Standardspannungen sowie die im Projekt freigeschalteten
+Projektnummer, Bauherr, Beschreibung, die Deckblattangaben (Anschrift,
+Leistungsphase, Projektleitung, Bearbeitung; Schema-Version 3, Migration
+`0008`), die Kennzeichnung als öffentliches Gebäude, beide Standardspannungen sowie die im Projekt freigeschalteten
 Verteiler-Netzarten als eine atomare Änderung. Die Gebäudekennzeichnung ist
 der spätere Eingang für die Auswahl halogenfreier Kabel und Leitungen. Der
 Systemkatalog besteht aus `AV`, `SV`, `EV`, `USV`, `MSR` und `SiBe`; mindestens
@@ -245,22 +255,55 @@ Werte, Revision und Historienstapel gemeinsam. `PUT /api/projects/:projectId`
 verlangt deshalb `expectedRevision`, liefert Projekt plus aktualisierten
 Historienstand und besitzt keinen separaten direkten Settings-Schreibweg mehr.
 Kommando- und Snapshot-Payloads müssen dem aktuellen Baseline-Schema entsprechen.
-Die Projektseite zeigt Verteilungen, Etagen und Räume als kompakte
-Bestandsübersichten; ihre versionierten Erstellwege öffnen beschriftete Modals
-statt dauerhafter Eingabezeilen. Projektgeräte werden als durchsuchbare,
+Die Projektseite zeigt Verteilungen als kompakte Bestandsübersicht; ihre
+versionierten Erstellwege öffnen beschriftete Modals statt dauerhafter
+Eingabezeilen. Gebäude, Etagen und Räume werden auf der eigenen Seite
+„Gebäudestruktur“ (`/projects/:projectId/struktur`) gepflegt; Etagen können
+einem Gebäude zugeordnet sein (`docs/building-structure.md`). Projektgeräte werden als durchsuchbare,
 fünfspaltige Übersicht dargestellt. Manuelle Anlage, Übernahme aus der globalen
 Bibliothek und vollständige Bearbeitung erfolgen in einem gemeinsamen Modal.
 Die anschließende Vorschau verknüpfter Stromkreiszeilen bleibt davon getrennt,
 damit Änderungen weiterhin niemals still synchronisiert werden.
-`GET /api/projects/:projectId/export` verpackt denselben vollständigen
-Projektzustand in ein portables, format- und schema-versioniertes JSON-Dokument
-mit SHA-256-Prüfsumme. `POST /api/projects/:projectId/import` prüft Format,
-Snapshot-Relationen und Prüfsumme vor jedem Schreibzugriff. Der Modus `replace`
-läuft über `project.restore-state` und ist dadurch eine atomare, dauerhaft
-rückgängig machbare Projektrevision. Der Modus `duplicate` ordnet Projekt-,
+Die Karten Verteilungen und Projektgeräte besitzen je eine einklappbare
+Filterleiste im Stil der PM-App (Suche, Mehrfachauswahl für Etage/Netzart bzw.
+Kategorie/Phasenzahl/Kostengruppe, „Zurücksetzen“, Anzeige „x von y“); die
+Filterlogik liegt rein in `src/frontend/utils/overview-filters.ts`, der
+Einklappzustand je Karte in `localStorage`. Aktionen verwenden wie der Editor
+`IconButton`/`IconLink`.
+Die allgemeinen Anwendungskarten verwenden in `src/app/globals.css` einen
+gleichmäßigen Rahmen, 16-px-Rundungen und einen Schatten mit eigener
+Dark-Mode-Abstimmung. Bootstrap-Karten mit `shadow-sm` nutzen denselben
+Schatten; der Stromkreis-Grid bleibt eine eigenständige Komponente.
+Die Verteilersuche berücksichtigt Name, Verteilernummer, Örtlichkeit und
+Etagenname; die Gerätesuche
+Name, Anzeigename, Kategorie einschließlich deutscher Bezeichnung, Anschlussart
+und Kostengruppe. Der Gerätefilter „Anschluss“ wählt zwischen 1- und 3-phasig.
+Mehrere Werte innerhalb eines Filters gelten alternativ, verschiedene Filter
+und die Suche gemeinsam. Eine leere Auswahl bedeutet „Alle“; fehlende
+Zuordnungen sind über „Ohne Etage“, „Nicht festgelegt“ beziehungsweise
+„Ohne Kostengruppe“ auswählbar. Nicht mehr angebotene Auswahlwerte werden bei
+der Filterung ignoriert. „Zurücksetzen“ leert die Filter der jeweiligen Karte.
+Beim Einklappen bleiben aktive Filter wirksam und durch „Filter aktiv“ sichtbar.
+Nur der Einklappzustand wird je Kartentyp im Browser gespeichert; Suchbegriffe
+und Filterauswahl werden nicht dauerhaft gespeichert. Die Filter ändern keine
+Projektdaten und erzeugen keine Revisionen. Das Löschen eines Projektgeräts
+erfordert eine Bestätigung mit dessen Namen und verwendet weiterhin den
+bestehenden persistenten Projektbefehl.
+
+`GET /api/projects/:projectId/export` verpackt den vollständigen portablen
+Projektzustand in ein format- und schema-versioniertes JSON-Dokument mit
+SHA-256-Prüfsumme. Transferformat 2 enthält zusätzlich alle Grobbilanzen,
+ohne sie in das logische Snapshot-Schema aufzunehmen; Format 1 bleibt ohne
+Grobbilanzen importierbar. `POST /api/projects/:projectId/import` prüft Format,
+Snapshot-Relationen, Grobbilanzen und Prüfsumme vor jedem Schreibzugriff. Der
+Modus `replace` läuft über `project.restore-state` Version 2 und ersetzt den
+Projektzustand und die Grobbilanzen atomar und dauerhaft rückgängig machbar.
+Normale Snapshot-Restores verwenden weiterhin Version 1 und lassen
+Grobbilanzen unverändert. Der Modus `duplicate` ordnet Projekt-,
 Struktur-, Gruppen-, Verteilerkomponenten-, Raum-, Stromkreis- und
-Gerätezeilen-UUIDs sowie Schutzgeräte-Referenzen vollständig neu zu und legt
-die Kopie mit Revision `0` in einer Transaktion an. Fachliche Verknüpfungen
+Gerätezeilen-UUIDs sowie Schutzgeräte-Referenzen und die IDs aller Grobbilanzen
+vollständig neu zu und legt die Kopie mit Revision `0` in einer Transaktion an.
+Fachliche Verknüpfungen
 innerhalb des unterstützten Laufzeitmodells bleiben
 erhalten. Die
 Projektübersicht verwendet dafür den separaten Collection-Endpunkt
@@ -416,7 +459,16 @@ wieder her.
 verteilerweiten Gleichzeitigkeitsfaktor gemeinsam und stellt alle Werte über
 dauerhaftes Undo/Redo wieder her. Der Faktor liegt zwischen `0` und `1` und
 ist für bestehende sowie neu angelegte Verteilungen standardmäßig `1`.
-Snapshot-Schema 5 enthält zusätzlich den manuellen Mengenanteil jeder
+Derselbe Befehl versioniert die Felder der Verteiler-Infokarte
+(`boardNumber`, `location`, `fedFrom`, `remark`, Migration `0007`). Die
+Infokarte liegt im Bearbeiten-Dialog der Verteilung; die Werte sind lokale
+Planungswerte und sollen später über den Revit-Abgleich nur nach Vorschau und
+ausdrücklicher Bestätigung vorbelegt werden. `fedFrom` ist vorerst Freitext.
+Snapshot-Schema 7 enthält zusätzlich die Gebäude und die Gebäudezuordnung
+der Etagen; ältere Versionen werden ohne Gebäude hochgestuft.
+Snapshot-Schema 6 enthält diese Felder und die Deckblattangaben des
+Projekts; ältere Versionen werden mit `null`
+hochgestuft. Snapshot-Schema 5 enthält zusätzlich den manuellen Mengenanteil jeder
 Gerätezeile. Version 4 wird mit `manualQuantity = quantity` hochgestuft und
 enthält bereits den vollständigen externen Modellzustand
 aus Quelle, Batches, Raum-Mappings und Objekten. Es enthält außerdem die
@@ -498,7 +550,7 @@ Revision und Undo/Redo. Details, Rechenweg und Prüfnachweis der Tabellen:
   `toLowerCase()` gegen das vollständige Register der Stromkreisliste und wird
   von jedem Anlage-/Umbenennungspfad für Stromkreise und Verteilerkomponenten
   aufgerufen, auch dort, wo zuvor kein Vorab-Check existierte. Snapshot- und
-  Transfer-Integration verwenden aktuell Snapshot-Schema 5. Persistente
+  Transfer-Integration verwenden aktuell Snapshot-Schema 6. Persistente
   Insert/Delete/Update-Commands für veränderliche Verteilerkomponenten,
   Gruppen einschließlich befüllter Unterbäume sowie vollständige
   Gruppensortierung sind integriert. Der Editor zeigt die geschützte Struktur
@@ -517,6 +569,10 @@ bei einem späteren Wechsel trotzdem einen eigenen PostgreSQL-Adapter.
 
 ## Revit-CSV-Grundlage
 
+**Zurückgestellt:** Die weitere Revit-Arbeit wird später angegangen, dann
+über den CSV-Export/-Import des Linear-Plugins in Revit statt über Dynamo.
+Details: [Revit-CSV-Anforderungen, Abschnitt 1](spec/revit-csv-integration-requirements.md).
+
 Der reine Adapter unter `src/external-model/csv` validiert die projektweite
 Transport- und Mappingkonfiguration und parst UTF-8-CSV verlustarm in eine
 klassifizierte Zellmatrix. Er erkennt Metadaten, Header, Passthrough-, Objekt-
@@ -526,7 +582,7 @@ einschließlich BOM, CRLF und Quotierung bytegleich zurück. Der lokale Befehl
 
 `external_csv_configurations` enthält höchstens eine versionierte Konfiguration
 je Projekt. `external-csv-configuration.update` schreibt Anlage, Änderung oder
-Entfernung zusammen mit Revision und persistentem Undo/Redo. Snapshot-Schema 5,
+Entfernung zusammen mit Revision und persistentem Undo/Redo. Snapshot-Schema 6,
 Restore und portabler Projekttransfer enthalten diesen Zustand; beim Duplizieren
 werden Konfigurations-UUID und Projektlink remapped.