jappel/leistungsbilanz-ts
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b1a11397b33dd3ef0e5e17239550aa7922e5c936
leistungsbilanz-ts/docs/circuit-list-editor-api.md
T

13 KiB
Raw Blame History

Circuit List Editor API

Scope

The circuit-first editor uses tree, circuit, row and project-device endpoints. All paths below are mounted below /api. There is no Consumer application API.

Project responses from GET /projects, GET /projects/:projectId and the circuit-tree endpoint include currentRevision. Versioned project commands use this value for optimistic concurrency checks.

Project Commands and History

  • GET /projects/:projectId/history
    • returns currentRevision, undoDepth, redoDepth and the current top change-set id for both persistent stacks
  • GET /projects/:projectId/history/revisions
    • returns revision metadata in descending revisionNumber order
    • optional query: limit (default 25, maximum 100) and exclusive beforeRevision
    • returns projectId, currentRevision, revisions and nextBeforeRevision; use the latter as the next page's beforeRevision
    • each revision contains ids, number, timestamp, actor, source, description, command type and payload schema version
    • stored forward/inverse command payloads are intentionally not exposed
  • POST /projects/:projectId/commands
    • executes a supported versioned command as a new user revision
    • body: { "expectedRevision": 0, "command": { ... } }
  • POST /projects/:projectId/history/undo
  • POST /projects/:projectId/history/redo
    • body: { "expectedRevision": 1 }
    • executes the eligible inverse or forward command as a new auditable revision
  • GET /projects/:projectId/snapshots
    • lists named and automatic logical snapshot metadata, including kind, without returning payload JSON
  • POST /projects/:projectId/snapshots
    • body: { "expectedRevision": 12, "name": "Vor Ausschreibung", "description": "Optional" }
    • atomically captures the complete project-scoped runtime state at the expected revision
    • returns 201 with source revision, schema version, SHA-256 and creation metadata
    • snapshot creation does not increment the project revision or alter undo/redo stacks
    • duplicate names and stale revisions return 409
    • the central revision boundary additionally creates automatic snapshots after 25 further revisions and retains the newest 12 per project; named snapshots are never removed by this policy
  • POST /projects/:projectId/snapshots/:snapshotId/restore
    • body: { "expectedRevision": 13 }
    • verifies the stored payload checksum and atomically restores the complete supported project state as revision 14 with source restore
    • stores the complete pre-restore state as the inverse command, so project Undo/Redo can revert or repeat the restore after a restart
    • stale revisions or state checks return 409; unknown snapshots return 404
    • clients cannot submit arbitrary project.restore-state payloads through the generic command endpoint

The public dispatcher currently supports circuit.update, circuit.insert, circuit.delete, circuit-device-row.update, circuit-device-row.insert, circuit-device-row.delete, circuit-device-row.move, circuit-device-row.move-with-new-circuit, circuit.reorder-section, circuit.reorder-sections, circuit.renumber-section and project-device.update, project-device.insert, project-device.delete and project-device.sync-rows as well as project.update-settings, all with schema version 1. Other command types 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 target sort order. This makes deletion and moves undoable without generating replacement identities or renumbering circuits. Existing Circuit and CircuitDeviceRow cell edits, standalone insert/delete actions, device-row moves, reorders and explicit renumbering in the editor consume these endpoints.

circuit-device-row.move targets existing circuits in the same circuit list. circuit-device-row.move-with-new-circuit atomically creates exactly one explicitly identified empty target circuit and moves one or multiple existing rows into it. Its inverse restores every row to its exact prior position and deletes the generated circuit only if its fields and complete row set still match the recorded state.

circuit.reorder-section requires one assignment for every circuit currently in the section. Each assignment records the expected and target sortOrder. The command and its inverse change no circuit field other than sortOrder; equipment identifiers and complete device-row blocks remain unchanged.

