leistungsbilanz-ts/docs/spec/03-data-model-concept.md

Data Model Concept

This is a conceptual model for Codex. It is not a final database schema, but the implementation must preserve these domain relationships.

Core Concept

A distribution board contains a circuit list.

A circuit list contains sections.

A section contains circuits.

A circuit contains zero, one or multiple device rows.

A device row may be:

• linked to a project device
• manually entered without a linked project device

ProjectDevice

A project device is a reusable project-specific consumer or consumer group.

A project device can represent:

• one physical device
• a recurring device type
• a consumer group, for example six workstation sockets

User-facing fields:

• name
• displayName
• phaseType
• connectionKind
• costGroup
• category
• quantity
• powerPerUnit
• simultaneityFactor
• cosPhi
• totalPower
• remark

Notes:

• name is the technical or product-related name, for example E-Line Pro.
• displayName is a default display name used when inserting the device into the circuit list.
• After insertion, the circuit list display name is local and not automatically synchronized.
• quantity is allowed on project devices because a project device may represent a consumer group.
• Project devices must not define final cable or protection data.

Circuit

A circuit represents one outgoing circuit / equipment identifier in a distribution board section.

User-facing fields:

• equipmentIdentifier
• section
• displayName optional
• circuitTotalPower
• protectionType
• protectionRatedCurrent
• protectionCharacteristic
• cableType
• cableCrossSection
• cableLength
• rcdAssignment optional
• terminalDesignation optional
• voltage optional
• status optional
• isReserve optional
• remark optional

Circuit-level fields only:

• protection type
• protection rated current
• protection characteristic
• cable type
• cable cross-section
• cable length
• RCD assignment
• terminal designation
• circuit total power

Reason:

Protection and cable data are dimensioned for the complete circuit. They depend on the combined load, installation context, cable length, voltage drop and planning rules.

CircuitDeviceRow

A circuit device row represents a device assigned to a circuit.

User-facing fields:

• linkedProjectDeviceId optional
• name
• displayName
• phaseType
• connectionKind optional
• costGroup optional
• category optional
• level
• roomNumber
• roomName
• quantity
• powerPerUnit
• simultaneityFactor
• cosPhi
• rowTotalPower
• remark
• overriddenFields

A circuit device row can be manual.

A manual row has no linked project device.

A manual row can later be saved as a project device. After saving, the row becomes linked to the newly created project device.

Single-Device vs Multi-Device Display

If a circuit has exactly one device row, it is displayed as one compact circuit row.

If a circuit has multiple device rows, it is displayed as:

• one circuit summary row
• indented device rows below it

The circuit summary row shows:

• equipment identifier
• optional circuit display name
• circuit total power
• circuit-level protection data
• circuit-level cable data

The device rows show:

• individual device values
• quantity
• power
• cost group
• category
• room data
• remarks

Load Calculation

Device row load:

rowTotalPower = quantity × powerPerUnit × simultaneityFactor

Circuit total:

circuitTotalPower = sum(rowTotalPower of all device rows assigned to the circuit)

cosPhi is stored even if it is not visible in the default table view.

Later apparent power calculation:

apparentPower = totalActivePower / cosPhi

For circuits with multiple devices, apparent power should be calculated per device row and then summed. This avoids losing information when different devices have different power factors.