119 lines
4.8 KiB
Markdown
119 lines
4.8 KiB
Markdown
# 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.
|
|
|
|
## Frontend Grid Modules
|
|
|
|
- `circuit-tree-editor.tsx` owns React state, API commands, undo/redo and drag-and-drop orchestration.
|
|
- `circuit-grid-model.ts` owns column metadata, circuit/device cell ownership, value projection, formatting, numeric parsing and block sort values.
|
|
- `circuit-grid-projection.ts` owns block-preserving filtering/sorting and the normalized visible row projection.
|
|
- `circuit-grid-insertion.ts` resolves insertion intent and insertion sort positions.
|
|
- `circuit-grid-safety.ts` resolves delete intent, BMK conflicts and cross-section move confirmation requirements.
|
|
|
|
The pure grid modules have no React state and are covered by focused unit tests. This keeps circuit/device ownership rules testable while the editor UI is split incrementally.
|
|
|
|
## 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
|
|
- voltage and optional control requirement for future sizing
|
|
- 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.
|
|
- 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
|
|
|
|
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`
|
|
|
|
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).
|
|
|
|
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.
|