circuit.reorder-sections contains one complete assignment block per affected section. All blocks are validated before any write and commit or roll back together as one revision and one undo step. The editor uses it when applying a sorted view that changes multiple sections.

circuit.renumber-section is an explicit operation requiring one assignment for every circuit in the section. Assignments contain expected and target equipment identifiers. The store rejects stale values, duplicate targets and targets occupied by other sections, then applies swaps through collision-safe temporary identifiers. Undo restores the exact prior identifiers; sort positions and device rows remain unchanged.

project-device.sync-rows represents synchronize, disconnect and reconnect operations. Every selected row carries complete expected and target snapshots of all ProjectDevice-sync fields, the link and overriddenFields. All rows, the inverse command, revision and history-stack transition commit or roll back together. Disconnect/reconnect may only change the link; stale row snapshots and cross-project devices or rows are rejected.

project-device.update changes one or multiple canonical ProjectDevice fields and derives its inverse from the persisted device. It validates project ownership and never writes linked CircuitDeviceRow values; synchronization remains a separate explicit command.

project-device.insert stores the complete canonical device with a stable id. User inserts cannot attach existing rows. project-device.delete captures the complete device and every currently linked row before deletion. Its inverse recreates the same device and reconnects only rows whose complete disconnected snapshot still matches; device, links, revision and history transition are atomic.

Project Device CRUD

  • GET /project-devices/projects/:projectId
    • lists the project's reusable devices
  • POST /project-devices/projects/:projectId
  • PUT /project-devices/projects/:projectId/:projectDeviceId
    • request: all canonical device fields plus expectedRevision
    • response: { "projectDevice": { ... }, "revision": { ... }, "history": { ... } }
  • DELETE /project-devices/projects/:projectId/:projectDeviceId
    • request: { "expectedRevision": 12 }
    • response: the project command result with the updated history state
  • POST /project-devices/projects/:projectId/import-global/:globalDeviceId
    • request: { "expectedRevision": 12 }
    • creates an independent project device with a stable UUID
    • response shape matches ProjectDevice create/update

These write endpoints execute the typed project-device.update, project-device.insert and project-device.delete commands. A stale revision returns 409 PROJECT_REVISION_CONFLICT. Updating a project device still never synchronizes linked circuit rows implicitly.

Project Settings

  • PUT /projects/:projectId
    • request: { "expectedRevision": 12, "singlePhaseVoltageV": 230, "threePhaseVoltageV": 400, "enabledDistributionBoardSupplyTypes": ["AV", "MSR", "SiBe"], ...projectMetadata }
    • executes project.update-settings as one atomic revision
    • response: { "project": { ... }, "revision": { ... }, "history": { ... } }
    • persistent Undo/Redo restores metadata, voltage values and the enabled distribution-board supply types together
    • at least one of AV, SV, EV, USV, MSR, SiBe must be enabled; a supply type currently used by a distribution board cannot be disabled
    • unchanged values are rejected without creating a revision; a stale revision returns 409 PROJECT_REVISION_CONFLICT

Example:

{
  "expectedRevision": 0,
  "description": "Rename circuit",
  "command": {
    "schemaVersion": 1,
    "type": "circuit.update",
    "payload": {
      "circuitId": "cir_1",
      "changes": [
        { "field": "displayName", "value": "Sockets East" }
      ]
    }
  }
}

A stale expectedRevision returns HTTP 409 with PROJECT_REVISION_CONFLICT. Undo or redo without an eligible stack entry returns HTTP 409 with PROJECT_HISTORY_OPERATION_UNAVAILABLE.

Circuit-First Endpoints

