# 设备管理服务平台

版本 | 创建时间 | 作者 | 备注信息
--- | --- | --- | ---
v1.0 | 2022-01-20 | zxfei | 接口文档

## 数据类型

类型名称 | 类型描述 | 参考样例
--- | --- | ---
String | 字符串 | A、a、ab
Integer | 数字类型 | 1、12、-1
Long | 长整型数字 | 1、12、-1
date | 时间类型,单位纳秒数字 | 167988745573
BigDecimal | 小数类型 | 545.256
object | 对象类型 | {"name":"zhang3"}
arrays | 数组类型 | [{"name":"zhang3"},{"name":"zhang2"}]

## 设备终端接口服务

### 服务端地址获取

广播服务端口: 8074

广播客户端口: 8073

请求方式: UDP

内容类型: application/json;charset=utf-8

简要描述: 服务端地址获取

广播参数:

参数名称 | 类型 | 备注 | 必填 | 其它
--- | --- | --- | --- | ---
deviceNum | String | 设备编码 | 是 | -

请求样例:

    {
    "deviceNum":"12345678"
    }

响应参数:

参数名称 | 参数类型 | 备注 | 其它
--- | --- | --- | ---
code | Integer | 结果码（-1.失败，1.成功） | -
msg | String | 消息 | -
data | Object | 数据对象 | -
ip | String | ip | -
port | Integer | port | -
deviceRegisterApi | String | 设备注册API | -
deviceInitApi | String | 设备初始化信息API | -
deviceUpdateApi | String | 设备页面修改API | -

响应消息样例:

    {
        "msg":"获取服务端地址成功",
        "code":1,
        "data":{
            "ip":"192.168.0.98",
            "port":11091,,
            "deviceRegisterApi":"/m/api/register",
            "deviceInitApi":"/m/api/deviceInit",
            "deviceUpdateApi":"/m/api/deviceUpdate"
        }
    }

### 设备注册

请求URL: m/api/register

请求方式: POST

内容类型: application/json;charset=utf-8

简要描述: 设备注册，成功返回响应rabbmit连接参数,如未找到该设备，系统会根据设备码创建新设备

请求参数:

参数名称 | 类型 | 备注 | 必填 | 其它
--- | --- | --- | --- | ---
deviceCode | String | 设备编码,唯一 | 是 | 可是编码或者mac地址，由平台创建
deviceVersion | String | 设备版本信息 | 否 | -

请求样例:

    {
        "deviceCode":"a12345678",
        "deviceVersion":"1"
    }

响应参数:

参数名称 | 参数类型 | 备注 | 其它
--- | --- | --- | ---
code | Integer | 结果码（-1.失败，1.成功） | -
msg | String | 消息 | -
data | object | 数据对象 | -
content | String | 加密后的内容 | AES加密

content解密参数:

参数名称 | 参数类型 | 备注 | 其它
--- | --- | --- | ---
rabbmitInfo | Object | rabbmit相关链接信息 | -
downTopicFilter | String | 下行队列topic | -
uploadTopicFilter | String | 上行队列topic | -
username | String | rabbmit用户名 | -
password | String | rabbmit密码 | -
host | String | ip | -
port | String | 端口 | -
virtualHost | String | 虚拟机 | -
exchangeName | String | 交换机名称 | -
messageTtl | String | 队列消息超时时间，毫秒 | -
serviceInfo | Object | 服务接口连接信息 | -
homeUrl | String | 首页 | -
eventUrl | String | 事件地址 | -
serverUrl | String | 前端服务接口地址 | -
deviceInfo | Object | 设备基础信息 | -
siteId | Long | 站点ID | -
siteCode | String | 站点编码 | -
siteName | String | 站点名称 | -
productId | Long | 设备产品类型Id | -
productName | String | 设备产品类型 | -
enabled | Integer | 设备启用状态 (0.停止，1.启用) | -
source | Integer | 设备来源,默认1(0.旧设备，1.新设备) | -

