leistungsbilanz-ts/docs/spec/07-implementation-phases-todo.md

# Implementation Phases and Todo List

## Important Strategy

There is already an existing codebase.

Do not blindly continue with the current implementation if it conflicts with this specification.

Do not blindly delete the current codebase either.

First audit the existing code against this specification, then refactor or replace the parts that conflict with the target model.

The most important architectural correction is:

A circuit is not the same thing as one device row.

A circuit contains zero, one or multiple device rows.

## Phase 0: Audit Existing Codebase

Goal:

Determine which parts of the current codebase can be kept.

Tasks:

- identify current data model
- identify whether rows are modeled as circuits, devices or mixed entities
- identify hardcoded section logic
- identify current drag-and-drop implementation
- identify current table/editing implementation
- identify current project device concept
- identify persistence layer and migrations
- list conflicts with the new specification
- propose refactor plan before changing code

Deliverable:

- short audit report
- keep/refactor/delete recommendation per major module

## Phase 1: Core Data Model and Basic Table

Goal:

Implement the stable foundation.

Tasks:

- define sections
- define circuits
- define circuit device rows
- define project devices
- allow manual rows
- allow empty/reserve circuits
- calculate row total power
- calculate circuit total power
- display sections as separator rows
- display single-device circuits as compact rows
- display multi-device circuits with summary row and indented device rows
- implement manual equipment identifier editing
- implement next identifier generation as highest number + 1
- prevent automatic renumbering

Acceptance criteria:

- a section can contain multiple circuits
- a circuit can contain zero, one or multiple device rows
- deleting a device does not automatically delete the circuit unless the user chooses so
- circuit total power is calculated from all device rows
- equipment identifiers are stable unless manually changed or explicitly renumbered

## Phase 2: Spreadsheet-Like Editing

Goal:

Make the table efficient to edit.

Tasks:

- static text cells by default
- inline editing on double click / Enter / typing / F2
- Enter, Tab, Shift+Tab, Escape behavior
- keyboard navigation
- Ctrl + Plus row insertion
- Ctrl + Shift + Plus support
- Delete behavior
- validation warnings for duplicate identifiers

Acceptance criteria:

- common values can be edited without opening full forms
- keyboard workflow is usable for repetitive entry
- accidental edits can be cancelled

## Phase 3: Project Device Sidebar

Goal:

Allow dragging project devices into the circuit list.

Tasks:

- implement project device list
- search project devices
- filter project devices
- show basic technical values
- drag project device into valid section
- drop onto free placeholder to create a circuit
- drop onto existing circuit to add device
- create linked device rows
- prefill display name but keep it local after insertion

Acceptance criteria:

- project devices can create new circuits
- project devices can be added to existing circuits
- invalid sections reject drops or require confirmation
- linked rows keep the source relationship

## Phase 4: Drag-and-Drop Restructuring

Goal:

Allow restructuring circuits and device assignments.

Tasks:

- drag from circuit handle moves whole circuit
- drag from device area moves device row
- move device between circuits
- move device to free placeholder to create new circuit
- move circuit inside section
- visual drop indicator
- valid/invalid drop zone feedback
- multi-row selection with Ctrl + click and Shift + click
- multi-row drag preserving internal order

Acceptance criteria:

- circuits can be reordered without renumbering
- devices can be reassigned to other circuits
- circuit totals recalculate after moves
- multi-row movement does not break circuit/device grouping

## Phase 5: Filtering, Sorting and Columns

Goal:

Add Excel-like table management.

Tasks:

- filter menu per column header
- sort ascending/descending per column
- sorting circuits as complete blocks
- preserve device grouping when sorting
- column visibility configuration
- column reorder by drag and drop
- reset default column layout

Acceptance criteria:

- user can filter by room, cost group, category, phase type, etc.
- user can sort within sections
- sorting does not split circuits
- sorting does not renumber
- user can renumber explicitly after sorting

## Phase 6: Undo / Redo

Goal:

Make structural editing safe.

Tasks:

