# 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 - 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 ``` ## 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 ``` 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 - projectDeviceList: DeviceList DistributionBoard - id - name - circuitList: CircuitList CircuitList - id - name - entries: List 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 ``` ## 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.