# IoT Debug Service API

**Base URL:** `http://<host>:8083` | **Auth:** 无

模拟 IoT 设备的调试服务，预置 8 个设备用于开发和测试。所有状态存储在内存中，重启后重置。

---

## 目录

1. [GET /api/v1/health](#1-get-apiv1health)
2. [GET /api/v1/devices](#2-get-apiv1devices)
3. [GET /api/v1/devices/:id](#3-get-apiv1devicesid)
4. [GET /api/v1/devices/:id/history](#4-get-apiv1devicesidhistory)
5. [POST /api/v1/devices/:id/toggle](#5-post-apiv1devicesidtoggle)
6. [POST /api/v1/devices/:id/set](#6-post-apiv1devicesidset)

---

## 预置设备

| ID | 名称 | 类型 | 默认状态 |
|----|------|------|----------|
| `light-livingroom` | 客厅灯 | light | off, brightness=0 |
| `light-bedroom` | 卧室灯 | light | off, brightness=0 |
| `ac-livingroom` | 客厅空调 | ac | off, temperature=26 |
| `ac-bedroom` | 卧室空调 | ac | off, temperature=26 |
| `curtain-livingroom` | 客厅窗帘 | curtain | closed, position=0 |
| `sensor-temperature` | 温度传感器 | sensor | value=25.5, unit=celsius |
| `sensor-humidity` | 湿度传感器 | sensor | value=60.0, unit=percent |
| `lock-door` | 智能门锁 | lock | locked |

---

## 数据模型

### Device

| 字段 | 类型 | 适用类型 | 说明 |
|------|------|----------|------|
| `id` | string | 全部 | 设备 ID |
| `name` | string | 全部 | 设备名称 |
| `type` | string | 全部 | `light`, `ac`, `curtain`, `sensor`, `lock` |
| `status` | string | 全部 | `on`/`off`, `open`/`closed`, `locked`/`unlocked` |
| `brightness` | int | light | 0-100 |
| `color` | string | light | 颜色标识 |
| `temperature` | float64 | ac | 设定温度 |
| `mode` | string | ac | `cool`, `heat`, `auto` |
| `position` | int | curtain | 0-100 |
| `value` | float64 | sensor | 传感器读数 |
| `unit` | string | sensor | `celsius`, `percent` |
| `battery` | int | lock | 电池百分比 |
| `last_updated` | string | 全部 | RFC3339 时间戳 |

### HistoryEntry

| 字段 | 类型 | 说明 |
|------|------|------|
| `timestamp` | string | RFC3339 |
| `field` | string | 变更字段名 |
| `old_value` | string | 旧值 |
| `new_value` | string | 新值 |

---

## 1. GET /api/v1/health

```json
{ "status": "ok", "service": "iot-debug-service" }
```

---

## 2. GET /api/v1/devices — 设备列表

`history` 字段在列表中始终为 null。

```json
{
  "devices": [ Device, ... ],
  "total": 8
}
```

---

## 3. GET /api/v1/devices/:id — 设备详情

含最近 10 条 `history`。

```json
{
  "device": {
    "id": "light-livingroom",
    "name": "客厅灯",
    "type": "light",
    "status": "off",
    "brightness": 0,
    "color": "warm_white",
    "last_updated": "2024-01-01T12:00:00Z",
    "history": [
      { "timestamp": "2024-01-01T12:00:00Z", "field": "status", "old_value": "on", "new_value": "off" }
    ]
  }
}
```

**404:** `{"error":"设备 {id} 不存在"}`

---

## 4. GET /api/v1/devices/:id/history — 设备历史

```json
{
  "device_id": "string",
  "history": [ HistoryEntry, ... ]
}
```

---

## 5. POST /api/v1/devices/:id/toggle — 切换状态

**请求体:** 空。

```json
// 响应 200
{ "device": Device, "action": "toggled" }
```

### 行为

| 设备类型 | 行为 |
|----------|------|
| light | on ↔ off。off 时 brightness=0，on 时 brightness=80 |
| ac | on ↔ off |
| curtain | closed (position=0) ↔ open (position=100) |
| lock | locked ↔ unlocked |
| sensor | **不支持**，返回错误 |

---

## 6. POST /api/v1/devices/:id/set — 设置属性

```json
// 请求
{ "field": "brightness", "value": 80 }
```

### 有效 field/value 组合

| field | value | 适用设备 | 说明 |
|-------|-------|----------|------|
| `status` / `power` | `"on"`/`"off"`/`"open"`/`"closed"`/`"locked"`/`"unlocked"` | 除 sensor | 中文 `"开"`/`"关"` 也支持 |
| `status` / `power` | `true`/`false` | 除 sensor | true→on, false→off |
| `status` / `power` | 数字 | 除 sensor | 0→off, 非0→on |
| `temperature` | number | ac | — |
| `brightness` | int 0-100 | light | — |
| `position` | int 0-100 | curtain | — |
| `mode` | `"cool"`/`"heat"`/`"auto"` | ac | — |
| `color` | string | light | 如 `"warm_white"`, `"colorful"` |

```json
// 响应 200
{ "device": Device, "action": "set_brightness" }
```

### 错误

| 状态码 | 错误体 |
|--------|--------|
| 400 | `{"error":"设备 {id} 不存在"}` |
| 400 | `{"error":"无效的状态值: ..."}` |
| 400 | `{"error":"temperature 需要数字值"}` |
| 400 | `{"error":"设备 {name} (类型 {type}) 不支持温度调节"}` |
| 400 | `{"error":"不支持的属性: {field}"}` |
| 400 | `{"error":"请求格式错误"}` |