- implement undo/redo stack
- support insert circuit
- support insert device
- support delete circuit
- support delete device
- support move circuit
- support move device
- support multi-row move
- support renumber section
- support cell edits
- support sync operations
- support disconnect linked project device

Acceptance criteria:

- destructive changes can be reverted
- renumbering can be undone
- drag-and-drop restructuring can be undone

Note:

Undo/redo should be considered from the beginning. Implement technically as early as possible if the architecture allows it.

## Phase 7: Linked Device Synchronization

Goal:

Control updates from project devices to circuit list rows.

Tasks:

- track linked project devices
- track overridden fields
- show affected rows when a project device changes
- implement sync dialog
- allow field-level selection
- apply to one / selected / all linked rows
- allow disconnecting selected rows

Acceptance criteria:

- displayName is not synchronized by default
- user sees affected distribution boards and circuits
- user controls which fields are overwritten
- local values are not silently lost

## Phase 8: Future Sizing Preparation

Goal:

Prepare for future electrical sizing logic.

Tasks:

- keep circuit-level protection and cable fields
- keep voltage and cosPhi
- support future control requirement
- structure sizing rules separately from UI
- add warning/status concept

Acceptance criteria:

- the codebase can later add rule-based sizing without redesigning circuits/devices
- users can manually override calculated suggestions

## Phase 9: Development Environment and Docker

Goal:

Make short development sessions quick to start and stop.

Tasks:

- add a Docker-based local development setup
- start frontend, API and SQLite persistence with one command
- keep the database in an explicit persistent volume
- run or document pending database migrations during startup
- add concise start, stop and reset instructions
- retain a non-Docker development path for direct debugging

Acceptance criteria:

- a new development session starts with one documented command
- stopping and restarting does not lose the local database
- frontend and API health can be checked without manual port setup
- the development workflow works consistently across short sessions

Note:

This phase may be moved earlier if repeated local startup overhead begins to slow down feature development.

## Phase 10: Deferred Circuit Editor UX Polish

Goal:

Improve everyday usability after the core circuit workflows are stable.

Tasks:

- keep column headers visible while scrolling down long circuit lists
- keep undo/redo controls reachable without scrolling to the top
- preserve the user's viewport when toolbar undo/redo is applied instead of jumping to the changed row
- reduce the default table width and contain horizontal scrolling within the editor
- review sensible default columns and responsive behavior for typical browser widths
- redesign column filtering with clearer controls, active-filter indicators and an easy reset action

Implemented layout foundation:

- table scrolling is contained inside the editor so sticky headers remain visible
- the toolbar remains reachable while the page scrolls
- programmatic grid focus preserves the viewport during undo/redo reloads
- wide tables no longer expand the surrounding browser layout
- active sorts and filters are summarized above the grid and can be removed individually or reset together
- column filter buttons show their selected-value count
- filter menus provide value search, select-all/select-none controls and explicit cancel/apply actions
- filter values and visible columns use full-width selectable rows instead of permanent checkbox controls
- column settings use the same searchable panel pattern as column filters
- column headings are visually plain text while remaining keyboard-accessible sort controls

Acceptance criteria:

- users retain column context anywhere in a long list
- undo/redo does not disrupt the current reading position
- the editor remains usable without overflowing the browser layout
- active filters are easy to understand, change and clear

## Phase 11: Persistence and Transaction Foundation

Status: Complete.

Goal:

Prepare the current SQLite implementation for persistent history and a later PostgreSQL adapter without changing user-facing behavior.

Tasks:

- add real SQLite integration tests for transaction commit and rollback
- introduce an injectable transaction / unit-of-work boundary
- remove direct database-client access from domain services
- treat synchronous SQLite transactions as an adapter detail
- remove dead persistence methods after coverage exists
- verify database backup and restore independently from project history

Acceptance criteria:

- critical multi-write commands roll back completely in a real database test
- domain command behavior is not coupled to `better-sqlite3`
- adding a PostgreSQL persistence adapter does not require rewriting editor domain rules

Implemented foundation:

