docs: 添加完整 API 文档 — Gateway 统一文档 + 后端服务文档
新增 docs/api/gateway-api.md：面向客户端开发的网关 API 统一文档，覆盖全部 16 个模块。 新增 docs/api/backend-services/：后端服务详细文档 (ai-core, memory-service, voice-service, iot-debug, tool-engine)。 更新 .gitignore：docs/api/ 例外允许推送，其他 docs/ 内容仍忽略。 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,178 @@
|
||||
# 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":"请求格式错误"}` |
|
||||
Reference in New Issue
Block a user