leistungsbilanz-ts/docs/current-architecture.md

Aktuelle Systemarchitektur

Status und unterstützter Pfad

Der unterstützte Editor ist Circuit-First:

Project → DistributionBoard → CircuitList → CircuitSection → Circuit → CircuitDeviceRow

Ein Stromkreis ist nicht dasselbe wie eine Gerätezeile. BMK, Schutz- und Kabeldaten gehören zum Stromkreis; Last-, Raum- und Kategoriedaten gehören zur Gerätezeile.

Die frühere Consumer-Oberfläche und ihre API sind entfernt. Die Tabelle consumers sowie Mappings und Reports bleiben ausschließlich erhalten, damit ältere Datenbanken über den expliziten Upgrade-Befehl migriert und geprüft werden können.

Laufzeit

Browser :3001
    │
    ▼
Next.js App Router ── /api/* Rewrite ──▶ Express API :3000
                                              │
                                              ▼
                                    Repository / Transaktion
                                              │
                                              ▼
                              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.

Wichtige Einstiegspunkte

• src/app/projects/page.tsx – Projektliste und globale Gerätebibliothek
• src/app/projects/[projectId]/page.tsx – Projektstammdaten, Verteilungen, Räume und Projektgeräte
• src/app/projects/[projectId]/circuit-lists/[circuitListId]/tree-edit/page.tsx – unterstützte Editorroute
• src/frontend/components/circuit-tree-editor.tsx – Editorzustand, Befehlsausführung, Drag-and-drop und sitzungslokales Undo/Redo
• src/frontend/components/circuit-grid-*.ts – reine Grid-Projektion, Zellbesitz, Einfügen und Sicherheitsregeln
• src/frontend/utils/api.ts – typisierte Frontend-API-Aufrufe
• src/server/index.ts und src/server/routes/ – API-Komposition
• src/domain/services/ – fachliche Command- und Synchronisierungsregeln
• src/db/repositories/ – Abfragen, Persistenzmapper und Transaktionsadapter
• src/db/schema/ und src/db/migrations/ – SQLite-Schema und Migrationen

Daten- und Befehlsfluss

1. Das Grid projiziert den geladenen Circuit-Tree in sichtbare Zeilen.
2. Eine Benutzeraktion wird im Frontend validiert und als API-Befehl gesendet.
3. Controller validieren Requestdaten mit Zod.
4. Domain-Services prüfen fachliche Regeln wie BMK-Eindeutigkeit, Abschnittszuordnung und Reserveverhalten.
5. Repositories schreiben Daten. Kritische Mehrfachschreibvorgänge besitzen explizite SQLite-Transaktionsadapter mit Commit-/Rollback-Integrationstests.
6. Das Frontend lädt den Circuit-Tree neu und stellt Auswahl beziehungsweise Viewport soweit möglich wieder her.

Die React-Historie ist derzeit sitzungslokal. Das Datenmodell besitzt bereits einen projektbezogenen Revisionszähler sowie getrennte Revision-/Change-Set- Tabellen. Ein getestetes Repository kann diese Historienmetadaten optimistisch und atomar fortschreiben. Vorwärts- und Rückwärtskommandos besitzen einen versionierten, JSON-sicheren Umschlag; Typ und Payload können dadurch nach einem Neustart verlustfrei rekonstruiert werden. Konkrete Fachkommandos und bestehende Fachoperationen sind aber noch nicht allgemein an diese Grenze angeschlossen. Für Circuit- und Gerätezeilen-Feldänderungen existieren interne Command-Stores, die Fachänderung, automatisch erzeugtes inverses Kommando und Revision gemeinsam committen beziehungsweise zurückrollen können. Gerätezeilen-Kommandos bewahren dabei auch lokale ProjectDevice-Overrides und prüfen Projektzugehörigkeit von Verknüpfungen und Räumen. Projektweite, persistente Undo-/Redo-Stacks verwalten die zulässige LIFO-Reihenfolge und verwerfen den Redo-Zweig bei einem neuen Benutzerkommando. Ihr Status ist über GET /api/projects/:projectId/history lesbar. Die schreibenden Command-Stores sind noch nicht über die API oder das Grid aktiviert; serverseitiges Undo/Redo ist daher noch nicht verfügbar.

Projektgeräte

ProjectDevice verwendet ausschließlich die kanonischen Circuit-First-Felder: phaseType, powerPerUnit, simultaneityFactor, cosPhi, remark sowie optionale technische und kategorisierende Felder.

Beim Einfügen entsteht eine verknüpfte CircuitDeviceRow. Der Anzeigename wird kopiert, aber nicht still synchronisiert. Spätere Änderungen am Projektgerät werden als Diff angezeigt und nur für ausdrücklich gewählte Felder und Zeilen übernommen.

Die globale Gerätebibliothek ist ein einfacher, datenbankweiter Vorlagenbestand. Kopieren in ein Projekt erzeugt ein eigenständiges Projektgerät.

Persistenz und Migration

• SQLite ist die aktuell unterstützte Datenbank.
• Fremdschlüssel werden für jeden Datenbankkontext aktiviert.
• npm run db:migrate wendet Drizzle-Migrationen an.
• npm run db:verify:circuit-schema prüft erforderliche und entfernte Spalten.
• npm run db:backup erzeugt ein konsistentes und verifiziertes Online-Backup.
• Angewendete Migrationen werden niemals nachträglich verändert.
• db:migrate:legacy-consumers ist Upgrade-Werkzeug, kein Anwendungspfad.

PostgreSQL ist bewusst nicht implementiert. Die Domainregeln und Transaktionsgrenzen sollen portabel bleiben; Schema und Betriebsmodell benötigen bei einem späteren Wechsel trotzdem einen eigenen PostgreSQL-Adapter.

Noch nicht unterstützt

• persistentes Undo/Redo und Projektversionen
• Mehrbenutzerbetrieb und Konfliktauflösung
• Revit-/CSV-/IFCGUID-Round-trip
• vollständige elektrische Dimensionierung
• Produktionsdeployment

Details: Bekannte Einschränkungen und Zukunftsarchitektur.