152 lines
3.2 KiB
Markdown
152 lines
3.2 KiB
Markdown
# 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.
|