From a72d2c76e096eded152f7fdc8d9061506eba72a4 Mon Sep 17 00:00:00 2001 From: Julian Appel Date: Thu, 30 Jul 2026 18:52:26 +0200 Subject: [PATCH] Specify protected circuit groups --- docs/README.md | 1 + docs/revit-requirements-llm-context.md | 2 +- docs/spec/07-implementation-phases-todo.md | 38 +- docs/spec/08-current-product-backlog.md | 14 +- ...-board-components-and-protection-groups.md | 636 ++++++++++++++++++ 5 files changed, 686 insertions(+), 5 deletions(-) create mode 100644 docs/spec/09-distribution-board-components-and-protection-groups.md diff --git a/docs/README.md b/docs/README.md index b7b8409..652a097 100644 --- a/docs/README.md +++ b/docs/README.md @@ -43,6 +43,7 @@ Limitierungen und Roadmap. - [Datenmodellkonzept](spec/03-data-model-concept.md) - [UI- und Interaktionsanforderungen](spec/04-ui-interaction-requirements.md) - [Verknüpfte Projektgeräte und Synchronisierung](spec/05-linked-devices-and-sync.md) +- [Verteilerkomponenten und Schutzgruppen](spec/09-distribution-board-components-and-protection-groups.md) ## Archiv diff --git a/docs/revit-requirements-llm-context.md b/docs/revit-requirements-llm-context.md index 060517d..965eb47 100644 --- a/docs/revit-requirements-llm-context.md +++ b/docs/revit-requirements-llm-context.md @@ -264,6 +264,6 @@ nur Architekturvorschläge des LLM sind. - `docs/spec/03-data-model-concept.md` – Datenmodellkonzept - `docs/spec/05-linked-devices-and-sync.md` – Regeln für Projektgeräte und kontrollierte Synchronisierung -- `docs/spec/07-implementation-phases-todo.md` – Roadmap, insbesondere Phase 13 +- `docs/spec/07-implementation-phases-todo.md` – Roadmap, insbesondere Phase 14 - `docs/circuit-list-editor-known-limitations.md` – noch nicht implementierte Funktionen diff --git a/docs/spec/07-implementation-phases-todo.md b/docs/spec/07-implementation-phases-todo.md index 6bce04b..03b6a4c 100644 --- a/docs/spec/07-implementation-phases-todo.md +++ b/docs/spec/07-implementation-phases-todo.md @@ -496,7 +496,41 @@ Acceptance criteria: - restoring an older state does not delete intervening history - concurrent stale commands cannot silently overwrite newer project state -## Phase 13: External Model Round-Trip +## Phase 13: Distribution Board Components and Protection Groups + +Goal: + +Extend the circuit list into the structural basis of a tabular single-line +diagram before defining Revit parameter exchange. + +Detailed specification: + +- `docs/spec/09-distribution-board-components-and-protection-groups.md` + +Delivery: + +- add typed protection-device catalogs and defaults +- evolve sections into repeatable category-specific circuit groups +- add fixed, group and auxiliary distribution-board components +- give every new circuit one explicit protection device +- implement nested BMK generation, same-category group moves and explicit + collision-safe group renumbering +- preserve all new state through commands, snapshots, transfer and persistent + Undo/Redo +- project the header, groups and auxiliary footer in the spreadsheet editor + +Acceptance criteria: + +- new boards contain the main switch, surge protective device and three default + groups +- all circuits and components have list-wide unique BMKs +- circuit reordering keeps identifiers while cross-group moves assign the next + target-group identifier +- destructive group operations are confirmed, atomic and fully undoable +- existing supported project data migrates without silently changing BMKs or + protection selections + +## Phase 14: External Model Round-Trip Goal: @@ -521,7 +555,7 @@ Acceptance criteria: PostgreSQL should be introduced when shared multi-user operation, background jobs or operational scale justify it. External-object count alone does not require an immediate migration. -## Phase 14: Documentation and Collaboration Handoff +## Phase 15: Documentation and Collaboration Handoff Goal: diff --git a/docs/spec/08-current-product-backlog.md b/docs/spec/08-current-product-backlog.md index aafc962..e2d9cfc 100644 --- a/docs/spec/08-current-product-backlog.md +++ b/docs/spec/08-current-product-backlog.md @@ -8,6 +8,15 @@ requirements and intended sequencing, not proof of implementation. - Collect the remaining editor interaction issues before changing additional behavior. +## Distribution Board Components and Protection Groups + +- [ ] Implement the agreed protected circuit-group and distribution-board + component model in phased work packages. +- [ ] Keep full electrical sizing and cable-dimensioning rules separate until + the planner supplies the calculation requirements. +- Detailed specification: + `docs/spec/09-distribution-board-components-and-protection-groups.md` + ## First Release Baseline Complete this immediately before the first supported release, once the schema @@ -90,5 +99,6 @@ and initial feature set are frozen: 3. [x] Snapshot-to-revision descriptions and history presentation. 4. [x] Distribution-board power summary and project column layout. -The Revit/CSV/IFCGUID round-trip remains a separate jointly planned phase and -must not be inferred from these tasks. +The Revit/CSV/IFCGUID round-trip follows the distribution-board component +foundation as a separate jointly planned phase and must not be inferred from +these tasks. diff --git a/docs/spec/09-distribution-board-components-and-protection-groups.md b/docs/spec/09-distribution-board-components-and-protection-groups.md new file mode 100644 index 0000000..a1a3d4d --- /dev/null +++ b/docs/spec/09-distribution-board-components-and-protection-groups.md @@ -0,0 +1,636 @@ +# Distribution Board Components and Protection Groups + +## Status + +This document defines the agreed target behavior for distribution-board +components, protected circuit groups and circuit protection devices. It is a +future specification, not proof of implementation. + +Full rule-based protection and cable sizing is deliberately deferred. This +phase establishes the structure and manually selected technical values that a +later calculation and warning engine will evaluate. + +## Goals + +- represent the circuit list as the basis of a tabular single-line diagram +- list incoming, group-level and auxiliary distribution-board components with + stable equipment identifiers +- support multiple independently protected groups for lighting, single-phase + and three-phase outgoing circuits +- give every newly created outgoing circuit one explicit protection device +- preserve the existing distinction between a circuit and its device rows +- keep every structural change atomic, revisioned and persistently undoable +- prepare stable target fields for the later Revit round-trip + +## Non-Goals + +- norm-compliant protection or cable sizing +- automatic creation of additional groups based on the incoming rating +- automatic phase balancing +- manufacturer-specific product catalogs +- automatic equipment-identifier generation for auxiliary components +- channel-level relationships between actors and controlled circuits +- PostgreSQL or multi-user operation + +## Existing Model Audit + +### Keep + +- `Circuit` remains the outgoing-circuit aggregate. +- `CircuitDeviceRow` remains a load assigned to a circuit and never receives + its own protection device or equipment identifier. +- Circuit-level load, cable and control fields remain circuit-owned. +- Existing stable UUIDs, project revisions, snapshots and persistent Undo/Redo + remain authoritative. +- `CircuitSection` remains the migration starting point for a protected circuit + group. +- Grid projection remains separate from persisted domain structure. + +### Change + +- A `CircuitSection` gains an explicit category and group number and represents + one protected circuit group. +- Circuit protection changes from loosely related flat strings to an explicit + one-to-one protection-device model. +- Distribution-board components become independent BMK-bearing list entries. +- Equipment-identifier uniqueness covers circuits and all distribution-board + components in the complete circuit list. +- Moving a circuit to another group of the same category atomically assigns the + next identifier of the target group. +- New distribution boards create three default groups rather than treating the + optional unassigned compatibility section as a normal fourth group. + +### Remove Eventually + +- hard-coded assumptions that each category has exactly one section +- numbering that only understands `prefix + integer` +- free-text protection-device combinations that cannot be validated +- `rcdAssignment` as a substitute for an explicit group relationship + +Removal happens only after migrated state, snapshots, commands and the editor +use the replacement model. + +## Target Domain Structure + +```text +Project +└── DistributionBoard + └── CircuitList + ├── fixed header components + │ ├── Main switch + │ └── Surge protective device + ├── CircuitGroup 1..n + │ ├── optional upstream protection component + │ ├── optional group RCD component + │ └── Circuit 0..n + │ ├── ProtectionDevice exactly 1 + │ └── CircuitDeviceRow 0..n + └── auxiliary components 0..n +``` + +The hierarchy defines ownership and electrical grouping. It does not require +every level to be visually indented in the table. + +## Circuit Groups + +`CircuitSection` evolves into the circuit-group entity. A group has: + +- stable UUID +- circuit-list ownership +- category +- positive group number +- display name +- sort order +- optional upstream protection component +- optional group RCD component +- zero or more outgoing circuits + +Supported categories: + +- `lighting` +- `single_phase` +- `three_phase` + +Each new distribution board creates exactly: + +1. `Beleuchtung 1` +2. `1-phasig 1` +3. `3-phasig 1` + +Additional groups are created manually. A new group receives the highest +existing group number in its category plus one. Gaps are not filled +automatically. + +A group may have at most one upstream protection component and at most one +group RCD. Both are optional. Every circuit in the group remains downstream of +those group components until it is moved to another group. + +## Distribution-Board Components + +Every distribution-board component has: + +- stable UUID +- circuit-list ownership +- unique equipment identifier +- name +- role +- placement +- sort order within its placement + +Initial roles: + +- `main_switch` +- `surge_protective_device` +- `group_upstream_protection` +- `group_residual_current_protection` +- `auxiliary` + +Initial placement zones: + +- `header` +- `group` +- `footer` + +New distribution boards create exactly: + +- `-Q0`, name `Hauptschalter`, role `main_switch` +- `-FA`, name `Überspannungsableiter`, role + `surge_protective_device` + +These fixed components appear at the top and may initially have no further +technical product data. + +Auxiliary components initially require only: + +- manually entered equipment identifier +- name +- sort order + +Examples include KNX switching actuators, blind actuators, phase-monitoring +modules, DALI gateways, relays and other installed board equipment. They appear +after all circuit groups and can be reordered by drag-and-drop. Automatic BMK +suggestions and channel-to-circuit relationships are deferred. + +## Circuit Protection + +Every newly created outgoing circuit owns exactly one protection device. +`CircuitDeviceRow` does not own a protection device. + +The circuit and its protection device are projected as one circuit row. The +circuit equipment identifier is also the displayed identifier of its +protection device and must not be stored twice. + +Supported protection-device types: + +- `D02` +- `NH000` +- `NH00` +- `NH0` +- `NH1` +- `NH2` +- `NH3` +- `LS` +- `FI` +- `FI_LS` +- `AFDD` + +`D01` and `NH4` are intentionally excluded. + +## Protection-Device Fields + +All protection devices have: + +- type +- rated current in ampere + +Type-dependent fields: + +- D02 and NH: + - fuse utilization category `gG` or `gR` +- LS: + - trip characteristic `B`, `C`, `D` or `Z` +- FI: + - RCD type `A`, `AC`, `B` or `B+` + - rated residual current in milliampere +- FI/LS: + - trip characteristic `B`, `C`, `D` or `Z` + - RCD type `A`, `AC`, `B` or `B+` + - rated residual current in milliampere +- AFDD: + - trip characteristic `B`, `C`, `D` or `Z` + - no RCD type + - no rated residual current + +Poles are intentionally not stored. The circuit-group category supplies the +required phase context for the current scope. + +## Allowed Ratings + +### D02 + +`20, 25, 32, 35, 40, 50, 63 A` + +### NH000 and NH00 + +`6, 10, 16, 20, 25, 32, 35, 40, 50, 63, 80, 100, 125, 160 A` + +### NH0 + +`6, 10, 16, 20, 25, 32, 35, 40, 50, 63, 80, 100, 125, 160, 200, 224, 250 A` + +### NH1 + +`16, 20, 25, 32, 35, 40, 50, 63, 80, 100, 125, 160, 200, 224, 250 A` + +### NH2 + +`25, 32, 35, 40, 50, 63, 80, 100, 125, 160, 200, 224, 250, 300, 315, 355, 400 A` + +### NH3 + +`50, 63, 80, 100, 125, 160, 200, 224, 250, 315, 355, 400, 500, 630, 800 A` + +### LS, FI/LS and AFDD + +`6, 10, 13, 16, 20, 25, 32, 40, 50, 63, 80, 100, 125 A` + +### FI/RCD + +Rated currents: + +`16, 25, 40, 63, 80, 100, 125 A` + +Rated residual currents: + +`10, 30, 100, 300, 500 mA` + +The device type determines which values and characteristics are valid. UI, +request validation and domain validation use one shared catalog rather than +duplicated free-text rules. + +All supported devices that provide overcurrent protection may be selected as a +group upstream protection device. A standalone FI belongs in the separate +optional group-RCD role. + +## Default Protection Devices + +New circuits receive: + +- lighting: + - LS + - 10 A + - characteristic B +- single-phase: + - FI/LS + - 16 A + - characteristic B + - RCD type A + - 30 mA +- three-phase: + - FI/LS + - 16 A + - characteristic B + - RCD type A + - 30 mA + +A newly added group RCD defaults to: + +- FI +- 40 A +- RCD type A +- 30 mA + +An upstream protection component has no automatic default and is created only +when the planner requests it. + +## Equipment-Identifier Rules + +The leading hyphen is part of every generated identifier. + +Group 1 examples: + +```text +-1F1.0 upstream protection, lighting +-1Q1.0 group RCD, lighting +-1F1.1 first lighting circuit + +-2F1.0 upstream protection, single-phase +-2Q1.0 group RCD, single-phase +-2F1.1 first single-phase circuit + +-3F1.0 upstream protection, three-phase +-3Q1.0 group RCD, three-phase +-3F1.1 first three-phase circuit +``` + +Category numbers: + +- lighting: `1` +- single-phase: `2` +- three-phase: `3` + +Function letters: + +- overcurrent protection and outgoing circuit: `F` +- group RCD: `Q` + +The group number follows the function letter. `.0` is reserved for the group +component. Outgoing-circuit suffixes start at `.1`. + +Equipment identifiers must be unique across all circuits and components of the +complete circuit list, including header and footer components. + +Manual BMK edits must validate that same shared uniqueness boundary. + +## Reorder, Move and Renumber Behavior + +### Reorder Within One Group + +Changing circuit order changes only `sortOrder`. It never changes an equipment +identifier. + +### Move to Another Group + +A circuit may move only to another group of the same category. + +The move: + +1. finds the highest existing outgoing-circuit suffix in the target group +2. assigns that suffix plus one +3. moves the complete circuit, its one-to-one protection device and all device + rows +4. commits old and new group, position and identifier atomically + +Gaps are not filled. Undo restores the original group, sort position and +equipment identifier. Redo reapplies the same previously determined target +identifier rather than calculating another one. + +This automatic identifier change is specific to a cross-group move initiated +by the user. A reorder inside one group never renumbers. + +### Reorder Groups + +Changing group display order changes only group `sortOrder`. Group numbers and +all equipment identifiers remain unchanged. + +### Explicitly Renumber Groups + +Group renumbering is a separate explicit action. It: + +- changes group numbers according to the requested mapping +- preserves every outgoing circuit suffix +- updates optional `.0` group-component identifiers +- updates every affected circuit identifier +- resolves swaps through collision-safe temporary identifiers +- commits the complete mapping as one project revision + +Undo restores the exact previous group numbers and identifiers. + +## Delete Behavior + +A group may be deleted even when populated, but only after an explicit warning +that summarizes: + +- optional upstream protection +- optional group RCD +- number of circuits +- number of circuit device rows + +Confirmation deletes the complete group subtree atomically. The inverse +command stores the complete stable snapshots needed to restore all UUIDs, +fields, links, protection devices, group relationships, identifiers and sort +positions. + +A stale or partially changed subtree must not be silently deleted or restored. + +## UI Projection + +The circuit-list editor projects three fixed zones: + +1. header: + - `-Q0 Hauptschalter` + - `-FA Überspannungsableiter` +2. groups: + - group heading + - optional upstream protection row + - optional group RCD row + - circuit rows and their optional expanded device rows +3. footer: + - auxiliary distribution-board components + +Group indentation is optional presentation. Group ownership must remain clear +through headings, separators or a dedicated group indication. + +The grid remains a custom spreadsheet component: + +- static text by default +- edit mode only when invoked +- group and auxiliary-component drag handles +- clear valid and invalid drop indicators +- German user-facing labels + +Protection editing must show only fields valid for the selected device type. +Changing the type resets or explicitly confirms removal of fields that the new +type cannot use. + +## History and Command Boundary + +New project-scoped writes must use typed persistent commands and the existing +shared project-command transaction boundary. + +Required logical operations: + +- insert/update/delete auxiliary component +- reorder auxiliary components +- insert/update/delete group protection component +- insert/delete group +- reorder groups +- explicitly renumber groups +- move circuit between same-category groups with deterministic BMK assignment +- update circuit protection device + +Creating a distribution board includes its fixed components, three default +groups, circuit list and all stable UUIDs in one `distribution-board.insert` +command. + +Every command must: + +- require `expectedRevision` +- validate complete project/list/group ownership +- validate shared BMK uniqueness inside the write transaction +- contain deterministic forward and inverse data +- commit the domain mutation, revision and history transition atomically +- remain undoable and redoable after application restart + +## Snapshot and Transfer Compatibility + +The supported logical project snapshot and portable JSON transfer must include: + +- group category and group number +- fixed, group and auxiliary components +- circuit protection-device state +- all new component relationships and sort positions + +Introducing the model requires a snapshot-schema version increase and explicit +upgraders for supported older payloads. + +Database migration rules: + +- preserve all existing stable UUIDs +- preserve existing circuit equipment identifiers during schema migration +- map the existing lighting, single-phase and three-phase sections to group 1 + of the respective category +- preserve an existing unassigned section only when required by existing data; + it is not created for a new distribution board +- preserve existing flat circuit protection values when creating the new + one-to-one protection state +- do not silently replace an existing protection selection with a new default +- allow legacy identifiers to remain until an explicit, collision-safe + conversion or renumber action is approved + +New defaults apply to newly created circuits and boards, not as an implicit +rewrite of existing planning data. + +Historical persisted commands and snapshots that remain in the supported +compatibility window must still deserialize and execute after the migration. + +## Later Sizing and Warning Engine + +The selected protection device is the planner-owned value. Later sizing logic +will calculate a recommendation separately. + +Target behavior: + +```text +stored selection + -> calculation and validation + -> valid: no warning + -> invalid: colored warning plus recommended protection + -> user explicitly accepts or rejects the recommendation +``` + +The same pattern applies later to cable cross-section and length. Suggestions +never silently overwrite selected values. + +Dimensioning rules and additional inputs are defined in a separate future +specification supplied by the planner. + +## Delivery Phases + +### A. Catalog and Pure Domain Rules + +- introduce typed component roles, categories and protection-device types +- centralize rating and characteristic catalogs +- validate device-specific field combinations +- define default circuit and group-RCD protection values +- test numbering parsing and formatting independently from persistence + +Acceptance: + +- every agreed valid combination is accepted +- invalid rating/type/field combinations are rejected +- defaults produce the exact agreed values + +### B. Persistence and Compatibility Model + +- add group category and group number +- add distribution-board component persistence +- add one-to-one circuit protection persistence +- implement shared BMK uniqueness +- generate and inspect one additive migration +- add snapshot/transfer schema upgrade +- preserve existing identifiers and protection values + +Acceptance: + +- a current database migrates without data loss +- an empty database creates the complete schema +- old supported snapshots and transfers upgrade deterministically +- BMK collisions across circuits and components are rejected + +### C. Persistent Commands and Board Defaults + +- extend `distribution-board.insert` with fixed components and three groups +- implement component and group CRUD commands +- implement group and footer reordering +- add complete inverse snapshots and rollback tests + +Acceptance: + +- new boards contain the agreed fixed structure +- every structural write survives reload and supports Undo/Redo +- forced late failures leave no partial components or groups + +### D. Group Numbering and Circuit Moves + +- implement nested identifier generation +- support same-category cross-group circuit moves +- implement explicit collision-safe group renumbering +- implement confirmed populated-group deletion + +Acceptance: + +- target identifiers use highest suffix plus one +- reordering never renumbers +- cross-category moves are rejected +- group renumbering preserves circuit suffixes +- delete, move and renumber Undo restore exact prior UUIDs and BMKs + +### E. Editor Projection and Editing + +- render fixed header components +- render group components and circuit blocks +- render sortable auxiliary footer components +- add group management and destructive confirmations +- add type-dependent protection editing +- keep spreadsheet selection, keyboard and drag behavior coherent + +Acceptance: + +- the visible order is header, groups, footer +- users can create, configure, reorder and delete groups +- users can configure circuit and group protection without invalid fields +- device rows remain visually and technically subordinate to their circuit + +### F. Documentation and Full Verification + +- update current architecture, API and interaction documentation +- update demo/sample data +- run focused domain and transaction tests +- run the complete required test, build and type-check suite +- perform the agreed GUI test checklist + +Acceptance: + +- documentation distinguishes implemented behavior from later sizing +- clean install and migrated database both work +- snapshots, JSON transfer and Undo/Redo cover all new state + +## Risks and Mitigations + +- Mixed legacy and grouped BMKs: + preserve old identifiers and provide an explicit conversion path. +- Cross-entity BMK collisions: + enforce one transaction-level uniqueness boundary for the complete list. +- Partial destructive writes: + persist complete subtree commands through the shared transaction wrapper. +- Bloated grid logic: + add pure projection and ownership modules before React rendering changes. +- Invalid protection combinations: + use one shared typed catalog for UI, API and domain validation. +- Silent planning changes: + apply defaults only on creation and keep later recommendations explicit. +- Snapshot incompatibility: + version payloads and test every supported upgrade path. + +## Open Implementation Decisions + +These decisions may be resolved during the relevant delivery phase without +changing the agreed domain behavior: + +- exact relational implementation of the shared BMK ownership boundary +- presentation of group ownership through indentation, headings or a column +- filter behavior for structural component rows +- explicit UI for converting retained legacy identifiers to grouped numbering +- whether fixed header components become editable beyond name and BMK in this + phase