响应消息样例:

    {
        "code":1,
        "data":{
            "content":"hRNPu+V1hc4lGRHtXGyVOF0U7ez8/ZxFke9L4o7DWVLMfsZwkViAChfLKSydAEWAdsbgP1dzfNrQTq7X0diu1awR/qdPNcDcpj5/hBozLn+OmuTKLUWhq9+WGtuoF3BTbtIpWkpQWDGolOCfRadenGUkuMozjEwwkt5CIDa+nzOqh56BJIhGahlx79Qt30ugj3UNhLTfvw5lpN9jY7u+icx+xnCRWIAKF8spLJ0ARYAbMXXhI21dYty7e1b+Cb2wZobupPyXRmyuy8Fkn4bculmkCywq78F6tPlu0rCCgJA="
        }
    }

### 设备初始化信息

请求URL: m/api/deviceInit

请求方式: GET

内容类型: application/json;charset=utf-8

简要描述: 设备初始化信息，提供手机编辑设备入口信息

请求参数:

参数名称 | 类型 | 备注 | 必填 | 其它
--- | --- | --- | --- | ---

请求样例:

    {}

响应参数:

参数名称 | 参数类型 | 备注 | 其它
--- | --- | --- | ---
code | Integer | 结果码（-1.失败，1.成功） | -
msg | String | 消息 | -
data | object | 数据对象 | -
productList | array | 产品列表 | 数组
productId | Long | 产品id | -
productName | String | 产品名称 | -
productCode | String | 产品编码 | -
firmList | array | 设备生产商列表 | 数组
deviceFirmId | Long | 生产商id | -
deviceFirmname | String | 生产商名称 | -
siteList | array | 站点列表 | 数组
siteId | Long | 站点id | -
siteName | String | 站点名称 | -
siteCode | String | 站点编码 | -

响应消息样例:

    {
      "code": 1,
      "data": {
        "firmList": [
          {
            "deviceFirmId": 1,
            "deviceFirmname": "四川新鸿翔"
          }
        ],
        "productList": [
          {
            "productCode": "pdj",
            "productId": 1,
            "productName": "排队机"
          },
          {
            "productCode": "ckp",
            "productId": 2,
            "productName": "窗口屏"
          }
        ],
        "siteList": [
          {
            "siteCode": "510105521000-0001",
            "siteId": 1,
            "siteName": "测试站点1"
          },
          {
            "siteCode": "513400000000-0001",
            "siteId": 2,
            "siteName": "凉山州行政审批局"
          }
        ]
      }
    }

### 设备新增或更新

请求URL: m/api/deviceUpdate

请求方式: POST

内容类型: application/json;charset=utf-8

简要描述: 设备新增或更新，提供给前端手机页面更新设备操作

请求参数:

参数名称 | 类型 | 必填 | 其它
--- | --- | --- | ---
deviceName | String | 否 | 设备名称
deviceCode | String | 是 | 设备编码,默认为MAC地址
deviceMac | String | 否 | 设备MAC地址，如不填写，默认等于deviceCode
siteId | Long | 是 | 站点Id
siteCode | String | 否 | 站点编号
siteName | String | 否 | 站点名称
productId | Long | 是 | 产品Id
deviceFirmId | Long | 否 | 设备生产厂商ID
deviceFirmname | String | 否 | 设备生产厂商名称
lon | String | 否 | 经度
lati | String | 否 | 经度
deviceInBuilding | Integer | 否 | 所属楼栋
deviceInFloor | Integer | 否 | 所属楼层
defectsLiabilityPeriod | Date | 否 | 保修期，如2020-08-12 15:00:00
leadingOfficial | String | 否 | 负责人
leadingOfficialTelephone | String | 否 | 联系电话
source | Integer | 否 | 设备来源,默认1(0.旧设备，1.新设备)
active | Integer | 否 | 设备激活,默认0(0.否，1.是)

请求样例:

    {
        "deviceName":"agpla8",
        "deviceCode":"a1-a2",
        "deviceMac":"a1-a2",
        "siteId":1,
        "siteCode":"510105521000-0001",
        "siteName":"测试站点1",
        "productId":1,
        "deviceFirmId":1,
        "lon":"12",
        "lati":"22",
        "deviceInBuilding":13,
        "deviceInFloor":22,
        "defectsLiabilityPeriod":"2022-06-30",
        "leadingOfficial":"张三",
        "leadingOfficialTelephone":"13281114856",
        "source":1,
        "active":1
    }