- database contexts can be created independently from the production singleton
- SQLite foreign-key enforcement is enabled explicitly for every context
- the read-only distribution-board repository receives its database dependency explicitly
- distribution-board setup uses its persistent command repository with real
  in-memory SQLite commit and rollback coverage using production migrations
- database backups use SQLite's online backup API and include committed WAL data
- every backup is opened independently and checked for integrity and foreign-key violations
- an integration test restores the backup into a separate database and verifies its snapshot contents
- circuit-device-row creation/deletion and reserve-state changes use an explicitly injected transaction store
- a new circuit and all of its initial device rows use the same transaction store
- device-row moves, reserve-state updates and optional target creation share one transaction
- project-device synchronization, disconnect and reconnect use a separate injected transaction store
- section renumbering and circuit reordering use persistent command stores
- circuit-device-row transaction tests cover both successful commits and forced SQLite rollbacks
- project-device row synchronization has real multi-row SQLite commit and rollback coverage
- BMK swaps and section reorder have real SQLite commit and rollback coverage
- the former Consumer migration service, mappings and reports were removed with
  the pre-release database cutover
- circuit and device-row persistence value mapping is separated from the general repositories
- obsolete direct Circuit, CircuitDeviceRow, CircuitList, DistributionBoard and
  Project repository writes are removed; integration fixtures live under
  `tests/support` instead of production repositories
- all supported runtime project-command stores, including complete snapshot
  restore, share one tested transaction wrapper for domain mutation, revision
  append and history transition; its applied-forward variant retains derived
  CircuitDeviceRow override metadata
- low-level revision append persistence is tested directly; the unused
  standalone runtime revision repository and store interface are removed
- runtime project-device synchronization and circuit-numbering services depend
  on narrow domain readers; server composition injects the SQLite repositories
- all general application repositories require an explicit database context;
  server composition owns their runtime instances and controllers contain no
  direct global SQLite access
- TypeScript maintenance and upgrade scripts have a dedicated no-emit
  typecheck, including all referenced application modules
- the former Consumer UI, API, tables and upgrade tooling are removed
- migration `0000` is the clean baseline for new installations; pre-baseline
  development databases are intentionally unsupported
- project devices no longer persist duplicate legacy power, phase, cosPhi or remark fields

## Phase 12: Project Revisions and Persistent Undo / Redo

Goal:

Persist project-wide change history and restore points across reloads and application restarts.

Tasks:

- [x] add project-scoped monotonic revision storage
- [x] add immutable append-only server-side change-set storage with versioned
  forward/inverse payloads
- [x] add optimistic checks when appending a revision
- [x] route supported domain writes and history records through one shared transaction
- [x] define concrete serializable domain command descriptions and executors
  outside React
- [x] persist undo/redo eligibility on the server
- [x] expose public command, undo and redo endpoints for the first supported
  update command types
- [x] expose a cursor-paginated, read-only revision metadata timeline without
  command payloads
- [x] add explicitly named logical project snapshots with schema-versioned
  payloads and integrity checksums
- [x] add periodic logical project snapshots with a bounded retention policy
- [x] restore a historical snapshot as a new auditable revision with
  persistent undo/redo
- [x] expose named snapshots, confirmed restore and the paginated revision
  timeline on the project page
- [x] expose persistent project-wide undo/redo controls on the project page
  and remove its session-local ProjectDevice synchronization undo state
- keep database backups separate from logical history

Implemented foundation:

- projects start at revision zero and advance monotonically
- each revision has one separately stored logical change set
- forward and inverse changes use complete, versioned JSON command envelopes
- invalid or lossy command payloads are rejected before persistence
- an internal typed `circuit.update` command generates its inverse from the
  persisted pre-command state
- circuit update, inverse command, change set and revision share one SQLite
  transaction with stale-command and late-failure rollback coverage
- an internal typed `circuit-device-row.update` command uses the same boundary,
  records derived ProjectDevice override metadata and rejects cross-project
  rows, device links and rooms
- relational project-wide undo/redo stacks persist eligible original change
  sets, enforce LIFO order and clear redo on a new user command
- stack transitions are part of the domain/revision transaction and have
  late-failure rollback coverage
