leistungsbilanz-ts/docs/circuit-list-editor-architecture.md

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.