Align documentation with clean baseline
This commit is contained in:
@@ -4,9 +4,8 @@
|
||||
|
||||
This document records the agreed and implemented behavior for
|
||||
distribution-board components, protected circuit groups and circuit
|
||||
protection devices. Delivery phases A through E are complete. Phase F retains
|
||||
the final GUI checklist; the current runtime paths are documented in
|
||||
`docs/current-architecture.md`.
|
||||
protection devices. Delivery phases A through F are complete. The current
|
||||
runtime paths are documented in `docs/current-architecture.md`.
|
||||
|
||||
Full rule-based protection and cable sizing is deliberately deferred. This
|
||||
phase establishes the structure and manually selected technical values that a
|
||||
@@ -34,7 +33,7 @@ later calculation and warning engine will evaluate.
|
||||
- channel-level relationships between actors and controlled circuits
|
||||
- PostgreSQL or multi-user operation
|
||||
|
||||
## Existing Model Audit
|
||||
## Implemented Model Boundary
|
||||
|
||||
### Keep
|
||||
|
||||
@@ -44,33 +43,28 @@ later calculation and warning engine will evaluate.
|
||||
- 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
|
||||
- `CircuitSection` is the persisted representation of a protected circuit
|
||||
group.
|
||||
- Grid projection remains separate from persisted domain structure.
|
||||
|
||||
### Change
|
||||
|
||||
- A `CircuitSection` gains an explicit category and group number and represents
|
||||
- A `CircuitSection` has an explicit category and group number and represents
|
||||
one protected circuit group.
|
||||
- Circuit protection changes from loosely related flat strings to an explicit
|
||||
- Circuit protection uses 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.
|
||||
- New distribution boards create exactly three default groups.
|
||||
|
||||
### Remove Eventually
|
||||
### Remaining Model Cleanup
|
||||
|
||||
- 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.
|
||||
- The older optional `rcdAssignment` circuit field still exists separately
|
||||
from the explicit group relationship. Removing it requires its own reviewed
|
||||
domain and UI change; it is not a compatibility path for pre-release data.
|
||||
|
||||
## Target Domain Structure
|
||||
|
||||
@@ -464,7 +458,7 @@ Every command must:
|
||||
- commit the domain mutation, revision and history transition atomically
|
||||
- remain undoable and redoable after application restart
|
||||
|
||||
## Snapshot and Transfer Compatibility
|
||||
## Snapshot and Transfer Boundary
|
||||
|
||||
The supported logical project snapshot and portable JSON transfer must include:
|
||||
|
||||
@@ -473,28 +467,15 @@ The supported logical project snapshot and portable JSON transfer must include:
|
||||
- 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.
|
||||
The clean pre-release baseline uses project-state schema version `1`. It
|
||||
contains the complete supported structure above and is shared by logical
|
||||
snapshots, restore, Undo/Redo and portable JSON transfer. Payloads from earlier
|
||||
development schemas are intentionally unsupported and rejected before any
|
||||
write.
|
||||
|
||||
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.
|
||||
Migration `0000` creates the complete relational model on an empty database.
|
||||
New defaults apply when boards, groups or circuits are created; they never
|
||||
silently overwrite a planner's later selection.
|
||||
|
||||
## Later Sizing and Warning Engine
|
||||
|
||||
@@ -544,7 +525,7 @@ Acceptance:
|
||||
- invalid rating/type/field combinations are rejected
|
||||
- defaults produce the exact agreed values
|
||||
|
||||
### B. Persistence and Compatibility Model
|
||||
### B. Persistence and Snapshot Model
|
||||
|
||||
Status: Complete.
|
||||
|
||||
@@ -552,44 +533,31 @@ Status: Complete.
|
||||
- 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
|
||||
- create the complete relational baseline schema
|
||||
- include the model in snapshots and portable transfers
|
||||
- preserve identifiers and protection values within supported project state
|
||||
|
||||
Implemented in B1:
|
||||
Implemented persistence:
|
||||
|
||||
- additive migration `0024` adds group identity to circuit sections and maps
|
||||
the three established sections to group 1 without changing UUIDs
|
||||
- baseline migration `0000` creates group identity, components and protection
|
||||
state directly for clean installations
|
||||
- separate component and circuit/component protection tables preserve the
|
||||
one-to-one ownership boundaries
|
||||
- a trigger-maintained circuit-list registry rejects normalized BMK collisions
|
||||
across circuits and distribution-board components
|
||||
- the existing flat circuit protection fields remain untouched until their
|
||||
deterministic snapshot/runtime transition is implemented
|
||||
- clean and populated pre-migration databases are covered by migration tests
|
||||
- newly created legacy-compatible board structures receive the same initial
|
||||
group identity while their persisted command format remains unchanged
|
||||
|
||||
Implemented in B2:
|
||||
|
||||
- snapshot schema version 7 includes group identity, distribution-board
|
||||
- snapshot schema version `1` includes group identity, distribution-board
|
||||
components and both one-to-one protection collections
|
||||
- capture, named and automatic snapshots, restore, Undo/Redo and portable JSON
|
||||
transfers preserve the complete new relational state
|
||||
- duplicate imports remap component UUIDs and both protection-owner references
|
||||
together with the existing project structure
|
||||
- versions 1 through 6 remain readable; version 6 maps the three established
|
||||
section keys to group 1 and leaves new collections empty
|
||||
- older flat circuit protection values remain present and are not guessed into
|
||||
strict new protection configurations
|
||||
- current snapshots reject invalid ownership, duplicate group numbers,
|
||||
- snapshots reject invalid ownership, duplicate group numbers,
|
||||
cross-entity BMKs and invalid protection configurations before persistence
|
||||
|
||||
Acceptance:
|
||||
|
||||
- a current database migrates without data loss
|
||||
- an empty database creates the complete schema
|
||||
- old supported snapshots and transfers upgrade deterministically
|
||||
- unsupported pre-release snapshots and transfers are rejected before writing
|
||||
- BMK collisions across circuits and components are rejected
|
||||
|
||||
### C. Persistent Commands and Board Defaults
|
||||
@@ -603,14 +571,13 @@ Status: Complete.
|
||||
|
||||
Implemented in C1:
|
||||
|
||||
- `distribution-board.insert` schema version 3 carries stable UUIDs for three
|
||||
- `distribution-board.insert` schema version `1` carries stable UUIDs for three
|
||||
initial groups, main switch `-Q0` and surge protective device `-FA`
|
||||
- its inverse verifies and removes the unchanged complete structure; Redo
|
||||
restores the same UUIDs
|
||||
- a late revision/history failure rolls back board, list, groups and components
|
||||
together
|
||||
- stored schema versions 1 and 2 retain four legacy sections and receive no
|
||||
invented components
|
||||
- unsupported command schema versions are rejected
|
||||
|
||||
Implemented in C2a1:
|
||||
|
||||
@@ -819,13 +786,13 @@ checklist are complete.
|
||||
Acceptance:
|
||||
|
||||
- documentation distinguishes implemented behavior from later sizing
|
||||
- clean install and migrated database both work
|
||||
- clean installation and baseline migration 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.
|
||||
- Incorrect implicit BMK changes:
|
||||
preserve identifiers during sorting and require explicit renumbering.
|
||||
- Cross-entity BMK collisions:
|
||||
enforce one transaction-level uniqueness boundary for the complete list.
|
||||
- Partial destructive writes:
|
||||
@@ -836,8 +803,9 @@ Acceptance:
|
||||
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.
|
||||
- Future snapshot evolution:
|
||||
introduce a new explicit schema version and upgrader only after defining its
|
||||
supported compatibility window.
|
||||
|
||||
## Resolved Implementation Decisions
|
||||
|
||||
@@ -848,6 +816,6 @@ Acceptance:
|
||||
- structural component rows remain outside editable-cell filtering and
|
||||
spreadsheet navigation; circuit filtering continues to preserve complete
|
||||
circuit blocks
|
||||
- explicit UI for converting retained legacy identifiers to grouped numbering
|
||||
- whether fixed header components become editable beyond name and BMK in this
|
||||
phase
|
||||
- explicit group renumbering updates grouped identifiers collision-safely
|
||||
- fixed header components remain read-only; mutable group and auxiliary
|
||||
components use their dedicated modals
|
||||
|
||||
Reference in New Issue
Block a user