- a read-only project history endpoint exposes revision, stack depths and top
  change-set ids
- a separate read-only timeline endpoint exposes immutable revision metadata
  in descending, cursor-paginated pages without forward/inverse payloads
- named snapshot Create/List endpoints persist complete project-scoped runtime
  state with the source revision and SHA-256 without changing revision or
  undo/redo stacks
- the central revision boundary captures an `automatic` snapshot after every
  25 new revisions and retains the newest 12 automatic snapshots per project
  without deleting named snapshots or immutable revisions
- the project page lists, creates and explicitly restores named snapshots and
  displays paginated revision metadata without exposing command payloads
- the version-card header reads persisted undo/redo eligibility and executes
  optimistic project-wide undo/redo even while its timeline body is collapsed
- a central application dispatcher reconstructs persisted commands and exposes
  optimistic command, undo and redo endpoints for Circuit and CircuitDeviceRow
  field updates
- the circuit tree exposes `currentRevision`; existing Circuit and
  CircuitDeviceRow cell edits use those optimistic commands and project-wide
  undo/redo instead of direct field-update PATCH routes
- typed CircuitDeviceRow insert/delete commands preserve complete row snapshots
  and stable ids; row mutation, circuit reserve state, revision and history
  stack transition commit or roll back together
- typed Circuit insert/delete commands treat the circuit and all device rows as
  one block, preserve every stable id and never renumber neighbouring circuits
- standalone Circuit/CircuitDeviceRow insert/delete editor paths use those
  commands with stable client-generated UUIDs and project-wide undo/redo; the
  obsolete direct structure POST and CircuitDeviceRow DELETE routes are removed
- typed CircuitDeviceRow move commands persist exact old/new circuit and sort
  positions for single or multi-row moves between existing circuits and derive
  affected reserve states in the same transaction
- placeholder-target moves persist one complete generated circuit identity and
  all row positions atomically; undo restores every source and removes only an
  unchanged generated circuit, without renumbering
- complete section reorders persist every expected and target circuit
  `sortOrder`; undo/redo changes neither equipment identifiers nor device rows
- explicit section renumber commands persist every expected and target
  equipment identifier, apply swaps collision-safely and restore exact prior
  identifiers without changing sort positions or device rows
- ProjectDevice row synchronization, disconnect and reconnect persist complete
  expected/target sync snapshots in one atomic multi-row command; undo restores
  local values, links and override metadata without silent overwrites
- canonical ProjectDevice field updates persist independently with exact
  inverses and never overwrite linked CircuitDeviceRow values implicitly
- ProjectDevice insert/delete commands preserve stable device ids and restore
  previously linked rows only from complete unchanged disconnected snapshots
- ProjectDevice create, update, delete and global-to-project copy endpoints use
  these commands, require `expectedRevision` and return the new history state
- ProjectDevice synchronization and disconnect endpoints also require
  `expectedRevision`; their UI undo uses project-wide persistent history and
  the obsolete direct restore/reconnect write paths are removed
- project settings use `project.update-settings`; metadata, public-building
  classification, voltage values, inverse, revision and history transition
  commit atomically and the former direct settings write is removed
- distribution-board setup uses `distribution-board.insert` with a complete
  stable board/list/default-section snapshot; Undo removes only an unchanged
  empty setup and the former direct controller write is removed
- floor and room setup use `project-floor.insert` and `project-room.insert`
  with stable ids; their inverses refuse assigned or referenced records and the
  former direct repository create methods are removed
- revision metadata, change-set payloads and the project counter are committed
  in one SQLite transaction
- a stale expected revision produces no history writes
- integration coverage verifies sequential revisions, stale-command rejection
  and rollback after a forced late persistence failure

ProjectDevice CRUD, synchronization and disconnect on the project page and
Circuit/CircuitDeviceRow field/insert/delete actions, device-row moves and
circuit reorders in the circuit-list editor are connected to this history
boundary. Applying sorted order across multiple sections is one atomic command.
Explicit renumbering is connected to the same persistent boundary. The
editor reads the persistent undo/redo stack depths on initial load and after
every tree reload. Tree and history revisions are reconciled before the state
is exposed, so the toolbar remains usable after a page refresh.