响应参数:

参数名称 | 参数类型 | 备注 | 其它
--- | --- | --- | ---
code | Integer | 结果码 | 见附录码表
msg | String | 消息 | -
data | object | 数据对象 | -
content | String | 加密后的内容 | AES加密

content解密参数:

参数名称 | 参数类型 | 备注 | 其它
--- | --- | --- | ---
rabbmitInfo | Object | rabbmit相关链接信息 | -
downTopicFilter | String | 下行队列topic | -
uploadTopicFilter | String | 上行队列topic | -
username | String | rabbmit用户名 | -
password | String | rabbmit密码 | -
host | String | ip | -
port | String | 端口 | -
virtualHost | String | 虚拟机 | -
exchangeName | String | 交换机名称 | -
messageTtl | String | 队列消息超时时间，毫秒 | -
serviceInfo | Object | 服务接口连接信息 | -
homeUrl | String | 首页 | -
serverUrl | String | 前端服务接口地址 | -
serviceInfo | Object | 服务接口连接信息 | -
homeUrl | String | 首页 | -
eventUrl | String | 事件地址 | -
serverUrl | String | 前端服务接口地址 | -
deviceInfo | Object | 设备基础信息 | -
siteId | Long | 站点ID | -
siteCode | String | 站点编码 | -
siteName | String | 站点名称 | -
productId | Long | 设备产品类型Id | -
productName | String | 设备产品类型 | -
enabled | Integer | 设备启用状态 (0.停止，1.启用) | -

响应消息样例:

    {
        "code":1,
        "data":{
            "content":"hRNPu+V1hc4lGRHtXGyVOF0U7ez8/ZxFke9L4o7DWVLMfsZwkViAChfLKSydAEWAdsbgP1dzfNrQTq7X0diu1awR/qdPNcDcpj5/hBozLn+OmuTKLUWhq9+WGtuoF3BTbtIpWkpQWDGolOCfRadenGUkuMozjEwwkt5CIDa+nzOqh56BJIhGahlx79Qt30ugj3UNhLTfvw5lpN9jY7u+icx+xnCRWIAKF8spLJ0ARYAbMXXhI21dYty7e1b+Cb2wZobupPyXRmyuy8Fkn4bculmkCywq78F6tPlu0rCCgJA="
        }
    }

### 设备版本检查

请求URL: m/api/checkVersion

请求方式: POST

内容类型: application/json;charset=utf-8

简要描述: 检查当前设备所属版本最新版本信息

请求参数:

参数名称 | 类型 | 备注 | 必填 | 其它
--- | --- | --- | --- | ---
deviceCode | String | 设备编码,唯一 | 是 | 可是编码或者mac地址，由平台创建
deviceVersion | String | 设备版本信息 | 否 | -

请求样例:

    {
        "deviceCode":"a12345678"
    }

响应参数:

参数名称 | 参数类型 | 备注 | 其它
--- | --- | --- | ---
code | Integer | 结果码（-1.失败，1.成功） | -
msg | String | 消息 | -
data | object | 数据对象 | -
content | String | 加密后的内容 | AES加密

content解密参数:

参数名称 | 参数类型 | 备注 | 其它
--- | --- | --- | ---
productId | Long | 产品Id | -
productCode | String | 产品编号 | -
productName | String | 产品名称 | -
version | Int | 版本号 | -
remark | String | 备注信息 | -
downloadUrl | String | 版本下载地址 | -

响应消息样例:

    {
        "code":1,
        "data":{
            "content":"hRNPu+V1hc4lGRHtXGyVOF0U7ez8/ZxFke9L4o7DWVLMfsZwkViAChfLKSydAEWAdsbgP1dzfNrQTq7X0diu1awR/qdPNcDcpj5/hBozLn+OmuTKLUWhq9+WGtuoF3BTbtIpWkpQWDGolOCfRadenGUkuMozjEwwkt5CIDa+nzOqh56BJIhGahlx79Qt30ugj3UNhLTfvw5lpN9jY7u+icx+xnCRWIAKF8spLJ0ARYAbMXXhI21dYty7e1b+Cb2wZobupPyXRmyuy8Fkn4bculmkCywq78F6tPlu0rCCgJA="
        }
    }

