Align documentation with clean baseline
This commit is contained in:
@@ -74,8 +74,8 @@ Protected-board structure uses
|
||||
persisted inverse of a delete. The dispatcher also supports the documented
|
||||
project-device, project settings, distribution-board and project-location
|
||||
commands. The generic editor commands listed here use schema version `1`;
|
||||
older stored formats can remain supported by their owning command boundary.
|
||||
Unsupported types are rejected. Insert commands contain the complete entity or circuit block
|
||||
the clean pre-release baseline does not accept older development formats.
|
||||
Unsupported types or schema versions are rejected. Insert commands contain the complete entity or circuit block
|
||||
with stable ids; delete commands include the expected parent identity. Circuit
|
||||
snapshots contain zero, one or multiple complete device rows. Move commands
|
||||
contain each row's expected and target circuit plus its exact expected and
|
||||
|
||||
@@ -267,7 +267,7 @@ deshalb weder eine bestehende Projekt-ID noch `expectedRevision` annimmt. Das
|
||||
Ersetzen eines Projekts bleibt auf dessen Einstellungsmodal und den
|
||||
projektgebundenen Endpunkt beschränkt.
|
||||
`distribution-board.insert` versioniert die Anlage einer Verteilung mit
|
||||
Command-Schema 3 als vollständigen Block aus Verteilung, Stromkreisliste, den
|
||||
Command-Schema 1 als vollständigen Block aus Verteilung, Stromkreisliste, den
|
||||
drei Gruppen `Beleuchtung 1`, `1-phasig 1`, `3-phasig 1`, Hauptschalter `-Q0`
|
||||
und Überspannungsableiter `-FA`.
|
||||
Alle UUIDs entstehen vor dem Command und bleiben über Undo/Redo stabil.
|
||||
@@ -349,9 +349,9 @@ Teilwiederherstellungen.
|
||||
Der Circuit-Tree liefert zusätzlich `headerComponents`,
|
||||
gruppenbezogene `components` und `footerComponents`. Abschnitte enthalten
|
||||
optionale Gruppenkategorie und -nummer; Stromkreise und Gruppenkomponenten
|
||||
enthalten ihre optionale getrennte Schutzgerätekonfiguration. Die bisherigen
|
||||
flachen Stromkreis-Schutzfelder bleiben während der Übergangsphase additiv
|
||||
erhalten. Separate aktive Read-Repositories lesen Komponenten- und beide
|
||||
enthalten ihre getrennte Schutzgerätekonfiguration. Die
|
||||
1:1-Schutzgerätetabellen sind die einzige unterstützte Quelle dieser Daten.
|
||||
Separate aktive Read-Repositories lesen Komponenten- und beide
|
||||
Schutzgerätetabellen; Schreibzugriffe bleiben ausschließlich in Commands.
|
||||
`src/frontend/utils/circuit-structure-projection.ts` projiziert diesen Tree
|
||||
rein und deterministisch in die drei Zonen Kopf, vollständige Gruppen und Fuß.
|
||||
@@ -381,12 +381,12 @@ Projektzugehörigkeit und schreibt Schutzgerät, Revision und Historienübergang
|
||||
atomar. Benutzer können Schutzdaten anlegen oder ändern, aber nicht entfernen;
|
||||
Undo einer erstmaligen Anlage darf den zuvor fehlenden Datensatz exakt
|
||||
wiederherstellen.
|
||||
Der vollständige `CircuitSnapshot` kann rückwärtskompatibel einen
|
||||
`protectionDevice`-Datensatz enthalten. Neue gruppierte Stromkreise und durch
|
||||
Geräteverschiebung erzeugte Zielstromkreise verwenden die vereinbarten
|
||||
Der vollständige `CircuitSnapshot` enthält den zugehörigen
|
||||
`protectionDevice`-Datensatz, sofern einer vorhanden ist. Neue Stromkreise und
|
||||
durch Geräteverschiebung erzeugte Zielstromkreise verwenden die vereinbarten
|
||||
Kategorie-Standardwerte und schreiben Schutzgerät, Stromkreis sowie
|
||||
Gerätezeilen atomar. Delete/Undo erfasst denselben Datensatz vollständig.
|
||||
Im Editor sind die bisherigen Schutzspalten deshalb nur noch eine
|
||||
Im Editor sind die Schutzspalten deshalb eine
|
||||
schreibgeschützte Projektion der 1:1-Daten; Änderungen erfolgen über ein
|
||||
geräteabhängiges Schutzgeräte-Modal und `circuit-protection.update`.
|
||||
Gruppen lassen sich im Editor schrittweise nur gegenüber einer benachbarten
|
||||
|
||||
@@ -84,7 +84,8 @@ Implemented named-snapshot foundation:
|
||||
stores the complete project state in one SQLite transaction
|
||||
- the versioned payload contains project settings, distribution boards,
|
||||
circuit lists, sections, circuits with device rows, project devices, floors
|
||||
and rooms while excluding global and upgrade-only data
|
||||
and rooms while excluding the global device catalog and other
|
||||
non-project-owned data
|
||||
- snapshot creation/listing does not create a project revision or affect
|
||||
undo/redo eligibility
|
||||
- public Create/List endpoints expose metadata but not the logical payload
|
||||
|
||||
@@ -6,9 +6,10 @@ This is a conceptual model for Codex. It is not a final database schema, but the
|
||||
|
||||
A distribution board contains a circuit list.
|
||||
|
||||
A circuit list contains sections.
|
||||
A circuit list contains circuit groups. `CircuitSection` is the persisted name
|
||||
of that group aggregate.
|
||||
|
||||
A section contains circuits.
|
||||
A circuit group contains circuits of one category.
|
||||
|
||||
A circuit contains zero, one or multiple device rows.
|
||||
|
||||
@@ -60,29 +61,28 @@ User-facing fields:
|
||||
- `section`
|
||||
- `displayName` optional
|
||||
- `circuitTotalPower`
|
||||
- `protectionType`
|
||||
- `protectionRatedCurrent`
|
||||
- `protectionCharacteristic`
|
||||
- `protectionDevice`
|
||||
- `cableType`
|
||||
- `cableCrossSection`
|
||||
- `cableLength`
|
||||
- `rcdAssignment` optional
|
||||
- `terminalDesignation` optional
|
||||
- `voltage` optional
|
||||
- `voltage`, derived from project settings and phase category
|
||||
- `controlRequirement` optional, for example DALI or KNX
|
||||
- `status` optional
|
||||
- `isReserve` optional
|
||||
- `remark` optional
|
||||
|
||||
`protectionDevice` is the circuit-owned one-to-one protection configuration.
|
||||
It contains the device type, rated current and only the type-dependent values
|
||||
such as trip characteristic or residual current. Newly created circuits
|
||||
receive the category default defined in the protection catalog.
|
||||
|
||||
Circuit-level fields only:
|
||||
|
||||
- protection type
|
||||
- protection rated current
|
||||
- protection characteristic
|
||||
- protection device and all of its technical values
|
||||
- cable type
|
||||
- cable cross-section
|
||||
- cable length
|
||||
- RCD assignment
|
||||
- terminal designation
|
||||
- circuit total power
|
||||
|
||||
|
||||
@@ -559,11 +559,11 @@ PostgreSQL should be introduced when shared multi-user operation, background job
|
||||
|
||||
Goal:
|
||||
|
||||
After the legacy consumer path has been removed, provide one accurate entry point for developers, contributors and LLM-assisted work.
|
||||
With the former Consumer path removed, provide one accurate entry point for developers, contributors and LLM-assisted work.
|
||||
|
||||
Timing:
|
||||
|
||||
- perform the final rewrite after legacy cutover so the documentation describes only the supported architecture
|
||||
- keep the post-cleanup documentation limited to the supported architecture
|
||||
- update documentation incrementally during earlier phases, but do not present transitional paths as the long-term design
|
||||
|
||||
README target structure:
|
||||
@@ -618,8 +618,8 @@ Implemented handoff:
|
||||
|
||||
- README is a concise setup and project entry point without prototype status lists
|
||||
- `docs/README.md` separates current, operational, future, specification and archived material
|
||||
- current runtime and module boundaries are documented without unsupported
|
||||
upgrade-only data paths
|
||||
- current runtime and module boundaries are documented without compatibility
|
||||
paths for unsupported pre-release data formats
|
||||
- contributor workflow covers clean databases, safe demo data, migrations, tests and commits
|
||||
- development Compose is clearly separated from the currently unsupported production deployment
|
||||
- `AGENTS.md` points LLM-assisted work to supported code paths and deferred architecture
|
||||
|
||||
@@ -14,11 +14,11 @@ requirements and intended sequencing, not proof of implementation.
|
||||
component model in phased work packages.
|
||||
- [x] Phase A: central protection catalog, validation, defaults and pure grouped
|
||||
BMK rules.
|
||||
- [x] Phase B1: additive relational schema, group backfill, component/protection
|
||||
tables and shared BMK uniqueness.
|
||||
- [x] Phase B2: snapshot/transfer schema upgrade and deterministic compatibility
|
||||
mapping.
|
||||
- [x] Phase C1: versioned new-board command with three groups and fixed header
|
||||
- [x] Phase B1: relational group, component and protection tables with shared
|
||||
BMK uniqueness.
|
||||
- [x] Phase B2: complete snapshot/transfer schema for the supported project
|
||||
state.
|
||||
- [x] Phase C1: new-board command with three groups and fixed header
|
||||
components.
|
||||
- [x] Phase C2a1: persistent insert/delete commands for mutable group
|
||||
protection and auxiliary components.
|
||||
@@ -52,22 +52,22 @@ requirements and intended sequencing, not proof of implementation.
|
||||
|
||||
## First Release Baseline
|
||||
|
||||
Complete this immediately before the first supported release, once the schema
|
||||
and initial feature set are frozen:
|
||||
The pre-release cleanup established the following compatibility boundary:
|
||||
|
||||
- Decide explicitly whether pre-release databases, portable JSON exports,
|
||||
logical snapshots and persisted command histories remain supported.
|
||||
- Create one clean baseline migration that builds the complete release schema
|
||||
on an empty database.
|
||||
- Replace the active development migration chain and Drizzle metadata only if
|
||||
no released installation depends on it.
|
||||
- Remove upgrade-only database, snapshot and command compatibility code only
|
||||
for formats that are explicitly declared unsupported.
|
||||
- Preserve the pre-release migration history in Git history or a release tag.
|
||||
- Verify installation, migrations, application startup and core workflows
|
||||
against a completely empty database.
|
||||
- Mark the resulting compatibility boundary with the first release tag.
|
||||
- Treat every migration published after that release as immutable.
|
||||
- [x] Pre-release databases, portable JSON exports, logical snapshots and
|
||||
persisted command histories are explicitly unsupported.
|
||||
- [x] Migration `0000` builds the complete supported schema on an empty
|
||||
database.
|
||||
- [x] The development migration chain and Drizzle metadata were replaced
|
||||
before any supported release depended on them.
|
||||
- [x] Upgrade-only database, snapshot and command compatibility paths were
|
||||
removed.
|
||||
- [x] Pre-cleanup development history remains available through Git history.
|
||||
- [x] Clean installation, migration, startup and core workflows were verified
|
||||
against an empty database.
|
||||
- [ ] Mark this compatibility boundary with the first supported release tag.
|
||||
- After that release, every published migration is immutable and later schema
|
||||
changes must use new additive migrations.
|
||||
|
||||
## Project History
|
||||
|
||||
@@ -109,9 +109,9 @@ and initial feature set are frozen:
|
||||
device rows with a valid phase are three-phase.
|
||||
- [x] Changing project voltage settings updates all project devices and circuits
|
||||
atomically in the same persistent Undo/Redo step.
|
||||
- [x] Database migration `0019` and snapshot schema version `5` normalize older
|
||||
stored values. Version-four and older imports remain supported and are
|
||||
normalized while being upgraded.
|
||||
- [x] Baseline migration `0000` and project-state schema version `1` store only
|
||||
the canonical derived values. Pre-release imports are intentionally
|
||||
unsupported.
|
||||
|
||||
## Circuit List Power Summary
|
||||
|
||||
|
||||
@@ -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