leistungsbilanz-ts/docs/electrical-load-balance-requirements-context-dump.md

Context Dump – Requirements for Electrical Load Balance and Circuit List Web App

1. Purpose

The application shall be a web app for creating electrical load balances and combined load balance / circuit lists for electrical planning.

The application shall primarily work in a tabular way.

2. Basic Structure

The application manages projects.

A project contains:

• Multiple distribution boards
• One project-specific device list

Each distribution board contains:

• Exactly one circuit list

Additionally, there is:

• One global device list
• One project-specific device list per project

Basic hierarchy:

Project
├── ProjectDeviceList
└── DistributionBoard
    └── CircuitList
        └── CircuitEntries

Global
└── GlobalDeviceList

3. Projects

A project is the top-level domain object.

A project can contain multiple distribution boards.

A project has one project-specific device list.

Devices from the project-specific device list can be used in the circuit lists of the distribution boards within that project.

Project Attributes

Project
- id
- name
- distributionBoards: List<DistributionBoard>
- projectDeviceList: DeviceList

4. Distribution Boards

A distribution board belongs to exactly one project.

A distribution board has exactly one circuit list.

A project can contain multiple distribution boards.

Each circuit list is therefore assigned to one distribution board.

DistributionBoard Attributes

DistributionBoard
- id
- name
- circuitList: CircuitList

5. Circuit Lists

A circuit list belongs to one distribution board.

The circuit list is table-based.

One row in the table is one circuit entry.

Multiple rows may reference the same circuit number.

This is required so that multiple different devices can be assigned to the same circuit.

Example:

Circuit 1 | Sockets        | 6 pcs
Circuit 1 | Lights         | 3 pcs
Circuit 1 | Fixed load     | 1 pc

This means that one circuit can be represented by multiple table rows.

CircuitList Attributes

CircuitList
- id
- name
- entries: List<CircuitEntry>

6. Circuit Entries

A circuit entry is one row in the circuit list.

A circuit entry can:

• Be linked to a device from the project-specific device list
• Exist without a device
• Exist without a device reference
• Be detached from the originally linked device
• Have its own description
• Have its own values

A circuit entry may be incomplete.

In principle, there are no required fields.

CircuitEntry Attributes

CircuitEntry
- id
- circuitNumber
- description
- roomNumber
- roomName
- device
- isLinkedToDevice
- quantity
- unitPower
- simultaneityFactor
- cosPhi
- totalPower
- deviceType
- phaseType
- tradeOrCostGroup
- group
- protectionType
- protectionRatedCurrent
- protectionCharacteristic
- cableType
- cableCrossSection
- comment

7. Circuit Entry Description

The description of a circuit entry is independent from:

• The device name
• The device display name
• The device link

Even if a circuit entry is linked to a device, the circuit entry description can always be overwritten manually.

There are therefore three different naming fields:

Device.name
Device.displayName
CircuitEntry.description

Meaning

Device.name

Internal or unique name of the device.

Device.displayName

Default visible name of the device.

CircuitEntry.description

Concrete description in the circuit list. This can be manually overwritten.

8. Devices

The application shall support configurable devices.

A device can represent either:

• A single device
• A collection/group of devices

Examples:

• Single pendant light
• Socket group with six sockets
• Workplace connection group
• Fixed load

Device Attributes

Device
- id
- name
- displayName
- deviceType
- phaseType
- quantity
- unitPower
- cosPhi
- tradeOrCostGroup

Attribute Meaning

name

Internal or unique name.

Used to distinguish similar devices.

displayName

Default visible name.

Multiple devices may have the same display name.

deviceType

The type of device.

Examples:

• Light
• Socket
• Fixed connection
• Generic
• Other values to be defined later

phaseType

Defines whether the device is single-phase or three-phase.

Examples:

• Single-phase
• Three-phase

quantity

Default quantity of the device.

This allows a device to be used either as a single device or as a collection.

Example:

Device: Socket group 6x
quantity: 6
unitPower: 100 W

unitPower

Power of one individual device or element.

cosPhi

Power factor.

tradeOrCostGroup

Assignment to a trade or cost group.

9. Device Name and Display Name

A device needs both a name and a displayName.

Reason:

Two devices may look the same in the circuit list but still be internally different.

Example:

Device 1:
name: Pendant light high occupancy
displayName: Pendant light

Device 2:
name: Pendant light low occupancy
displayName: Pendant light

This allows internally different devices to be displayed with the same name in the circuit list.

10. Device Lists

There are two types of device lists:

1. Global device list
2. Project-specific device list

Global Device List

The global device list contains generally reusable devices.

It is intended to be used across projects.

Project-Specific Device List

The project-specific device list belongs to a specific project.

It contains devices that can be used within that project.

Devices from this list can be selected in the circuit lists of the project's distribution boards.

DeviceList Attributes

DeviceList
- id
- name
- type
- devices: List<Device>

Possible values for type:

global
project

11. Copying Devices Between Device Lists

Devices shall be copyable between the global device list and project-specific device lists.

A device can be copied:

• From the global device list to a project-specific device list
• From a project-specific device list to the global device list

Copying means:

• A separate device is created in the target list
• Permanent synchronization between the original device and the copied device is not defined as a requirement

12. Device Link Between Device and Circuit Entry

A circuit entry can be linked to a device from the project-specific device list.

When the link is active, device values can be used in the circuit entry.

If the underlying device is changed, all still-linked circuit entries shall be updated.

