leistungsbilanz-ts/docs/circuit-list-editor-api.md

Circuit List Editor API

Scope

The circuit-first editor uses tree + circuit + row endpoints. Legacy consumer endpoints still exist for compatibility and migration, but should not be extended for new circuit-list behavior.

Circuit-First Endpoints

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",
  "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 CRUD

• POST /projects/:projectId/circuit-lists/:circuitListId/circuits
  • create circuit in list/section
• PATCH /circuits/:circuitId
  • update circuit-level fields (BMK, protection, cable, reserve flag, etc.)
• DELETE /circuits/:circuitId
  • delete circuit (and related rows via DB relations)
• GET /circuit-sections/:sectionId/next-identifier
  • preview next identifier for section (prefix + maxSuffix + 1)

Request sketch (POST .../circuits):

{
  "sectionId": "sec_1",
  "equipmentIdentifier": "-2F14",
  "displayName": "Sockets East",
  "sortOrder": 140
}

Device Row CRUD

• POST /circuits/:circuitId/device-rows
  • create row inside a circuit
• PATCH /circuit-device-rows/:rowId
  • update row values
• DELETE /circuit-device-rows/:rowId
  • delete row

Move Device Row

• PATCH /circuit-device-rows/:rowId/move
• Purpose: move one row to existing circuit or to newly created circuit in target section.

Request sketch:

{
  "targetCircuitId": "cir_target"
}

or

{
  "targetSectionId": "sec_target",
  "createNewCircuit": true
}

Bulk Move Device Rows

• PATCH /circuit-device-rows/move-bulk
• Purpose: move multiple rows in one command flow.

Request sketch:

{
  "rowIds": ["row_1", "row_2"],
  "targetCircuitId": "cir_target"
}

Reorder Circuits

• PATCH /circuit-sections/:sectionId/circuits/reorder
• Purpose: persist explicit circuit order within one section.

Request sketch:

{
  "orderedCircuitIds": ["cir_2", "cir_1", "cir_3"]
}

Renumber Section

• POST /circuit-sections/:sectionId/renumber
• Purpose: explicit renumbering by section prefix; never implicit on move/sort.

Safe Equipment Identifier Update

• PATCH /circuit-sections/:sectionId/equipment-identifiers
• Purpose: apply explicit per-circuit identifiers safely even with unique constraints.

Request sketch:

{
  "identifiers": [
    { "circuitId": "cir_1", "equipmentIdentifier": "-2F1" },
    { "circuitId": "cir_2", "equipmentIdentifier": "-2F2" }
  ]
}

Legacy Endpoints (Temporary)

• GET /consumers/projects/:projectId
• POST /consumers
• PUT /consumers/:consumerId
• DELETE /consumers/:consumerId

These remain for migration/legacy views. New circuit-list interactions must use circuit-first endpoints above.