Documentation

2026-05-07 22:55:15 +02:00
parent b1e19a88d5
commit 7580ad0ade
11 changed files with 584 additions and 1 deletions
@@ -0,0 +1,96 @@
+# Circuit List Editor Architecture
+
+## Purpose
+
+The circuit-list editor is a circuit-first planning workspace for distribution-board design. It is optimized for spreadsheet-like editing while preserving electrical domain boundaries: circuit-level data stays on circuits, and load rows stay inside circuits.
+
+## Domain Model Overview
+
+- `CircuitSection`
+  - Groups circuits by planning section (for example lighting, single-phase, three-phase).
+  - Owns section metadata (`key`, `displayName`, `prefix`, ordering).
+- `Circuit`
+  - Core electrical unit in the list.
+  - Owns circuit-level identifiers and technical data:
+    - `equipmentIdentifier` (BMK)
+    - protection data
+    - cable data
+    - reserve state
+    - circuit-level remark/status
+- `CircuitDeviceRow`
+  - Load/device line inside a circuit.
+  - Owns row-level load and context values:
+    - `quantity`
+    - `powerPerUnit`
+    - `simultaneityFactor`
+    - `cosPhi`
+    - room snapshots
+    - category/cost group and related row attributes
+- `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.
+
+## Why A Circuit Is Not One Row
+
+A circuit can contain zero, one, or many device rows. Treating a circuit as a single row breaks:
+
+- BMK ownership (belongs to circuit, not each device row)
+- circuit-level protection/cable fields
+- grouped calculations and circuit move/reorder semantics
+
+The tree model keeps circuit identity stable while allowing row-level load composition.
+
+## Rendering Model: Single vs Multi Device
+
+- Single-device circuit:
+  - Rendered as compact combined row (`circuitCompact`) for fast editing.
+- Multi-device circuit:
+  - Rendered as one circuit summary row (`circuitSummary`) plus indented `deviceRow` entries.
+
+This keeps visual density high without losing ownership boundaries.
+
+## Reserve / Empty Circuits
+
+Circuits with no device rows are rendered as reserve rows (`reserveCircuit`).  
+Section-level `-frei-` placeholder rows represent insertion targets for creating a new circuit in that section.
+
+## BMK Ownership (`equipmentIdentifier`)
+
+`equipmentIdentifier` / BMK is circuit-owned (`Circuit.equipmentIdentifier`).
+
+- Device rows do not have their own BMK.
+- Existing identifiers must stay stable unless explicitly changed by user action.
+- Renumbering is explicit, not implicit on move/sort/delete.
+
+## Data Ownership Split: Circuit vs Device Row
+
+Circuit-level fields on `Circuit`:
+
+- protection type/rating/characteristic
+- cable type/cross-section/length
+- RCD/terminal/status
+
+Device-level load fields on `CircuitDeviceRow`:
+
+- quantity, power per unit, simultaneity, cosPhi
+- row naming/categorization and room snapshots
+
+This split matches execution-design workflows where many loads share one protective path.
+
+## Calculated Totals
+
+- `rowTotalPower` is calculated per `CircuitDeviceRow`.
+- `circuitTotalPower` is calculated as sum of all row totals in one circuit.
+
+Totals are exposed by the tree response and shown in computed read-only cells.
+
+## Frontend Route
+
+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.