jappel/leistungsbilanz-ts
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Julian Appel
2026-04-30 18:22:10 +02:00
commit c3e98af5b6
36 changed files with 4779 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/electrical-load-balance-requirements-context-dump.md
+666
View File
@@ -0,0 +1,666 @@
# 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:
```text
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
```text
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
```text
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:
```text
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
```text
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
```text
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:
```text
Device.name
Device.displayName
CircuitEntry.description
```
### Meaning
```text
Device.name
```
Internal or unique name of the device.
```text
Device.displayName
```
Default visible name of the device.
```text
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
```text
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:
```text
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:
```text
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
```text
DeviceList
- id
- name
- type
- devices: List<Device>
```
Possible values for `type`:
```text
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:
```text
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:
```text
addCount != quantity
```
Example:
```text
Device: Workplace socket
Add count: 5
Quantity per entry: 6
```
Result:
```text
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:
```text
roomNumber
roomName
```
## 16. Trade / Cost Group and Group
Entries shall be groupable by domain-specific criteria.
The planned fields are:
```text
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:
```text
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.