## 对外平台接口服务

### 获取接口访问token

请求URL: m/api/getToken

请求方式: POST

内容类型: application/json;charset=utf-8

简要描述: 获取接口访问token

请求参数:

参数名称 | 类型 | 备注 | 必填 | 其它
--- | --- | --- | --- | ---
loginName | String | 平台用户名称 | 是 | -
password | String | 平台用户密码 | 是 | -

请求样例:

响应参数:

参数名称 | 参数类型 | 备注 | 其它
--- | --- | --- | ---
code | Integer | 结果码 | 见附录码表
msg | String | 消息 | -
data | object | 数据对象 | -

响应消息样例:

### 接收第三方平台设备消息

请求URL: m/api/receive

请求方式: POST

鉴权头信息: Authorization: {{token}}

内容类型: application/json;charset=utf-8

简要描述:

请求参数:

参数名称 | 类型 | 备注 | 必填 | 其它
--- | --- | --- | --- | ---
receiveMethod | Integer | 1：新增，2：修改，3：删除，4：激活，5：启用，6：停用 | 是 | -
deviceName | String | 设备名称 | 否 | -
deviceCode | String | 设备编码，如MAC地址 | 是 | -
platformCode | String | 平台系统编码 | 是 | 见平台编码附录
productCode | String | 产品编码 | 是 | 见产品编码附录
ip | String | 设备访问ip | 否 | -
port | String | 设备端口 | 否 | -
siteId | Long | 站点ID，来源基础服务平台 | 是 | -
leadingOfficial | String | 负责人 | 否 | -
leadingOfficialTelephone | String | 否 | 联系电话 | -
siteCode | String | 站点编号，来源基础服务平台 | 是 | -
siteName | String | 站点名称 | 是 | -
homeUrl | String | 首页地址 | 否 | -
deviceRemark | String | 备注 | 是 | -
deviceStatus | Integer | 设备状态 (0.未激活，1.离线,2.在线) | 是 | 默认0为激活
source | Integer | (0.旧设备，1.新设备) | 是 | 默认1新设备

请求样例:

    {}

响应参数:

参数名称 | 参数类型 | 备注 | 其它
--- | --- | --- | ---
code | Integer | 结果码 | 见附录码表
msg | String | 消息 | -
data | object | 数据对象 | -

响应消息样例:

### 接收第三方平台命令消息

请求URL: m/api/callback

请求方式: POST

内容类型: application/json;charset=utf-8

简要描述: 以数组方式进行提交

请求参数:

参数名称 | 类型 | 备注 | 必填 | 其它
--- | --- | --- | --- | ---
deviceCode | String | 设备编码，如MAC地址 | 是 | -
messageType | String | 消息类型 | 是 | 如HEART_BEAT
timestamp | Long | 时间戳 | 是 | -
data | String | 数据体，内容自行定义 | 否 | -

请求样例:

    [
        {
            "data":"{xxxx}",
            "deviceCode":"a1",
            "messageType":"HEART_BEAT",
            "timestamp":1654656951795
        },
        {
            "data":"{bbbbbb}",
            "deviceCode":"a2",
            "messageType":"HEART_BEAT",
            "timestamp":1654656951795
        }
    ]

响应参数:

参数名称 | 参数类型 | 备注 | 其它
--- | --- | --- | ---
code | Integer | 结果码 | 见附录码表
msg | String | 消息 | -

响应消息样例:

### 回调各个平台通知消息

请求URL: 各平台通知地址

请求方式: POST

内容类型: application/json;charset=utf-8

简要描述: 设备消息通知各个平台，当配置了地址时候

请求参数:

