# 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.