The link can be enabled or disabled per circuit entry.

If a circuit entry is detached from the device:

• The circuit entry remains in place
• The circuit entry keeps its own values
• Future changes to the device no longer affect that circuit entry

A circuit entry may also exist without a device and without a device reference.

13. Quantity

There is a quantity on the device and a quantity on the circuit entry.

Device Quantity

The device quantity describes the default scope of a device.

It allows devices to represent either single devices or collections.

Example:

Device: Socket group 6x
quantity: 6
unitPower: 100 W

Circuit Entry Quantity

The circuit entry quantity describes the concrete quantity used in the individual circuit entry.

It can be prefilled from the device quantity when a circuit entry is created from a device.

It can be changed in the circuit entry.

Add Count

When adding a device to a circuit list, there shall be a separate value defining how many circuit entries shall be created.

Important distinction:

addCount != quantity

Example:

Device: Workplace socket
Add count: 5
Quantity per entry: 6

Result:

5 circuit entries
Each circuit entry has quantity = 6

14. Total Power

The total power shall be calculated automatically.

The total power is an attribute of the circuit entry.

The calculation is based at least on:

• quantity
• unitPower
• simultaneityFactor

The exact calculation logic can be specified later.

15. Rooms

Rooms are represented by two fields:

roomNumber
roomName

16. Trade / Cost Group and Group

Entries shall be groupable by domain-specific criteria.

The planned fields are:

tradeOrCostGroup
group

These fields shall help treat similar elements together.

17. Table Functions

The circuit list shall support common table operations.

Defined operations are:

• Create entry
• Edit entry
• Delete entry
• Duplicate entry
• Copy entry to another circuit list
• Add device as entry
• Add device multiple times as entries
• Set quantity within an entry

General requirement:

• All common table manipulations shall be possible

Additional table functions may be specified later, for example:

• Sorting
• Filtering
• Reordering
• Multi-selection
• Bulk editing

18. Required Fields

In principle, there shall be no required fields.

This means:

• Entries may be incomplete
• A circuit entry may exist without a device
• A circuit entry may exist without a device reference
• Values can be completed later

19. Selection Lists

The application shall support fixed selection lists.

The exact selection lists will be defined later.

Current possible candidates based on the requirements are:

• deviceType
• phaseType
• tradeOrCostGroup
• group
• protectionType
• protectionCharacteristic
• cableType
• cableCrossSection

These lists are not yet finally specified.

20. Copying and Duplicating

Circuit entries shall be duplicatable.

Circuit entries shall be copyable to other circuit lists.

Devices shall be copyable between the global device list and project-specific device lists.

When adding a device to a circuit list, the user shall be able to define how many circuit entries shall be created from it.

Open point:

• Whether a device link is kept or detached when copying a circuit entry to another circuit list is not yet specified.

21. Simplified Class Model

The model shall use multiple classes but shall not be overly fragmented.

Current final class model:

Project
- id
- name
- distributionBoards: List<DistributionBoard>
- projectDeviceList: DeviceList

DistributionBoard
- id
- name
- circuitList: CircuitList

CircuitList
- id
- name
- entries: List<CircuitEntry>

CircuitEntry
- id
- circuitNumber
- description
- roomNumber
- roomName
- device: Device
- isLinkedToDevice
- quantity
- unitPower
- simultaneityFactor
- cosPhi
- totalPower
- deviceType
- phaseType
- tradeOrCostGroup
- group
- protectionType
- protectionRatedCurrent
- protectionCharacteristic
- cableType
- cableCrossSection
- comment

Device
- id
- name
- displayName
- deviceType
- phaseType
- quantity
- unitPower
- cosPhi
- tradeOrCostGroup

DeviceList
- id
- name
- type
- devices: List<Device>

22. Central Domain Rules

1. A project contains multiple distribution boards.

2. Each distribution board contains exactly one circuit list.

3. A circuit list consists of circuit entries.

4. One row in the circuit list is one circuit entry.

5. Multiple circuit entries may have the same circuit number.

6. This allows multiple different devices to be assigned to one circuit.

7. A circuit entry can be linked to a device.

8. A circuit entry can exist without a device.

9. A circuit entry can exist without a device reference.

10. The link between a circuit entry and a device can be detached per entry.

11. If a device is changed, all still-linked circuit entries are updated.

12. Detached circuit entries are no longer changed by later device changes.

13. A device has a default quantity.

14. A circuit entry has its own quantity.

15. The quantity on the device can be used as a default value for new circuit entries.

16. The description of a circuit entry can be overwritten independently from the linked device.

17. The total power of a circuit entry is calculated automatically.

18. A project has a project-specific device list.

19. Additionally, there is a global device list.

20. Devices can be copied between the global device list and project-specific device lists.

21. Circuit entries can be duplicated.

22. Circuit entries can be copied to other circuit lists.

23. When adding a device, the user can define how many circuit entries shall be created.

24. In principle, there are no required fields.

25. The application shall support fixed selection lists. Details will be specified later.

23. Open Points

The following points are not yet finally specified:

1. Exact formula for calculating totalPower.

2. Exact list of fields synchronized while a circuit entry is linked to a device.

3. Whether the device link is kept or detached when copying a circuit entry to another circuit list.

4. Final selection lists and their values.

5. Exact behavior of table functions such as sorting, filtering, multi-selection, and bulk editing.

6. Whether global devices and project devices remain permanently independent after copying, or whether optional synchronization should be supported later.