airqo-platform / airqo-platform/AirQo-frontend

Add "Decommission Device" action to Vertex

Abierto
#3,924 0 comentarios 0 reacciones 1 asignado Reclamado por @BwanikaRobert Ver en GitHub
Lenguaje dominante
TypeScript
Estrellas
23
Forks
48
Merge medio
15 h 24 min
PR fusionados (30 d)
57

Descripción

# Add "Decommission Device" action to Vertex

## Summary

device-registry has a new endpoint that lets a device be permanently retired on the platform **without touching its upstream data provider (e.g. ThingSpeak)**. It's the safe alternative to the existing hard-delete flow, which removes a device from both the platform and ThingSpeak and is intentionally not exposed in the UI today — that's difficult to recover from for a device already deployed in the field.

Typical trigger: a hardware engineer finds a device's ThingSpeak channel was deleted and needs to mark it retired in our system, with zero risk of the action touching ThingSpeak.

Decommissioning preserves the full device record and its activity/readings history — it only changes the device's status and takes it out of rotation (off its site/grid, excluded from online-status checks).

## Endpoint

```
POST /api/v2/devices/activities/decommission?deviceName={name}
```

Same auth and request/response shape as the existing `recall` action, so this should be a quick add alongside it.

**Headers:** `Authorization: JWT `

**Request body:**

```json
{
"reason": "ThingSpeak channel deleted upstream",
"date": "2024-01-15T10:30:00.000Z",
"user_id": "60f1b2e4d4a5c123456789ab",
"firstName": "John",
"lastName": "Doe",
"userName": "johndoe",
"email": "john.doe@example.com"
}
```

| Field | Required | Notes |
|---|---|---|
| `reason` | No | Free text, max 500 chars |
| `date` | Yes | ISO 8601, ≤1 month past / ≤5 min future |
| `user_id` | Yes | Mongo ObjectId of the acting user |
| `firstName` / `lastName` / `userName` / `email` | No | Attribution fields |

**Success (200):** returns `createdActivity` and `updatedDevice` (with `status: "decommissioned"`, `isActive: false`).
**Failures (400):** device not found / device already decommissioned. **(500):** internal error — safe to retry, device state is auto-restored if this happens.

## Acceptance Criteria

- [ ] Add an API call for this endpoint alongside the existing `recall` call.
- [ ] Add a **"Decommission device"** action on the device details screen.
- [ ] Confirmation dialog treats this as permanent — there is currently no "undo"/reinstate endpoint.
- [ ] Prompt for the optional `reason` field — consider a short set of common causes (channel deleted, hardware lost/destroyed, end of life) plus free text.
- [ ] Surface this as the primary retire action for hardware engineers instead of any destructive delete option, since it can never touch ThingSpeak.

## Nice-to-have

Device list/detail responses may also carry two informational fields (no new endpoint needed):

| Field | Meaning |
|---|---|
| `channelStatus` | `"not_found"` when the backend's periodic check got a 404 from the upstream channel — almost always means it was deleted upstream |
| `channelStatusCheckedAt` | Timestamp of that check |

Worth optionally surfacing on the device details screen (e.g. "Channel not found since `channelStatusCheckedAt`") to prompt a hardware engineer toward decommissioning. It clears itself automatically once the channel responds again.

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.