# 기기

앱 연결 토큰으로 호출합니다.

매장 기기는 한 경로로 다룹니다. 목록으로 기기와 연결 상태를 보고, 명령으로 조작합니다.

## 목록과 단건

`GET /device/v1/devices` · `GET /device/v1/devices/{id}`

문은 `kind`가 `door`인 행입니다. 여기서 얻은 `id`가 명령의 `{id}`이고 출입 허가 `doorIds`의 값입니다.

| 필드 | 의미 |
|---|---|
| `id` | 기기 ID |
| `name` | 이름 |
| `health.state` | `online`, `offline`, `unknown`(아직 한 번도 연결된 적 없음) |
| `capabilities` | 받을 수 있는 명령 묶음 |

단건은 문의 지금 상태(`standing`)를 더합니다.

## 명령

`POST /device/v1/devices/{id}/commands`

```bash
curl -X POST https://api.superplace.so/device/v1/devices/$DOOR/commands \
  -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"capability":"door","command":"hold","args":{"minutes":60}}'   # minutes 0 = 잠글 때까지
```

| 명령 | 동작 |
|---|---|
| `door.open` | 잠깐 열기 |
| `door.hold` | 열어두기 |
| `door.close` | 잠그기 |

`args.reason`은 기록용입니다.

`Idempotency-Key` 헤더는 필수입니다. 없으면 400입니다. 요청마다 고유한 문자열(UUID 권장)을 넣습니다. 타임아웃 뒤 같은 값으로 다시 보내면 문이 두 번 열리지 않고 처음 결과가 돌아옵니다. 모든 호출이 출입 기록 `GET /device/v1/entry-log`에 남습니다.

## 결과

기기가 실제로 실행했다고 답한 뒤에 응답합니다. 성공은 `200`과 `outcome: reported`입니다.

실패는 `details.reason`으로 구분합니다.

| `reason` | 의미 | 상태코드 |
|---|---|---|
| `offline` | 연결 끊김. 명령을 보내지 않았습니다. | 409 |
| `refused` | 기기가 거절했습니다. | 502 |
| `noResponse` | 기기가 답하지 않았습니다. 실행됐는지 알 수 없습니다. | 504 |

504를 받으면 같은 `Idempotency-Key`로 다시 보냅니다. 처음 명령이 실행됐다면 그 결과가 돌아오고, 아니면 다시 시도합니다. 실제로 열렸는지는 `GET /device/v1/entry-log`로 확인합니다. `health.state`가 `unknown`인 기기는 아직 연결된 적이 없으니 `offline`과 같이 다룹니다.