From 6b6d2c2a4257c4cf82d996a03797ec10533bacc3 Mon Sep 17 00:00:00 2001 From: Julian Appel Date: Thu, 23 Jul 2026 21:05:43 +0200 Subject: [PATCH] Rewrite project documentation --- AGENTS.md | 69 ++++- README.md | 284 ++++++------------ docs/README.md | 48 +++ .../initial-codex-prompts.md} | 6 +- docs/circuit-list-editor-api.md | 3 +- docs/circuit-list-editor-architecture.md | 15 +- docs/circuit-list-editor-known-limitations.md | 3 +- docs/circuit-list-editor-migration.md | 9 +- docs/current-architecture.md | 106 +++++++ docs/deployment.md | 60 ++++ docs/development-workflow.md | 110 +++++++ docs/local-db-circuit-first-migration.md | 4 + ...history-and-external-model-architecture.md | 18 +- docs/spec/07-implementation-phases-todo.md | 10 + package.json | 2 +- src/frontend/pages/README.md | 5 - src/frontend/utils/README.md | 4 - 17 files changed, 535 insertions(+), 221 deletions(-) create mode 100644 docs/README.md rename docs/{spec/08-codex-prompts.md => archive/initial-codex-prompts.md} (94%) create mode 100644 docs/current-architecture.md create mode 100644 docs/deployment.md create mode 100644 docs/development-workflow.md delete mode 100644 src/frontend/pages/README.md delete mode 100644 src/frontend/utils/README.md diff --git a/AGENTS.md b/AGENTS.md index f2ffd50..04d1493 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,12 +2,33 @@ ## Project Goal -Build a spreadsheet-like electrical distribution board circuit list editor. +Maintain and extend a spreadsheet-like electrical distribution board circuit list editor. The editor is used for electrical planning in execution design. It must support circuits, device rows, project devices, drag-and-drop restructuring, stable equipment identifiers and later electrical sizing logic. +## Current Supported Architecture + +- Frontend: Next.js App Router under `src/app` with reusable editor modules under `src/frontend`. +- API: Express composition starts in `src/server/index.ts`. +- Domain rules: `src/domain`. +- Persistence: SQLite/Drizzle schemas, repositories and migrations under `src/db`. +- Primary editor route: + `src/app/projects/[projectId]/circuit-lists/[circuitListId]/tree-edit/page.tsx`. +- Primary editor component: `src/frontend/components/circuit-tree-editor.tsx`. +- Grid ownership, projection, insertion and safety rules live in the pure + `src/frontend/components/circuit-grid-*.ts` modules. +- Critical multi-write commands use injected transaction repositories with real + SQLite commit/rollback tests. + +The supported runtime model is Circuit-First. The former Consumer UI and API are +removed. Retained `consumers` rows, migration mappings and reports are upgrade-only +data accessed by `npm run db:migrate:legacy-consumers`; do not build application +features on them. + +See `docs/current-architecture.md` for the complete module and request flow. + ## Critical Domain Rules - A circuit is not the same thing as one device row. @@ -112,6 +133,9 @@ Renumber only when the user explicitly triggers "Renumber section". The circuit list table should behave like a spreadsheet. +User-facing frontend text must be German unless a domain-standard technical term +is intentionally retained. + Cells show static text by default. Inline edit starts by: @@ -196,7 +220,8 @@ After saving, the row becomes linked to the new project device. ## Undo / Redo -Implement undo/redo for structural and destructive operations. +Session-local undo/redo exists for structural and destructive operations. +Persistent project-wide undo/redo remains future work. Required operations: @@ -232,6 +257,46 @@ Future sizing will need: Users must be able to override sizing suggestions. +## Persistence and Migration Rules + +- SQLite is the currently supported database. +- Never edit an already applied migration. +- Back up an existing database before applying a new migration. +- Inspect generated SQL; it must contain only the intended schema change. +- Keep database backups separate from future logical project snapshots. +- Do not import the global SQLite singleton into domain services. +- Keep synchronous SQLite transaction behavior inside persistence adapters. +- Preserve stable UUIDs and explicit transaction boundaries for a later + PostgreSQL adapter. + +## Current Deferred Work + +- persistent project revisions and undo/redo +- named logical snapshots and restore +- Revit/CSV/IFCGUID round-trip +- full electrical sizing +- multi-user/PostgreSQL operation +- supported production deployment + +Do not implement these while working on an unrelated phase. + +## Documentation and Verification + +- `README.md` is the setup entry point. +- `docs/README.md` is the documentation map. +- `docs/current-architecture.md` describes current code paths. +- `docs/spec/` contains requirements and roadmap, not proof of implementation. +- `docs/archive/` is historical and must not drive current implementation. + +For a normal code change run the relevant focused tests plus: + +- `npm test` +- `npm run build:api` +- `npm run build:web` +- `npx tsc --noEmit -p tsconfig.next.json` + +Use a concise imperative commit message for each completed, verified work package. + ## Response Style for Codex Be concise. diff --git a/README.md b/README.md index ec08135..f5a44b2 100644 --- a/README.md +++ b/README.md @@ -1,225 +1,121 @@ -# Leistungsbilanz – Hauptdokumentation +# Leistungsbilanz -Diese Anwendung unterstützt die elektrische Fachplanung (TGA/ELT) bei der Erstellung und Pflege von Leistungsbilanzen und Stromkreislisten. +Leistungsbilanz ist eine Webanwendung für die elektrische Ausführungsplanung. Im +Mittelpunkt steht ein tabellenähnlicher Stromkreislisten-Editor, der Stromkreise, +Gerätezeilen und wiederverwendbare Projektgeräte fachlich getrennt behandelt. -Sie ist als praxisnahe Webanwendung für kleine Teams gedacht (ca. 2–3 gleichzeitige Nutzer), mit Schwerpunkt auf schneller tabellarischer Bearbeitung statt komplexer Enterprise-Strukturen. +Das Projekt befindet sich in aktiver Entwicklung. Der lokale Entwicklungsbetrieb +mit SQLite und Docker Compose ist unterstützt. Ein Produktionsdeployment, +persistentes Undo/Redo, Projektversionen und der Revit-/IFCGUID-Datenaustausch sind +noch nicht implementiert. -## Sinn und Ziel der Anwendung +## Unterstützter Arbeitsablauf -Die Anwendung soll Planer dabei unterstützen: +- Projekte, Verteilungen, Etagen und Räume verwalten +- pro Verteilung eine Stromkreisliste mit festen Bereichen bearbeiten +- leere, einzeilige und mehrzeilige Stromkreise abbilden +- Stromkreise und Gerätezeilen per Drag-and-drop umstrukturieren +- Projektgeräte einfügen, verknüpfen und kontrolliert synchronisieren +- komplette Stromkreisblöcke filtern und sortieren +- BMKs stabil halten und nur auf ausdrücklichen Befehl neu nummerieren +- Änderungen innerhalb der aktuellen Editorsitzung rückgängig machen und wiederholen -1. Projekte anzulegen und zu verwalten. -2. Verteilungen pro Projekt anzulegen. -3. Verbraucher strukturiert in Stromkreislisten zu erfassen. -4. Installierte Leistung, Gleichzeitigkeitsleistung und Strom automatisch zu berechnen. -5. Gerätevorlagen global sowie projektbezogen zu verwalten und wiederzuverwenden. -6. Planungsdaten schrittweise zu vervollständigen, ohne unnötige Pflichtfeldhürden. +## Technik -Fachlich stehen folgende Begriffe im Zentrum: +- Next.js 16, React 19 und TypeScript für das Frontend +- Express 5 und Zod für die API +- SQLite, `better-sqlite3` und Drizzle ORM für die Persistenz +- eigener Spreadsheet-Grid statt eines Bootstrap-Tabellenframeworks +- Node.js-Test-Runner für Domain-, Grid- und SQLite-Integrationstests -- Projekt -- Verteilung -- Stromkreisliste -- Verbraucher/Gerät -- installierte Leistung -- Gleichzeitigkeitsfaktor -- berechnete Leistung -- Spannung (1-phasig / 3-phasig) -- Strom +## Schnellstart mit Docker -## Anforderungsbasis +Voraussetzungen: -Die fachliche Basis stammt aus [docs/electrical-load-balance-requirements-context-dump.md](docs/electrical-load-balance-requirements-context-dump.md). +- Git +- Docker Desktop mit Docker Compose -Die folgende Liste fasst die zentralen Anforderungen zusammen und zeigt den aktuellen Umsetzungsstand im Code. +```powershell +git clone +Set-Location leistungsbilanz-ts +docker compose up --build --detach +``` -## Anforderungsliste mit Ist-Stand +Danach: -### 1) Projektverwaltung -- Anforderung: Projekte erstellen und anzeigen. -- Status: Erfüllt. -- Umsetzung: UI in `src/app/projects/page.tsx`, API in `src/server/controllers/project.controller.ts`. +- Frontend: +- API-Healthcheck: -### 2) Verteilungen pro Projekt -- Anforderung: Mehrere Verteilungen pro Projekt. -- Status: Erfüllt. -- Umsetzung: `src/server/controllers/distribution-board.controller.ts`, `src/app/projects/[projectId]/page.tsx`. +Der API-Container führt ausstehende Migrationen und die Schemaprüfung beim Start +automatisch aus. Die SQLite-Datei liegt auf dem Host unter +`data/leistungsbilanz.db` und bleibt beim Stoppen erhalten. -### 3) Genau eine Stromkreisliste pro Verteilung -- Anforderung: Jede Verteilung besitzt genau eine Stromkreisliste. -- Status: Erfüllt. -- Umsetzung: Beim Erstellen einer Verteilung wird automatisch eine Stromkreisliste angelegt (`createDistributionBoard` + `CircuitListRepository.createForDistributionBoard`). +```powershell +docker compose ps +docker compose logs --follow +docker compose down +``` -### 4) Tabellarische Stromkreisbearbeitung -- Anforderung: Einträge als Tabellenzeilen anlegen, bearbeiten, löschen. -- Status: Erfüllt. -- Umsetzung: `src/app/projects/[projectId]/circuit-lists/page.tsx`, API `src/server/controllers/consumer.controller.ts`. +Der Compose-Stack startet Entwicklungsserver mit Quellcode-Mounts. Er ist kein +Produktionsdeployment. Details stehen in +[Deployment und Betrieb](docs/deployment.md). -### 5) Bis zu drei parallele Stromkreislisten -- Anforderung: 1–3 Listen parallel, Standard = 1, inkl. Kopieren zwischen Listen. -- Status: Erfüllt. -- Umsetzung: `activeListCount`, Slot-Logik und Kopierfunktionen in `src/app/projects/[projectId]/circuit-lists/page.tsx`. +## Direkte lokale Entwicklung -### 6) Geräteverwaltung global + projektbezogen -- Anforderung: Globale Geräteliste und Projektgeräteliste. -- Status: Erfüllt. -- Umsetzung: Seiten `src/app/projects/page.tsx` und `src/app/projects/[projectId]/page.tsx`, API-Routen für `global-devices` und `project-devices`. +Voraussetzungen: -### 7) Geräte zwischen global und Projekt kopieren -- Anforderung: Kopieren in beide Richtungen. -- Status: Erfüllt. -- Umsetzung: `copyGlobalDeviceToProject` und `copyProjectDeviceToGlobal`. +- Node.js 22 +- npm -### 8) `name` + `displayName` bei Geräten -- Anforderung: Interner Name und Anzeigename getrennt. -- Status: Erfüllt. -- Umsetzung: DB-Schema, Validierung, UI und Copy-Flows sind angepasst. +```powershell +npm ci +npm run db:migrate +npm run db:verify:circuit-schema +npm run dev:api +``` -### 9) Geräte-Link an Stromkreiseinträgen -- Anforderung: Eintrag kann mit Projektgerät verknüpft/entkoppelt werden; verknüpfte Einträge aktualisieren sich bei Geräteänderung. -- Status: Erfüllt. -- Umsetzung: Felder `projectDeviceId` + `isLinkedToDevice`, Sync in `syncLinkedConsumersFromProjectDevice`. +In einem zweiten Terminal: -### 10) Unvollständige Einträge zulassen -- Anforderung: Einträge sollen grundsätzlich auch unvollständig möglich sein. -- Status: Teilweise erfüllt. -- Umsetzung: Backend akzeptiert optionale Kernfelder und setzt Defaults. -- Hinweis: Das manuelle Schnellformular im UI verlangt weiterhin einen Namen für den direkten Anlege-Flow. +```powershell +npm run dev:web +``` -### 11) Add Count (mehrere Einträge aus einem Gerät erzeugen) -- Anforderung: getrennt von `quantity`. -- Status: Erfüllt. -- Umsetzung: `addCount` bei „Projektgerät übernehmen“ in der Stromkreislistenansicht. +Frontend und API laufen anschließend auf denselben Ports wie im Docker-Setup. -### 12) Duplizieren und Kopieren von Einträgen -- Anforderung: Duplizieren in derselben Liste + Kopieren in andere Listen. -- Status: Erfüllt. -- Umsetzung: Zeilenaktionen „Dupl.“ und Listenkopie, plus Auswahl-Kopie. +## Qualitätssicherung -### 13) Sortieren, Filtern, Bulk-Edit -- Anforderung: erweiterte Tabellenfunktionen. -- Status: Erfüllt (Basisumfang). -- Umsetzung: Filterfeld, Sortierfeld/-richtung und Sammeländerung für Auswahlwerte. +```powershell +npm test +npm run build:api +npm run build:web +npx tsc --noEmit -p tsconfig.next.json +``` -### 14) Räume und Etagen -- Anforderung: Projektbezogene Räume/Etagen und Zuordnung zu Einträgen. -- Status: Erfüllt. -- Umsetzung: Floors/Rooms in Projektansicht und Raumzuordnung in Stromkreisliste. +Wichtige Datenbankbefehle: -### 15) Projektspezifische Spannungsstandards (1-ph/3-ph) -- Anforderung: 230 V / 400 V als Standard, in Projekteigenschaften editierbar, in Berechnung verwendet. -- Status: Erfüllt. -- Umsetzung: Projekteinstellungen + Nutzung in Berechnungsservice. +```powershell +npm run db:backup +npm run db:migrate +npm run db:verify:circuit-schema +npm run db:generate +``` -### 16) Spaltensteuerung in der Tabelle -- Anforderung: Attribute ein-/ausblenden und Spaltenreihenfolge ändern. -- Status: Erfüllt. -- Umsetzung: Spaltenmanager in `circuit-lists/page.tsx`. +`db:backup` verwendet die SQLite-Online-Backup-API und prüft das Ergebnis auf +Integrität und Fremdschlüsselverletzungen. Vor jeder Migration einer bestehenden +Datenbank ist ein Backup erforderlich. -### 17) Feste Auswahllisten für Domänenfelder -- Anforderung: feste Werte für Felder wie `deviceType`, `phaseType`, Schutz/Kabel usw. -- Status: Erfüllt. -- Umsetzung: zentrale Listen in `src/shared/constants/consumer-option-lists.ts`, Validierung über `z.enum(...)`, UI-Selects. +`db:migrate:legacy-consumers` und `db:backfill:sections` sind ausschließlich +Upgrade-Werkzeuge für ältere Datenbanken. Neue Installationen benötigen sie nicht. -### 18) Tests über reine Formeln hinaus -- Anforderung: zusätzliche Tests für Link-/Eintragsverhalten. -- Status: Erfüllt. -- Umsetzung: `tests/consumer-linking.service.test.ts` und `tests/consumer-schema-options.test.ts`. +## Dokumentation -## Technische Architektur (für neue Entwickler) +- [Dokumentationsübersicht](docs/README.md) +- [Aktuelle Architektur](docs/current-architecture.md) +- [Editor-Interaktionen](docs/circuit-list-editor-interactions.md) +- [API des Stromkreislisten-Editors](docs/circuit-list-editor-api.md) +- [Entwicklungs- und Contributor-Workflow](docs/development-workflow.md) +- [Bekannte Einschränkungen](docs/circuit-list-editor-known-limitations.md) +- [Roadmap](docs/spec/07-implementation-phases-todo.md) -### Backend -- Node.js + Express -- Einstieg: `src/server/index.ts` -- API-Module: - - Projekte/Verteilungen/Räume/Etagen - - Verbraucher (Stromkreiseinträge) - - globale und projektbezogene Geräte - -### Frontend -- Next.js (App Router) + React + Bootstrap -- Hauptseiten: - - `src/app/projects/page.tsx` (Projektliste + globale Geräte) - - `src/app/projects/[projectId]/page.tsx` (Projektdetails, Verteilungen, Räume/Etagen, Projektgeräte) - - `src/app/projects/[projectId]/circuit-lists/page.tsx` (Stromkreislisten-Editor) - -### Datenbank -- SQLite + Drizzle ORM -- Schema unter `src/db/schema` -- Migrationen unter `src/db/migrations` - -### Domänen- und Rechenlogik -- Berechnung: `src/domain/calculations/power-calculation.ts` -- Anreicherung/Businesslogik: `src/domain/services/power-balance.service.ts` -- Geräte-Link-Logik: `src/domain/services/consumer-linking.service.ts` - -## Schneller Entwicklungsstart - -### Mit Docker (empfohlen fuer kurze Sessions) - -Voraussetzung: Docker Desktop mit aktivem Docker-Compose-Plugin. - -1. Sicherstellen, dass keine direkt gestartete API und kein direkt gestartetes Frontend mehr auf Port 3000/3001 laufen. -2. `npm run docker:up` (baut und startet beide Container im Hintergrund) -3. Frontend unter `http://localhost:3001` oeffnen. - -Beim Start fuehrt der API-Container ausstehende Drizzle-Migrationen und die Circuit-First-Schemapruefung aus. Die vorhandene SQLite-Datenbank wird ueber `./data:/app/data` eingebunden und bleibt nach `npm run docker:down` erhalten. Quellcodeaenderungen unter `src/` werden von beiden Entwicklungsservern automatisch erkannt. - -Weitere Docker-Befehle: - -- `npm run docker:down` - Frontend und API stoppen -- `npm run docker:logs` - laufende Containerlogs anzeigen (`Ctrl+C` beendet nur die Logansicht) -- `docker compose ps` - Status und Healthchecks anzeigen -- `Invoke-WebRequest http://localhost:3000/health` - API-Healthcheck pruefen - -Bewusster Datenbank-Reset unter PowerShell: - -1. `npm run docker:down` -2. `npm run db:backup` -3. `Remove-Item -LiteralPath .\data\leistungsbilanz.db` -4. `npm run docker:up` - -Der Reset entfernt die aktive lokale Datenbank. Die zuvor erzeugte Sicherung bleibt unter `data/backups/` erhalten. - -### Ohne Docker - -1. `npm install` -2. `npm run db:migrate` -3. `npm run db:verify:circuit-schema` -4. `npm run dev:api` (API auf Port 3000) -5. In einem zweiten Terminal `npm run dev:web` (Frontend auf Port 3001) - -## Wichtige Befehle - -- `npm run dev:api` – API lokal starten -- `npm run dev:web` – Frontend lokal starten -- `npm run build:api` – Backend bauen -- `npm run build:web` – Frontend bauen -- `npm test` – Testlauf -- `npm run db:generate` – Migrationen generieren -- `npm run db:migrate` – Migrationen ausführen - -### Circuit-First lokale Migration - -- `npm run db:backup` – lokale SQLite sichern -- `npm run db:migrate` – pending Migrationen ausführen -- `npm run db:verify:circuit-schema` – Circuit-First Tabellenprüfung -- `npm run db:backfill:sections` – Default-Sections für bestehende Listen anlegen -- `npm run db:migrate:legacy-consumers` – Legacy-Consumers explizit in Circuit-First überführen - -Siehe auch: `docs/local-db-circuit-first-migration.md` - -## Ergänzende Dokumente - -- Anforderungen (Quelle): [docs/electrical-load-balance-requirements-context-dump.md](docs/electrical-load-balance-requirements-context-dump.md) -- Abgleich „Anforderung vs. Implementierung“: [docs/anforderungs-abgleich.md](docs/anforderungs-abgleich.md) - -## Circuit-List Editor Dokumentation - -- Architektur: [docs/circuit-list-editor-architecture.md](docs/circuit-list-editor-architecture.md) -- Interaktionen: [docs/circuit-list-editor-interactions.md](docs/circuit-list-editor-interactions.md) -- API: [docs/circuit-list-editor-api.md](docs/circuit-list-editor-api.md) -- Migration: [docs/circuit-list-editor-migration.md](docs/circuit-list-editor-migration.md) -- Bekannte Limitierungen: [docs/circuit-list-editor-known-limitations.md](docs/circuit-list-editor-known-limitations.md) - -Diese Dokumente beschreiben den aktuellen circuit-first Editorstand und dienen als sichere Entwicklungsbasis fuer Folgeschritte. +Für LLM-gestützte Änderungen enthält [AGENTS.md](AGENTS.md) die verbindlichen +Domänenregeln, unterstützten Einstiegspunkte und Architekturgrenzen. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..1c113ed --- /dev/null +++ b/docs/README.md @@ -0,0 +1,48 @@ +# Dokumentationsübersicht + +Diese Seite ist der Einstieg in die Projektdokumentation. Aussagen zum aktuellen +System stehen unter „Aktuell“. Zukunftsentwürfe und historische Unterlagen sind +ausdrücklich getrennt und dürfen nicht als bereits implementiert verstanden werden. + +## Aktuell + +- [Aktuelle Systemarchitektur](current-architecture.md) – Laufzeit, Modulgrenzen, + Datenfluss und unterstützte Codepfade +- [Stromkreislisten-Architektur](circuit-list-editor-architecture.md) – + fachliches Modell und Grid-Aufteilung +- [Editor-Interaktionen](circuit-list-editor-interactions.md) – Tastatur, + Drag-and-drop, Sortierung, Filterung und Undo/Redo +- [Editor-API](circuit-list-editor-api.md) – unterstützte Circuit-First-Endpunkte +- [Bekannte Einschränkungen](circuit-list-editor-known-limitations.md) – + bewusst noch nicht implementierte oder begrenzte Funktionen + +## Entwicklung und Betrieb + +- [Entwicklungs- und Contributor-Workflow](development-workflow.md) +- [Deployment und Betrieb](deployment.md) +- [Lokale Circuit-First-Datenbankmigration](local-db-circuit-first-migration.md) +- [Retained Legacy-Datenmigration](circuit-list-editor-migration.md) – + ausschließlich für Upgrades alter Datenbanken + +## Zukunftsarchitektur + +- [Projektversionen und externer Modellaustausch](project-history-and-external-model-architecture.md) +- [Zukünftige Dimensionierung](spec/06-future-sizing-and-calculations.md) +- [Roadmap und Phasen](spec/07-implementation-phases-todo.md) + +## Fachliche Referenzspezifikation + +Die folgenden Dokumente beschreiben Zielregeln und Anforderungen. Nicht jeder +Punkt ist bereits umgesetzt; der aktuelle Stand ergibt sich aus Architektur, +Limitierungen und Roadmap. + +- [Domänenkontext](spec/01-domain-context.md) +- [Funktionale Anforderungen](spec/02-functional-requirements.md) +- [Datenmodellkonzept](spec/03-data-model-concept.md) +- [UI- und Interaktionsanforderungen](spec/04-ui-interaction-requirements.md) +- [Verknüpfte Projektgeräte und Synchronisierung](spec/05-linked-devices-and-sync.md) + +## Archiv + +- [Frühe Codex-Promptvorlagen](archive/initial-codex-prompts.md) – historischer + Arbeitsstand, keine aktuelle Implementierungsanweisung diff --git a/docs/spec/08-codex-prompts.md b/docs/archive/initial-codex-prompts.md similarity index 94% rename from docs/spec/08-codex-prompts.md rename to docs/archive/initial-codex-prompts.md index 8211479..03c3c86 100644 --- a/docs/spec/08-codex-prompts.md +++ b/docs/archive/initial-codex-prompts.md @@ -1,4 +1,8 @@ -# Codex Prompt Templates +# Archived Initial Codex Prompt Templates + +> Historical document. These prompts predate the supported Circuit-First +> architecture and must not be used as current implementation instructions. Use +> `AGENTS.md`, `docs/current-architecture.md` and the current roadmap instead. Use these prompts step by step. Do not ask Codex to build the whole application in one pass. diff --git a/docs/circuit-list-editor-api.md b/docs/circuit-list-editor-api.md index af2893f..9d94a49 100644 --- a/docs/circuit-list-editor-api.md +++ b/docs/circuit-list-editor-api.md @@ -2,7 +2,8 @@ ## Scope -The circuit-first editor uses tree + circuit + row endpoints. Legacy consumer endpoints still exist for compatibility and migration, but should not be extended for new circuit-list behavior. +The circuit-first editor uses tree, circuit, row and project-device endpoints. +All paths below are mounted below `/api`. There is no Consumer application API. ## Circuit-First Endpoints diff --git a/docs/circuit-list-editor-architecture.md b/docs/circuit-list-editor-architecture.md index d42d6a8..b7754df 100644 --- a/docs/circuit-list-editor-architecture.md +++ b/docs/circuit-list-editor-architecture.md @@ -40,9 +40,10 @@ The pure grid modules have no React state and are covered by focused unit tests. - `ProjectDevice` - Reusable device template entity at project level. - Can be linked to `CircuitDeviceRow` entries, with copied display values on insert. -- Legacy `Consumer` - - Old row-first model still present for compatibility/migration. - - Should not be extended for new circuit-list behavior. +- Retained legacy migration source + - Old `consumers` rows, mappings and reports are available only to explicit + database upgrade tooling. + - They are not application-domain entities and have no UI or API. ## Why A Circuit Is Not One Row @@ -104,10 +105,14 @@ Primary circuit-first editor route: - `/projects/:projectId/circuit-lists/:circuitListId/tree-edit` -Legacy route remains separate (read-only/preview/migration transition path) and is intentionally not merged into the editable tree editor. +The sibling `/tree` route is a read-only structure preview. Old +`/projects/:projectId/circuit-lists` bookmarks redirect to the project page. ## Future Persistence Direction Persistent undo/redo, project revisions, logical snapshots, external-model exchange and PostgreSQL readiness are specified in [Project History and External Model Architecture](./project-history-and-external-model-architecture.md). -Near-term refactoring must move command and transaction ownership toward server-side, project-scoped change sets. Database backups remain separate from user-visible project snapshots. +Critical multi-write commands already use explicit persistence transaction +adapters. The next step is to compose these command boundaries into server-side, +project-scoped revisions and change sets. Database backups remain separate from +user-visible project snapshots. diff --git a/docs/circuit-list-editor-known-limitations.md b/docs/circuit-list-editor-known-limitations.md index ec98515..00ab566 100644 --- a/docs/circuit-list-editor-known-limitations.md +++ b/docs/circuit-list-editor-known-limitations.md @@ -5,7 +5,8 @@ - No project revision or logical snapshot model is implemented yet. - No Revit/CSV/IFCGUID import and export workflow is implemented yet. - Persistence currently targets local SQLite; PostgreSQL is an architectural option, not an implemented runtime. -- No global cross-project device library workflow is implemented yet. +- The global device library supports basic CRUD and copy operations, but has no + versioning, permissions or controlled synchronization model. - Final electrical sizing logic is not implemented yet. - No full norm-compliant voltage-drop and protection-dimensioning calculation flow yet. - Sorting is view-only until users explicitly apply sorted order. diff --git a/docs/circuit-list-editor-migration.md b/docs/circuit-list-editor-migration.md index 142ceda..1f6364c 100644 --- a/docs/circuit-list-editor-migration.md +++ b/docs/circuit-list-editor-migration.md @@ -1,5 +1,10 @@ # Circuit List Editor Migration +## Status + +Upgrade-only. New installations already use the Circuit-First schema and do not +run this workflow. + ## Goal Migrate legacy row-first consumers into the circuit-first model without deleting legacy data. @@ -80,4 +85,6 @@ Do not delete legacy consumers yet. - legacy read/write endpoints have been removed from the application server - migration trace tables reference old/new mapping -- keeping legacy rows allows comparison and rollback validation during transition +- retained rows allow upgrade verification and audit of the completed mapping +- a future automatic cleanup migration must migrate and verify old databases + before dropping these source and trace tables diff --git a/docs/current-architecture.md b/docs/current-architecture.md new file mode 100644 index 0000000..ec79ed6 --- /dev/null +++ b/docs/current-architecture.md @@ -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). diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..44c7dd5 --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,60 @@ +# Deployment und Betrieb + +## Aktueller Status + +Es gibt derzeit kein unterstütztes Produktionsdeployment. + +`compose.yaml` ist ausschließlich für lokale Entwicklung vorgesehen. Es startet +`tsx watch` und `next dev`, bindet Quellcode vom Host ein und enthält weder TLS, +Authentifizierung, Reverse Proxy, Prozesshärtung noch ein zentral betriebenes +Datenbanksystem. Der Stack darf deshalb nicht als produktionsreif bezeichnet oder +öffentlich erreichbar gemacht werden. + +## Entwicklungs-Topologie + +| Komponente | Port | Healthcheck | Persistenz | +| --- | ---: | --- | --- | +| Next.js Web | 3001 | `GET /` | keine | +| Express API | 3000 | `GET /health` | `./data:/app/data` | +| SQLite | Datei | Integritäts-/FK-Prüfung via Backup und Skript | `data/leistungsbilanz.db` | + +Verwendete Umgebungsvariablen: + +- `PORT` – API-Port, Standard `3000` +- `API_INTERNAL_URL` – internes API-Ziel des Next.js-Rewrites, im Compose-Netz + `http://api:3000` +- `NEXT_TELEMETRY_DISABLED=1` +- `CHOKIDAR_USEPOLLING=true` und `WATCHPACK_POLLING=true` für lokale + Dateibeobachtung in Docker + +Beim API-Start laufen zuerst `npm run db:migrate` und +`npm run db:verify:circuit-schema`. + +## Voraussetzungen für ein späteres Produktionssetup + +Vor einer produktiven Installation werden mindestens benötigt: + +- reproduzierbare Produktionsimages und ein Next.js-Produktionsstartskript +- TLS-Termination und Reverse Proxy +- Authentifizierung, Autorisierung und Benutzer-/Rollenmodell +- definierte Secrets- und Konfigurationsverwaltung +- persistenter, gesicherter Datenbankbetrieb +- kontrollierter einmaliger Migrationsschritt vor dem API-Rollout +- Monitoring, strukturierte Logs und Alarmierung +- getestete Backup-, Restore- und Rollback-Prozeduren +- 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. + +## 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. + +Eine produktive Restore-Anweisung wird erst zusammen mit einem unterstützten +Produktionsbetrieb veröffentlicht. Lokale Wiederherstellung darf nur bei +gestoppter API, gegen eine separate Datei und nach erneuter Integritätsprüfung +erfolgen. diff --git a/docs/development-workflow.md b/docs/development-workflow.md new file mode 100644 index 0000000..109ee5e --- /dev/null +++ b/docs/development-workflow.md @@ -0,0 +1,110 @@ +# Entwicklungs- und Contributor-Workflow + +## Erstes lokales Setup + +Der empfohlene Einstieg ist Docker Compose: + +```powershell +docker compose up --build --detach +docker compose ps +``` + +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. + +Für direkte Node.js-Entwicklung: + +```powershell +npm ci +npm run db:migrate +npm run db:verify:circuit-schema +``` + +Danach `npm run dev:api` und `npm run dev:web` in getrennten Terminals starten. + +## Leere lokale Datenbank + +Eine bestehende lokale Datenbank lässt sich recoverable ersetzen: + +```powershell +docker compose down +npm run db:backup +Move-Item -LiteralPath .\data\leistungsbilanz.db .\data\leistungsbilanz.previous.db +docker compose up --build --detach +``` + +Die verschobene Datei und das verifizierte Backup bleiben lokal erhalten. Vor dem +Verschieben müssen die Container beendet sein, damit keine WAL-Sidecar-Datei aktiv +ist. + +## Sichere Beispieldaten + +Es gibt aktuell keinen versionierten Seed-Datensatz. Dadurch gelangen keine +Projekt- oder Kundendaten versehentlich ins Repository. Für einen lokalen +Testbestand: + +1. In der UI ein Projekt `Demo` anlegen. +2. Im Projekt eine Verteilung `UV-01` erstellen. +3. Ein Projektgerät mit unkritischen Fantasiewerten anlegen. +4. Die erzeugte Stromkreisliste öffnen und das Gerät in einen passenden Bereich + ziehen. + +Dateien unter `data/` und `data/backups/` dürfen nicht committed werden. + +## Arbeitsablauf für Änderungen + +1. Von einem aktuellen Branch einen kleinen Feature- oder Fix-Branch erstellen. +2. Relevante Domänenregeln in `AGENTS.md` und die aktuelle Architektur lesen. +3. Änderungen in einem fachlich geschlossenen Paket umsetzen. +4. Tests und Dokumentation proportional zur Änderung aktualisieren. +5. Alle erforderlichen Prüfungen ausführen. +6. Mit einer kurzen, prägnanten Nachricht committen. + +Empfohlene Commitnachrichten sind imperativ und beschreiben das Ergebnis, zum +Beispiel `Preserve circuit blocks during filtering`. + +## Pflichtprüfungen + +```powershell +npm test +npm run build:api +npm run build:web +npx tsc --noEmit -p tsconfig.next.json +git diff --check +``` + +Bei Docker- oder Laufzeitänderungen zusätzlich: + +```powershell +docker compose up --build --detach +docker compose ps +Invoke-WebRequest http://localhost:3000/health +``` + +Bei sichtbaren Editoränderungen ist außerdem ein kurzer GUI-Test erforderlich. + +## Migrationen + +1. Bestehende lokale Datenbank sichern: `npm run db:backup`. +2. Schema unter `src/db/schema/` ändern. +3. `npm run db:generate` ausführen. +4. Das generierte SQL vollständig prüfen; es darf nur die beabsichtigte Änderung + enthalten. +5. Upgrade-/Erhaltungstest ergänzen, wenn Spalten oder Beziehungen geändert + werden. +6. `npm test`, `npm run db:migrate` und + `npm run db:verify:circuit-schema` ausführen. + +Bereits angewendete SQL-Migrationen dürfen nicht geändert oder neu sortiert +werden. Korrekturen erfolgen immer über eine neue Migration. + +## Pull-Request-Handoff + +Die Beschreibung sollte enthalten: + +- fachliches Ergebnis +- Datenmodell- und API-Auswirkung +- ausgeführte Tests +- erforderliche manuelle Migration oder GUI-Prüfung +- bekannte Einschränkungen oder bewusst verschobene Arbeit diff --git a/docs/local-db-circuit-first-migration.md b/docs/local-db-circuit-first-migration.md index 784eb5a..206d8ff 100644 --- a/docs/local-db-circuit-first-migration.md +++ b/docs/local-db-circuit-first-migration.md @@ -2,6 +2,10 @@ This project uses SQLite at `data/leistungsbilanz.db` and Drizzle migrations in `src/db/migrations`. +This document is an upgrade runbook for databases created before the Circuit-First +cutover. A clean installation only needs the normal `db:migrate` and schema +verification steps documented in the main README. + ## Safe command order 1. Backup local DB (required before schema/data migration) diff --git a/docs/project-history-and-external-model-architecture.md b/docs/project-history-and-external-model-architecture.md index 6c7744f..c4eea7d 100644 --- a/docs/project-history-and-external-model-architecture.md +++ b/docs/project-history-and-external-model-architecture.md @@ -129,13 +129,19 @@ Drizzle schemas and migrations are dialect-specific and will require a deliberat ## Near-Term Refactoring Constraints -Before implementing the future features: +Completed foundation: -- add real SQLite rollback tests around the persistence boundary -- stop adding direct imports of the global SQLite client to domain services -- extract transaction ownership from oversized repositories incrementally -- modularize editor history commands independently from UI rendering -- preserve stable domain IDs during legacy cleanup +- real SQLite commit/rollback tests cover critical multi-write commands +- transaction ownership for row moves, synchronization, renumbering and migration + is isolated in injected persistence adapters +- database backup and independent restore verification are automated +- the Consumer application path is removed and stable domain IDs are preserved +- editor grid projection and safety rules are separated from React rendering + +Remaining constraints before implementing history: + +- model project-scoped command descriptions independently from React callbacks +- route all future history-enabled mutations through one project revision boundary - do not model IFCGUID as an overloaded circuit equipment identifier - keep database backup/restore checks separate from project history tests diff --git a/docs/spec/07-implementation-phases-todo.md b/docs/spec/07-implementation-phases-todo.md index d44bdfb..871e0a3 100644 --- a/docs/spec/07-implementation-phases-todo.md +++ b/docs/spec/07-implementation-phases-todo.md @@ -452,3 +452,13 @@ Acceptance criteria: - an LLM receives domain invariants, current module boundaries and deferred architecture direction without relying on stale legacy files - every README command and internal documentation link is verified - production instructions describe a real tested deployment path or clearly state that none is supported yet + +Implemented handoff: + +- README is a concise setup and project entry point without prototype status lists +- `docs/README.md` separates current, operational, future, specification and archived material +- current runtime, module boundaries and upgrade-only legacy data are documented explicitly +- contributor workflow covers clean databases, safe demo data, migrations, tests and commits +- development Compose is clearly separated from the currently unsupported production deployment +- `AGENTS.md` points LLM-assisted work to supported code paths and deferred architecture +- obsolete frontend placeholder documents were removed and early Codex prompts were archived diff --git a/package.json b/package.json index 5f2c2f6..9861577 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "leistungsbilanz", "version": "1.0.0", - "description": "", + "description": "Spreadsheet-style circuit list editor for electrical distribution planning", "main": "dist/server/index.js", "scripts": { "dev": "npm run dev:api", diff --git a/src/frontend/pages/README.md b/src/frontend/pages/README.md deleted file mode 100644 index 7da72fe..0000000 --- a/src/frontend/pages/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Frontend Placeholder - -Frontend implementation will move here in the next step (React/Next.js). -The backend API, domain logic, and SQLite persistence are now prepared. - diff --git a/src/frontend/utils/README.md b/src/frontend/utils/README.md deleted file mode 100644 index 9f3f262..0000000 --- a/src/frontend/utils/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# Frontend Utils Placeholder - -Shared UI utility helpers will be implemented during the Next.js migration step. -