From 0a17da2b8e5e24833a32631c5a610bceb1b5fe9d Mon Sep 17 00:00:00 2001 From: Julian Appel Date: Sat, 26 Sep 2026 21:02:48 +0200 Subject: [PATCH] Align runtime and editor documentation with current implementation --- README.md | 13 +++++++++---- docs/circuit-list-editor-interactions.md | 5 +++++ docs/current-architecture.md | 15 ++++++++++++--- docs/deployment.md | 21 +++++++++++++++------ docs/development-workflow.md | 8 +++++++- 5 files changed, 48 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 58f1832..55c4f65 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,12 @@ Leistungsbilanz ist eine Webanwendung für die elektrische Ausführungsplanung. Mittelpunkt steht ein tabellenähnlicher Stromkreislisten-Editor, der Stromkreise, Gerätezeilen und wiederverwendbare Projektgeräte fachlich getrennt behandelt. -Das Projekt befindet sich in aktiver Entwicklung. Der lokale Entwicklungsbetrieb -mit SQLite und Docker Compose ist unterstützt. Ein Produktionsdeployment, -Mehrbenutzerbetrieb und der Revit-/IFCGUID-Datenaustausch sind noch nicht -implementiert. +Das Projekt befindet sich in aktiver Entwicklung. Für SQLite stehen ein +Docker-Server-Stack mit gebautem Anwendungscode und ein separater +Entwicklungsstack bereit. Ein vollständig unterstütztes Produktionsdeployment +und Mehrbenutzerbetrieb fehlen weiterhin. Revit-CSV-Konfiguration, Vorschau +und bestätigter Erstimport sind implementiert; die Editoroberfläche zur +Objektzuordnung, Folgeimporte und Rückexport stehen noch aus. ## Unterstützter Arbeitsablauf @@ -25,6 +27,9 @@ implementiert. - Änderungen projektweit und auch nach einem Reload rückgängig machen und wiederholen - benannte Sicherungspunkte anlegen, wiederherstellen und Revisionen einsehen - automatische Sicherungspunkte mit begrenzter Aufbewahrung nutzen +- Revit-CSV-Dateien konfigurieren, prüfen und nach expliziter Zuordnung von + Räumen, Verteilungen und Projektgeräten erstmals importieren; dabei entstehen + noch keine Stromkreise oder Gerätezeilen ## Technik diff --git a/docs/circuit-list-editor-interactions.md b/docs/circuit-list-editor-interactions.md index c8c02aa..01ca537 100644 --- a/docs/circuit-list-editor-interactions.md +++ b/docs/circuit-list-editor-interactions.md @@ -161,6 +161,11 @@ across multiple sections is atomic and occupies one history step. Explicit renumbering uses a collision-safe persistent project command and one project-history step. +The editor creates client-side UUIDs through `createClientId` in +`src/frontend/utils/client-id.ts`. It uses `crypto.randomUUID()` when available +and otherwise generates a UUID v4 with `crypto.getRandomValues()`, so insertion +also works over plain HTTP from another machine in the LAN. + Covered operations include: - insert/delete circuit diff --git a/docs/current-architecture.md b/docs/current-architecture.md index 92efc98..b9ffba2 100644 --- a/docs/current-architecture.md +++ b/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 diff --git a/docs/deployment.md b/docs/deployment.md index 909c2c0..0b5baba 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -16,9 +16,10 @@ und macOS keine inotify-Events durchreichen; das kostet dauerhaft CPU, auch ohne Benutzeraktivität. Dieser Stack gehört deshalb nur auf einen Entwicklungsrechner. -Beides enthält weder TLS, Authentifizierung, Reverse Proxy, Prozesshärtung noch -ein zentral betriebenes Datenbanksystem. Der Stack darf deshalb nicht öffentlich -erreichbar gemacht werden. +Beide Stacks enthalten weder TLS, Authentifizierung, einen vorgeschalteten +Reverse Proxy noch ein zentral betriebenes Datenbanksystem. Die oben genannten +Container-Schutzmaßnahmen ersetzen diese Funktionen nicht. Der Stack darf +deshalb nicht öffentlich erreichbar gemacht werden. ## Topologie @@ -34,6 +35,11 @@ erreicht, kann jedes Projekt lesen und ändern. Erreichbar ist sie nur aus dem Compose-Netz, praktisch also über den Next.js-Rewrite. Im Entwicklungs-Stack hängen beide Ports am Loopback und sind nicht aus dem LAN erreichbar. +Beim HTTP-Zugriff auf den Server-Stack aus dem LAN erzeugt der Editor neue +UUIDs über `createClientId`, mit `crypto.getRandomValues()` als Ersatz für das +dort nicht verfügbare `crypto.randomUUID()`. HTTPS ist für diese +ID-Erzeugung nicht erforderlich. + ### Speichergrenzen Jeder Dienst hat ein `mem_limit`. Im Server-Stack ist zusätzlich @@ -140,14 +146,17 @@ Vor einer produktiven Installation werden mindestens benötigt: - Entscheidung, ob SQLite für einen einzelnen Prozess genügt oder PostgreSQL für Mehrbenutzerbetrieb erforderlich ist -Bis diese Punkte umgesetzt und getestet sind, besteht die „Installation“ aus dem -lokalen Entwicklungsstart in der README. +Der in der README beschriebene Server-Stack ermöglicht bereits den Betrieb des +gebauten Stands in einer geschützten Umgebung. Ein vollständig unterstütztes +Produktionssetup bleibt bis zur Umsetzung und Prüfung dieser Punkte offen. ## Backup und Wiederherstellung `npm run db:backup` erzeugt unter `data/backups/` ein konsistentes SQLite-Backup, öffnet es unabhängig und prüft Integrität sowie Fremdschlüssel. Diese -Dateisicherungen sind von zukünftigen logischen Projektversionen getrennt. +Dateisicherungen sind von den bereits vorhandenen benannten und automatischen +logischen Projektsicherungen getrennt. Projektsicherungen werden über die +Projektseite wiederhergestellt und unterstützen persistentes Undo/Redo. Eine produktive Restore-Anweisung wird erst zusammen mit einem unterstützten Produktionsbetrieb veröffentlicht. Lokale Wiederherstellung darf nur bei diff --git a/docs/development-workflow.md b/docs/development-workflow.md index b19b7ff..f630063 100644 --- a/docs/development-workflow.md +++ b/docs/development-workflow.md @@ -13,6 +13,11 @@ Ein sauberer Clone enthält keine SQLite-Datenbank. Beim ersten Start werden `data/leistungsbilanz.db`, alle Tabellen und Migrationseinträge automatisch angelegt. Das Frontend ist unter erreichbar. +Dieser Standard-Stack verwendet gebauten Anwendungscode. Für die Entwicklung +mit Quellcode-Mounts und Hot Reload stattdessen +`docker compose -f compose.dev.yaml up --build --detach` verwenden; die Dienste +sind dabei nur über die Loopback-Ports des Entwicklungsrechners erreichbar. + Für direkte Node.js-Entwicklung: ```powershell @@ -86,7 +91,8 @@ Bei Docker- oder Laufzeitänderungen zusätzlich: ```powershell docker compose up --build --detach docker compose ps -Invoke-WebRequest http://localhost:3000/health +Invoke-WebRequest http://localhost:3001/health +Invoke-WebRequest http://localhost:3001/web-health ``` Bei sichtbaren Editoränderungen ist außerdem ein kurzer GUI-Test erforderlich.