Acceptance criteria:

- undo/redo remains available after a page reload
- every logical command and inverse is atomic and auditable
- restoring an older state does not delete intervening history
- concurrent stale commands cannot silently overwrite newer project state

## 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

Status: abgeschlossen am 30.09.2026 mit R10. Siehe
[R10-Abnahme](revit-excel-r10-validation.md).

Status: R0 ist mit Korrekturen freigegeben; R1 stellt die Dokumentation auf
Linear-XLSX und Worksharing-ID um. Die frühere CSV-Planung 14.0–14.6 ist
abgelöst und wird nicht fortgeschrieben.

Verbindliche Quellen:

- [Revit-Integration über Linear-Excel](revit-excel-integration-requirements.md)
- [R0–R10-Plan](revit-excel-phase-14-plan.md)
- [R0-Bestandsaudit](revit-excel-r0-audit.md)

Die Umsetzung erfolgt ausschließlich in den Paketen R0–R10. R2 endet mit
einer aus der realen Musterdatei erzeugten Rückgabedatei. Der Nutzer muss sie
erfolgreich in Linear importieren, bevor R3 beginnt. Bei einem Fehlschlag wird
zuvor eine direkte OOXML-Änderung des Originalworkbooks als Alternative
vorgelegt.

Kernabnahme der Phase:

- Worksharing-ID ist der exakte, case-sensitive externe Schlüssel;
- XLSX-Kopfkommentare, Struktur, Formate und unbekannte Spalten bleiben beim
  Rückexport erhalten;
- Import erzeugt keine Rows und überschreibt keine lokale Planung still;
- Zuordnung, Löschung, Folgeimport und Undo/Redo sind atomar und nach Neustart
  reproduzierbar;
- Undo/Redo liest keine Excel-Datei;
- nur der letzte Importbatch enthält Workbook und Matrix vollständig;
- mehrere Tausend Objekte bleiben über eine clientseitig gefilterte,
  virtualisierte Liste bedienbar.

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 15: Documentation and Collaboration Handoff

Goal:

With the former Consumer path removed, provide one accurate entry point for developers, contributors and LLM-assisted work.

Timing:

- 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:

- short project purpose and current maturity/status
- supported domain workflow at a high level
- technology stack
- prerequisites
- recommended Docker development quick start
- direct local development start
- test, type-check and build commands
- database persistence, migration, backup and restore basics
- production deployment/install instructions once a production setup exists
- concise documentation map
- contribution entry point

README content to remove or relocate:

- historical requirement checklists
- file-by-file implementation status from early prototypes
- obsolete legacy consumer architecture
- long domain specifications already maintained in `docs/`
- broken links and claims that are not verified by the current code

Documentation tasks:

- add a `docs/README.md` index with current, future and archived documents clearly separated
- keep current architecture, domain invariants, API behavior and interaction behavior synchronized with code
- archive superseded initial requirements under `docs/archive/` when they are still useful for traceability
- remove obsolete documentation that has no remaining historical or operational value
- update `AGENTS.md` with current entry points, supported/deprecated paths and forward architecture constraints
- add a concise contributor workflow for branches, migrations, tests and commits
- document how a colleague creates an empty local database and optionally loads safe sample data
- avoid duplicating the same architecture facts across README, `AGENTS.md` and detailed docs; link to one source of truth

Deployment documentation requirements:

- distinguish development Compose from production deployment
- do not label the hot-reload development stack as a production setup
- document required environment variables, ports, health checks, persistent storage and migration behavior
- verify backup and restore procedures

Acceptance criteria:

- a colleague can clone the repository and start a clean development environment using only the README
- a contributor can identify the supported architecture and relevant code entry points without reading historical specs
- an LLM receives domain invariants, current module boundaries and deferred architecture direction without relying on stale legacy files
- every README command and internal documentation link is verified
- production instructions describe a real tested deployment path or clearly state that none is supported yet

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 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
- obsolete frontend placeholder documents were removed and early Codex prompts were archived