Cyrene/docs/api/backend-services/iot-debug.md

IoT Debug Service API

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

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

---

目录

1. GET /api/v1/health
2. GET /api/v1/devices
3. GET /api/v1/devices/:id
4. GET /api/v1/devices/:id/history
5. POST /api/v1/devices/:id/toggle
6. POST /api/v1/devices/:id/set

---

预置设备

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

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

---

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

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

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

---

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

含最近 10 条 history。

{
  "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 — 设备历史

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

---

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

请求体: 空。

// 响应 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 — 设置属性

// 请求
{ "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"

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

错误

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