Skip to content

API.md

Latest commit

 

History

History
307 lines (217 loc) · 5.36 KB

API.md

File metadata and controls

307 lines (217 loc) · 5.36 KB
Raw

接口文档

通用约定

所有接口返回统一结构：

{
  "code": 200,
  "message": "success",
  "data": {}
}

分页接口的 data 结构：

{
  "records": [],
  "total": 0,
  "page": 1,
  "size": 10
}

需要认证的接口使用请求头：

Authorization: Bearer <accessToken>

健康检查

GET /api/health

无需认证。

响应字段：

字段 说明
status 服务状态
application 应用名称
timestamp 当前服务时间

登录认证

POST /api/auth/login

无需认证。

请求体：

{
  "username": "operator",
  "password": "operator-password"
}

响应 data：

字段 说明
accessToken JWT 访问令牌
tokenType 固定为 Bearer
expiresIn 过期秒数
user 登录用户信息

设备分组

GET /api/device-groups

需要登录。

查询参数：

参数 类型 说明
parentId number 父分组 ID
keyword string 分组名称或编码关键字
page number 页码，默认 1
size number 每页数量，默认 10，最大 100

POST /api/device-groups

需要 ADMIN 或 OPERATOR 角色。

{
  "parentId": null,
  "groupName": "Factory A",
  "groupCode": "FACTORY_A",
  "description": "Factory A devices"
}

PUT /api/device-groups/{id}

需要 ADMIN 或 OPERATOR 角色。

{
  "parentId": null,
  "groupName": "Factory A",
  "description": "Updated description"
}

DELETE /api/device-groups/{id}

需要 ADMIN 或 OPERATOR 角色。删除前会检查子分组和关联设备。

GET /api/device-groups/{id}

需要登录。

设备管理

GET /api/devices

需要登录。

查询参数：

参数 类型 说明
groupId number 分组 ID
keyword string 设备名称或 SN
deviceType string 设备类型
status string ONLINE、OFFLINE、FAULT、MAINTENANCE、INACTIVE
page number 页码，默认 1
size number 每页数量，默认 10，最大 100

POST /api/devices

需要 ADMIN 或 OPERATOR 角色。

{
  "groupId": 1,
  "deviceSn": "SN-001",
  "deviceName": "Gateway",
  "deviceType": "GATEWAY",
  "status": "OFFLINE",
  "firmwareVersion": "1.0.0",
  "location": "Factory A",
  "ipAddress": "192.168.1.10"
}

PUT /api/devices/{id}

需要 ADMIN 或 OPERATOR 角色。

{
  "groupId": 1,
  "deviceName": "Gateway A",
  "deviceType": "GATEWAY",
  "status": "ONLINE",
  "firmwareVersion": "1.0.1",
  "location": "Factory A",
  "ipAddress": "192.168.1.10"
}

DELETE /api/devices/{id}

需要 ADMIN 或 OPERATOR 角色。删除前会检查属性、遥测和命令记录。

GET /api/devices/{id}

需要登录。

设备状态

POST /api/devices/{id}/status

需要 ADMIN 或 OPERATOR 角色。

{
  "status": "ONLINE",
  "reportedAt": "2026-06-19T13:00:00",
  "reason": "heartbeat"
}

GET /api/devices/{id}/status-history

需要登录。

查询参数：

参数 类型 说明
source string REPORT 或 OFFLINE_DETECTION
page number 页码，默认 1
size number 每页数量，默认 10，最大 100

操作日志

GET /api/operation-logs

需要 ADMIN 角色。前端仅管理员显示操作日志菜单。

查询参数：

参数 类型 说明
username string 操作用户名，模糊查询
operationType string CREATE、UPDATE、DELETE、REPORT_STATUS
targetType string DEVICE、DEVICE_GROUP
resultStatus string SUCCESS 或 FAILED
page number 页码，默认 1
size number 每页数量，默认 10，最大 100

操作日志只记录操作元数据，不记录密码、JWT 密钥、数据库密码或请求体。

用户管理

当前用户接口需要登录。管理员用户管理接口需要 ADMIN 角色。所有响应都不会返回密码哈希。

GET /api/users/me

查询当前登录用户资料。

PUT /api/users/me/password

修改当前登录用户密码。旧密码校验通过后，新密码会使用 BCrypt 加密保存；修改成功后前端会退出登录。

{
  "oldPassword": "operator-password",
  "newPassword": "new-operator-password"
}

GET /api/users

需要 ADMIN 角色。

查询参数：

参数 类型 说明
keyword string 用户名或显示名称
accountStatus string ENABLED、DISABLED、LOCKED
page number 页码，默认 1
size number 每页数量，默认 10，最大 100

POST /api/users

需要 ADMIN 角色。

{
  "username": "viewer",
  "password": "viewer-password",
  "displayName": "Viewer",
  "email": "viewer@example.com",
  "phone": "13800000000",
  "roles": ["VIEWER"]
}

密码会使用 BCrypt 加密后保存。

PUT /api/users/{id}

需要 ADMIN 角色。

{
  "displayName": "Viewer",
  "email": "viewer@example.com",
  "phone": "13800000000",
  "roles": ["VIEWER"]
}

PUT /api/users/{id}/status

需要 ADMIN 角色。

{
  "accountStatus": "DISABLED"
}

PUT /api/users/{id}/password

需要 ADMIN 角色。

{
  "password": "new-password"
}

GET /api/users/{id}

需要 ADMIN 角色。

查询单个用户详情。