Documentation

2026-05-07 22:55:15 +02:00
parent b1e19a88d5
commit 7580ad0ade
11 changed files with 584 additions and 1 deletions
@@ -0,0 +1,151 @@
+# 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:
+
+```json
+{
+  "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`):
+
+```json
+{
+  "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:
+
+```json
+{
+  "targetCircuitId": "cir_target"
+}
+```
+
+or
+
+```json
+{
+  "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:
+
+```json
+{
+  "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:
+
+```json
+{
+  "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:
+
+```json
+{
+  "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.