Rewrite project documentation

2026-07-23 21:05:43 +02:00
parent 30d6f1a2e1
commit 6b6d2c2a42
17 changed files with 535 additions and 221 deletions
@@ -0,0 +1,106 @@
+# 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
+
+```text
+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](circuit-list-editor-known-limitations.md) und
+[Zukunftsarchitektur](project-history-and-external-model-architecture.md).