API 参考

名尚智联后端 REST API，统一前缀 /api。认证接口外均需 Sa-Token（Header Authorization）。

---

一、通用规范

1.1 响应格式

{
  "code": 0,
  "msg": "ok",
  "data": {}
}

code	含义
0	成功
401	未认证 / Token 过期
403	无权限
404	资源不存在
500	服务端错误

1.2 分页

GET /api/device?pageNum=1&pageSize=20

响应：

{
  "code": 0,
  "data": {
    "records": [...],
    "total": 100,
    "size": 20,
    "current": 1
  }
}

1.3 认证

# 登录
POST /api/auth/login
{"username":"admin","password":"admin123"}
# → {"code":0,"data":{"token":"uuid-token"}}

# 后续请求
curl -H "Authorization: uuid-token" http://localhost:8080/api/device

---

二、认证模块

方法	路径	说明
POST	/api/auth/login	账号密码登录
POST	/api/auth/logout	登出
GET	/api/auth/info	当前用户信息
GET	/api/auth/captcha	图形验证码

---

三、设备管理

方法	路径	说明
GET	/api/device	设备列表（分页、按产品/状态筛选）
GET	/api/device/{id}	设备详情
POST	/api/device	创建设备
PUT	/api/device/{id}	更新设备
DELETE	/api/device/{id}	删除设备
POST	/api/device/batch	批量导入（Excel）
GET	/api/device/{id}/shadow	设备影子
POST	/api/device/{id}/command	下发指令
GET	/api/device/{id}/command/log	指令日志
POST	/api/device/{id}/ota	触发 OTA

创建设备

curl -X POST http://localhost:8080/api/device \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "serial": "ESP32-001",
    "name": "车间1号传感器",
    "productId": 1,
    "tenantId": 1
  }'

设备详情（含 authCode）

{
  "code": 0,
  "data": {
    "id": 1,
    "serial": "ESP32-001",
    "authCode": "a1b2c3d4e5f6...",
    "online": 1,
    "lastOnlineTime": "2026-10-17 20:00:00"
  }
}

---

四、产品与物模型

方法	路径	说明
GET	/api/product	产品列表
GET	/api/product/{id}	产品详情（含物模型）
POST	/api/product	创建产品
PUT	/api/product/{id}	更新产品
DELETE	/api/product/{id}	删除产品
GET	/api/product/{id}/model	物模型
PUT	/api/product/{id}/model	更新物模型

物模型结构

{
  "properties": [
    {
      "identifier": "temperature",
      "name": "温度",
      "dataType": "FLOAT",
      "unit": "℃",
      "min": -40, "max": 80
    }
  ],
  "events": [
    {
      "identifier": "alarm",
      "name": "告警",
      "dataType": "STRUCT"
    }
  ],
  "services": [
    {
      "identifier": "restart",
      "name": "重启",
      "params": []
    }
  ]
}

---

五、数据查询

方法	路径	说明
GET	/api/data/realtime/{deviceId}	设备实时值（Redis TSLV）
GET	/api/data/history	历史曲线（TDengine）
GET	/api/data/export	CSV 导出

历史曲线查询

GET /api/data/history?deviceId=1&identifier=temperature&start=2026-10-01&end=2026-10-17&interval=5m

---

六、规则引擎

方法	路径	说明
GET	/api/rule	规则列表
POST	/api/rule	创建规则（LiteFlow Chain JSON）
PUT	/api/rule/{id}	更新规则
DELETE	/api/rule/{id}	删除规则
POST	/api/rule/{id}/test	测试运行

---

七、告警中心

方法	路径	说明
GET	/api/alert/rule	告警规则列表
POST	/api/alert/rule	创建告警规则
GET	/api/alert/log	告警日志（未处理/已处理）
POST	/api/alert/log/{id}/handle	处理告警

---

八、EMQX Webhook（设备认证）

方法	路径	说明
POST	/api/emqx/auth	EMQX 连接认证（Webhook）
POST	/api/emqx/publish	EMQX 消息转发

认证请求/响应

// EMQX → 后端（请求）
{"username":"ESP32-001","password":"a1b2c3...","clientid":"ESP32-001_abc"}

// 后端 → EMQX（允许）
{"result": "allow"}

// 后端 → EMQX（拒绝）
{"result": "deny","message": "authCode mismatch"}

---

九、多租户

方法	路径	说明
GET	/api/tenant	租户列表（平台管理员）
POST	/api/tenant	创建租户（自动建 tenant_* 数据库）
PUT	/api/tenant/{id}	更新租户
DELETE	/api/tenant/{id}	删除租户（保留数据库）

租户隔离通过 TenantContext ThreadLocal 自动实现，所有 SQL 自动注入 tenant_id 过滤，无需额外拦截器。