第十一部分：MVP API 接口文档

11.1 通用约定

Base URL：http://127.0.0.1:3000
编码：UTF-8 JSON。
管理员和小程序接口通过 Authorization: Bearer <token> 认证。
成功响应：{"code":0,"message":"ok","data":...}。
失败响应：{"code":"ERROR_CODE","message":"可读说明"}，HTTP 状态码表达错误类型。
时间为 ISO 8601 UTC 字符串；调用方按本地时区显示。
当前 API 为 MVP v0 契约。生产版建议统一增加 /api/v1 前缀、requestId 和分页结构。

11.2 公共与认证接口

`GET /api/health`

无需认证。返回服务、数据结构版本和服务器时间。

`POST /api/auth/login`

管理后台登录。

{ "username": "admin", "password": "admin123" }

返回 token 和去除密码字段的 user。错误账号返回 HTTP 401 / INVALID_CREDENTIALS。

`GET /api/auth/me`

返回当前令牌对应用户，用于恢复后台会话。

11.3 管理后台接口

方法与路径	角色	说明
`GET /api/admin/summary`	admin/operator	汇总指标、趋势、最近告警和指令
`GET /api/admin/products`	admin/operator	产品列表，支持 `keyword`
`POST /api/admin/products`	admin	创建产品
`GET /api/admin/devices`	admin/operator	设备列表，支持 `keyword`、`status`
`POST /api/admin/devices`	admin/operator	注册设备
`PATCH /api/admin/devices/{id}`	admin/operator	修改名称、固件或演示状态
`GET /api/admin/users`	admin/operator	用户及绑定设备数量
`GET /api/admin/commands`	admin/operator	指令列表
`POST /api/admin/commands`	admin/operator	下发指令
`GET /api/admin/alerts`	admin/operator	告警列表，支持 `status`
`PATCH /api/admin/alerts/{id}`	admin/operator	更新告警状态
`GET /api/admin/audits`	admin	最近 100 条审计日志

创建产品：

{
  "name": "四路智能开关",
  "productKey": "SWITCH-4CH",
  "category": "智能开关",
  "protocol": "MQTT",
  "modelVersion": "1.0.0"
}

注册设备：

{
  "deviceName": "客户展厅开关",
  "serialNumber": "SW20260912001",
  "productId": "p-switch",
  "firmware": "1.0.0"
}

服务端生成 id、bindCode 和 deviceSecret。生产 API 应只在创建响应展示一次 deviceSecret，列表永不返回。

下发指令：

{
  "deviceId": "d-switch-001",
  "name": "setPower",
  "params": { "power": false }
}

在线设备在 MVP 返回 succeeded；离线设备返回 pending。生产接口应优先返回 202/pending，由 ACK 异步更新。

处置告警：

{ "status": "resolved" }

11.4 设备接入接口

`POST /api/device/telemetry`

请求头：

X-Device-Id: d-switch-001
X-Device-Secret: dev-secret-switch-001
Content-Type: application/json

请求体：

{
  "ts": "2026-09-12T04:00:00.000Z",
  "data": { "power": true, "voltage": 220.1, "current": 0.16 }
}

成功返回 HTTP 202，并保存遥测、合并当前属性、将设备设为在线并刷新 lastSeenAt。凭据错误返回 401 DEVICE_AUTH_FAILED；data 不是对象返回 422。

真实 MQTT 接入的 Topic 和消息信封见 5-1系统设计-一些细节.md。

11.5 小程序接口

`POST /api/mini/auth/wechat`

{ "code": "wx.login 返回的 code", "nickname": "微信用户" }

MVP 将 code 映射为演示 openid；生产服务端必须调用微信 code2Session，不得信任客户端上传的 openid。

`GET /api/mini/devices`

只返回当前用户绑定设备，响应中不包含 deviceSecret。

`POST /api/mini/devices/bind`

{ "bindCode": "IOT-GW-0002" }

无效码返回 404；被其他用户绑定返回 409；属于同一用户时幂等返回设备。

`GET /api/mini/devices/{id}`

返回本人设备详情以及最近 20 条遥测。请求其他用户或未绑定设备统一返回 404。

`POST /api/mini/devices/{id}/commands`

{ "name": "setPower", "params": { "power": true } }

只有设备所有者可以操作。

11.6 错误码

HTTP	code	场景
400	`INTERNAL_ERROR`（带格式说明）	JSON 解析失败
401	`UNAUTHORIZED`	令牌缺失、错误或过期
401	`INVALID_CREDENTIALS`	后台账号或密码错误
401	`DEVICE_AUTH_FAILED`	设备身份无效
403	`FORBIDDEN`	角色权限不足
404	`NOT_FOUND` / `DEVICE_NOT_FOUND`	路由或授权范围内对象不存在
409	`PRODUCT_KEY_EXISTS` / `SERIAL_EXISTS`	唯一键冲突
409	`DEVICE_ALREADY_BOUND`	设备已归属其他用户
422	`VALIDATION_ERROR`	必填字段或数据类型不满足

11.7 调用示例（PowerShell）

$login = Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:3000/api/auth/login `
  -ContentType 'application/json' `
  -Body '{"username":"admin","password":"admin123"}'

$headers = @{ Authorization = "Bearer $($login.data.token)" }
Invoke-RestMethod -Uri http://127.0.0.1:3000/api/admin/devices -Headers $headers

📒 笔记文档