参数名称 | 类型 | 备注 | 必填 | 其它
--- | --- | --- | --- | ---
type | Integer | 消息类型 | 是 | 0:设备增删改查，data数据域封装具体设备消息，1：设备消息类，数据域透传设备上行消息体。
msg | String | 消息 | 否 | -
data | object | 数据对象 | 是 | -
deviceStatus | Integer |  | 是 | 状态，1：新增，2：修改，3：删除，4：激活，5：启用，6：停用，7：上线，8：下线
deviceName | String | 设备名称 | 否 | -
deviceCode | String | 设备编码，如MAC地址 | 是 | -
productCode | String | 产品编码 | 是 | 见附录
ip | String | 设备访问ip | 否 | -
port | String | 设备端口 | 否 | -
leadingOfficial | String | 负责人 | 否 | -
leadingOfficialTelephone | String | 联系电话 | 否 | -
siteId | Long | 站点ID，来源基础服务平台 | 是 | -
siteCode | String | 站点编号，来源基础服务平台 | 是 | -
siteName | String | 站点名称 | 是 | -
deviceRemark | String | 备注 | 是 | -

请求样例:

    {}

响应参数:

参数名称 | 参数类型 | 备注 | 其它
--- | --- | --- | ---
code | Integer | 结果码 | 见附录码表
msg | String | 消息 | -
data | object | 数据对象 | -

响应消息样例:

## 设备消息

### 上行消息

topic: uploadTopicFilter

请求方式: rabbmitMQ

内容类型: application/json;charset=utf-8

简要描述: 上行消息存放队列

请求参数:

参数名称 | 类型 | 备注 | 必填 | 其它
--- | --- | --- | --- | ---
headers | Object | 消息头 | 是 | -
data | Object | 消息头数据对象 | 是 | -
protocol | String | 数据域协议类型，默认json | 是 | -
messageType | String | 上报消息类型 | 是 | HEART_BEAT
deviceCode | String | 设备编码信息 | 是 | 如:mac地址
sign | String | 签名 | 是 | -
timestamp | String | 时间戳 | 是 | -
data | byte[] | byte数组，base64编码 | 是 | -
key | String | 消息唯一标识 | 是 | -

请求样例:

    {
        "data":"YWJjZDEyMzQ=",
        "headers":{
            "data":{
                "protocol":"json",
                "messageType":"HEART_BEAT",
                "deviceCode":"A1:A2:A3:A4:A5:A6",
                "sign":"abcd1234",
                "timestamp":"2022-04-15 09:48:05"
            }
        },
        "key":"d3635cd0597d46c88b85797c3846b04f"
    }

### 下行消息

topic: downTopicFilter

请求方式: rabbmitMQ

内容类型: application/json;charset=utf-8

简要描述: 下行消息存放队列

请求参数:

参数名称 | 类型 | 备注 | 必填 | 其它
--- | --- | --- | --- | ---
headers | Object | 消息头 | 是 | -
data | Object | 消息头数据对象 | 是 | -
protocol | String | 数据域协议类型，默认json | 是 | -
messageType | String | 下发消息类型 | 是 | UPGREAD
deviceCode | String | 设备编码信息 | 是 | 如:mac地址
sign | String | 签名 | 是 | -
timestamp | String | 时间戳 | 是 | -
data | byte[] | byte数组，base64编码 | 是 | -
key | String | 消息唯一标识 | 是 | -

请求样例:

    {
        "data":"YWJjZDEyMzQ=",
        "headers":{
            "data":{
                "protocol":"json",
                "messageType":"UPGREAD",
                "deviceCode":"A1:A2:A3:A4:A5:A6",
                "sign":"abcd1234",
                "downloadUrl":"http://xxxxx",
                "timestamp":"2022-04-15 09:48:05"
            }
        },
        "key":"d3635cd0597d46c88b85797c3846b04f"
    }

## 码表

### 响应结果码表

结果码 | 结果 | 其它
--- | --- | ---
1 | 成功 | -
1001 | 当前设备编码不存在 | -
1002 | 当前设备编码已存在 | -
1003 | 所属产品编码不存在 | -
1004 | 当前设备未激活，请在后台配置后再激活 | -
1005 | 所属平台不存在！请在后台添加后再激活 | -
1006 | 当前设备所属产品平台未配置，请在后台配置后再激活 | -
1007 | 站点ID为空 | -
1008 | 设备已创建，请完善设备配置信息 | -
1009 | 当前设备不存在 | -
1010 | token认证失败 | -
1011 | 未找到设备版本信息 | -
-1 | 系统内部异常 | -

## 附录

### 业务上行下行消息类型

编码 | 说明 | 其它
--- | --- | ---
HEART_BEAT | 设备心跳消息 | 设备上行发送