Distribution Board Setup

  • POST /projects/:projectId/distribution-boards
    • body: { "name": "UV-02", "floorId": "floor_1", "supplyType": "SV", "expectedRevision": 12 }
    • floorId may be null; a non-null floor must belong to the project
    • supplyType is one of AV, SV, EV, USV, MSR or SiBe and must be enabled in the project settings
    • executes distribution-board.insert with stable ids for the distribution board, its circuit list and all four default circuit sections
    • response: { "distributionBoard": { ... }, "revision": { ... }, "history": { ... } }
    • persistent Undo removes only the unchanged and still-empty generated structure; Redo restores the same ids
    • stale revisions return 409 PROJECT_REVISION_CONFLICT
  • PUT /projects/:projectId/distribution-boards/:distributionBoardId
    • body: { "floorId": null, "supplyType": "AV", "expectedRevision": 13 }
    • executes distribution-board.update; floor and supply type are restored together by persistent Undo/Redo

Project Floors and Rooms

  • POST /projects/:projectId/floors
    • body: { "name": "EG", "expectedRevision": 13 }
    • executes project-floor.insert with a stable floor id
    • response: { "floor": { ... }, "revision": { ... }, "history": { ... } }
  • POST /projects/:projectId/rooms
    • body: { "floorId": "floor_1", "roomNumber": "001", "roomName": "Technik", "expectedRevision": 14 }
    • executes project-room.insert with a stable room id; floorId is optional and must belong to the project when present
    • response: { "room": { ... }, "revision": { ... }, "history": { ... } }
  • Persistent Undo removes only unchanged, unreferenced records. A floor with assigned rooms or distribution boards and a room referenced by device rows or retained upgrade data are rejected instead of silently clearing foreign keys.
  • Stale revisions return 409 PROJECT_REVISION_CONFLICT.

Tree Endpoint

  • GET /projects/:projectId/circuit-lists/:circuitListId/tree
  • Purpose: returns section/circuit/device-row tree with calculated row and circuit totals.

Response sketch:

{
  "circuitListId": "cl_1",
  "currentRevision": 12,
  "sections": [
    {
      "id": "sec_1",
      "key": "lighting",
      "prefix": "-1F",
      "circuits": [
        {
          "id": "cir_1",
          "equipmentIdentifier": "-1F1",
          "circuitTotalPower": 4.2,
          "deviceRows": [
            {
              "id": "row_1",
              "displayName": "Office lights",
              "rowTotalPower": 1.8
            }
          ]
        }
      ]
    }
  ]
}

Circuit Structure

  • GET /circuit-sections/:sectionId/next-identifier
    • preview next identifier for section (prefix + maxSuffix + 1)

Circuit and device-row field updates, standalone insertions/deletions, single or bulk device-row moves, circuit reorders and explicit renumbering are available only as the corresponding versioned commands through POST /projects/:projectId/commands. There are no direct field-update PATCH, structure POST, move, reorder, renumber, identifier-restore, Circuit DELETE or CircuitDeviceRow DELETE routes.

Removed Legacy Endpoints

The former /consumers read/write endpoints were removed after every retained consumer had a verified Circuit-First migration mapping. Database upgrade tooling reads retained legacy rows directly; application features must use the Circuit-First endpoints above.

Linked Project Device Review

  • GET /project-devices/projects/:projectId/:projectDeviceId/links
    • returns all linked circuit device rows with distribution-board/circuit context and field differences
  • POST /project-devices/projects/:projectId/:projectDeviceId/synchronize
    • applies only explicitly selected fields to explicitly selected linked rows
    • request: selected rowIds, selected fields and expectedRevision
    • response: updated preview, revision and project history state
  • POST /project-devices/projects/:projectId/:projectDeviceId/disconnect
    • disconnects explicitly selected rows without changing their local values
    • request: selected rowIds and expectedRevision
    • response: updated preview, revision and project history state

Both writes execute project-device.sync-rows. Undo uses the project-wide POST /projects/:projectId/history/undo endpoint; reconnect is the validated inverse command. The former direct restore/reconnect endpoints are removed.

displayName is included in the comparison but is not selected by default in the UI. Updating a project device never triggers synchronization implicitly.

Reference in New Issue View Git Blame Copy Permalink