# 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` and `GET /projects/:projectId` include
`currentRevision`. It currently exposes the persisted revision foundation only;
no public undo or redo command exists yet.

### Project History State

- `GET /projects/:projectId/history`
  - returns `currentRevision`, `undoDepth`, `redoDepth` and the current top
    change-set id for both persistent stacks
  - is read-only; the editor does not consume it yet

## Circuit-First Endpoints

### Distribution Board Setup

- `POST /projects/:projectId/distribution-boards`
  - atomically creates the distribution board, its circuit list and all default circuit sections

### 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
- `POST /projects/:projectId/circuit-lists/:circuitListId/circuits-with-device-rows`
  - atomically create one circuit and one or more initial device rows
- `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" }
  ]
}
```

## 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
- `POST /project-devices/projects/:projectId/:projectDeviceId/restore`
  - restores the captured pre-sync values for session-local undo
- `POST /project-devices/projects/:projectId/:projectDeviceId/disconnect`
  - disconnects explicitly selected rows without changing their local values
- `POST /project-devices/projects/:projectId/:projectDeviceId/reconnect`
  - restores a disconnected link if the row has not been linked elsewhere meanwhile

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