diff --git a/docs/circuit-list-editor-api.md b/docs/circuit-list-editor-api.md index 8f225a0..bd975d1 100644 --- a/docs/circuit-list-editor-api.md +++ b/docs/circuit-list-editor-api.md @@ -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 diff --git a/docs/current-architecture.md b/docs/current-architecture.md index dc8a3f8..42f4adc 100644 --- a/docs/current-architecture.md +++ b/docs/current-architecture.md @@ -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 diff --git a/docs/project-history-and-external-model-architecture.md b/docs/project-history-and-external-model-architecture.md index ae03868..a4d4cbd 100644 --- a/docs/project-history-and-external-model-architecture.md +++ b/docs/project-history-and-external-model-architecture.md @@ -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 diff --git a/docs/spec/03-data-model-concept.md b/docs/spec/03-data-model-concept.md index 545c450..dec30f6 100644 --- a/docs/spec/03-data-model-concept.md +++ b/docs/spec/03-data-model-concept.md @@ -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 diff --git a/docs/spec/07-implementation-phases-todo.md b/docs/spec/07-implementation-phases-todo.md index 16124c0..3683534 100644 --- a/docs/spec/07-implementation-phases-todo.md +++ b/docs/spec/07-implementation-phases-todo.md @@ -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 diff --git a/docs/spec/08-current-product-backlog.md b/docs/spec/08-current-product-backlog.md index 69046fb..4a81bb5 100644 --- a/docs/spec/08-current-product-backlog.md +++ b/docs/spec/08-current-product-backlog.md @@ -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 diff --git a/docs/spec/09-distribution-board-components-and-protection-groups.md b/docs/spec/09-distribution-board-components-and-protection-groups.md index c3df4f2..a8fe03f 100644 --- a/docs/spec/09-distribution-board-components-and-protection-groups.md +++ b/docs/spec/09-distribution-board-components-and-protection-groups.md @@ -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