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. Persistente Projektrevisionen, optimistische Revisionsprüfungen und serverseitiges Undo/Redo sind die nächste Architekturphase.

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.