bw-platform-sdk v0.7.5

bw-platform-sdk 入门

欢迎使用博康开发者平台前端 sdk 库，在这里你将了解到如何通过本 sdk 访问平台数据内容

前置条件

本 sdk 仅供前端 app 开发者使用，请事先下载并安装博康开发者平台，平台下载请咨询 179554574@qq.com

安装

本 sdk 基于 es6 规范，支持 vue 等框架集成调用，以下将以 vue 的方式进行说明

通过 yarn 安装开发包:

yarn add bw-platform-sdk

在 vue 项目 main.js 中全局引入 sdk

import sdk from "bw-platform-sdk";
Vue.prototype.sdk = sdk;

除了全局引入外，也可以在单独的 vue 文件中局部引入

import {user,device} from 'bw-platform-sdk'

user.login({ ... }) //平台登录
device.list({ ... }) //查询设备

依赖项

本 sdk 内部引用 ant-design-vue 和 axios 作为网络请求和消息提示，通过 app 模板增加的项目已预先引用，如果是自己创建的项目请确保自身项目包含这两个依赖

使用

在需要调用的页面通过如下方式访问：

this.sdk.device.add({ ... }) //添加设备
this.sdk.device.list({ ... }) //查询设备

说明

sdk 所有函数均返回 Promise 对象

sdk.user
  .login({
    username: "admin",
    password: "123456",
  })
  .then((res) => {
    //返回数据
  })
  .catch((err) => {
    //发生异常
  });

如果接口正确调用，统一返回如下格式的数据：

{
    code: 0, //0表示正确，其他数字表示异常
    msg: "ok", //如果code不为0，此处则是具体错误内容，msg可能是string，也可能是一串错误array
    data: {
        //如果code为0，这里则是具体返回的数据
    }
}

平台会统一拦截 code 不为 0 的错误并给出默认提示，一般情况下无需自行处理，如需要自己处理请求异常，则如下处理

sdk.user
  .login({
    username: "xxx",
    passowrd: "xxx",
  })
  .catch((err) => {
    //登录失败
    this.$message.error("登录失败！");
  });

独立模式和平台模式

如果是独立开发 app 而非通过平台加载，则需要自行处理登录，报警，权限等等的业务功能，如果是通过平台加载的应用，一般情况下只用关注应用本身的业务开发，无需处理额外逻辑，如用户登录，报警接收等

高级特性

字段扩展

为满足项目实际应用需要，平台数据库字段支持动态扩充，当前支持以下数据的动态扩展

• 区域地点
• 组织机构
• 设备
• 人口
• 车辆
• 报警

扩展数据统一以 meta 字段存放，存放格式为 json，以下以报警业务举例说明

根据业务需求，报警数据需增加处理状态，处理人，处理意见业务

可通过 sdk 动态增加这些数据

sdk.alarm.update({
  id: "1",
  "meta.处理状态": "处理中",
  "meta.处理人": "张三",
  "meta.处理意见": "正在上门核实",
});

通过这样调用，就为 id 为 1 这条报警添加了处理过程

同时，自定义字段支持动态查找，比如需要查找全部处理中的报警可通过如下方式：

sdk.alarm.list({
  page: "0",
  count: 20,
  extend: {
    "meta.处理状态.$eq": "处理中",
    "meta.处理人.$like": "张三%",
  },
});

extend 用来专门查找自定义的字段，其结构如下 meta.{自定义状态}.{查询函数}:{查询值}

目前支持以下函数：

• \$eq
• \$ne
• \$gte
• \$gt
• \$lte
• \$lt
• \$not
• \$in
• \$notIn
• \$is
• \$like
• \$notLike
• \$iLike
• \$notILike
• \$regexp
• \$notRegexp
• \$iRegexp
• \$notIRegexp
• \$between
• \$notBetween
• \$overlap
• \$contains
• \$contained
• \$adjacent
• \$strictLeft
• \$strictRight
• \$noExtendRight
• \$noExtendLeft
• \$and
• \$or
• \$any
• \$all
• \$values
• \$col

具体使用方法请参考

https://sequelize.org/master/manual/model-querying-basics.html

数据模型

待补充...

功能介绍

sdk 主要包含以下功能，并且随着后期迭代会不断增加新功能

• 应用管理
• 用户管理
• 权限管理
• 通知管理
• 区域地点管理
• 组织机构管理
• 配置管理
• 设备管理
• 人口管理
• 车辆管理
• 报警管理
• 报警处置管理
• API 请求日志管理
• 用户自定义日志管理

应用管理

列出全部已安装的应用

sdk.app.list();
// 注意：这只是后端已经加载的应用，并非前端已经打开的应用

打开应用

sdk.app.open(appid - or - appname, callback);
// 参数一：appid或app名称
// 参数二：(非必填)打开成功后的回调函数（可获取到对应的iframe）

// 用法示例
sdk.app
  .open("emap", (app) => {
    //如果app没打开，则会启动app，加载成功后会执行回调返回frame对象
    //如果app已打开，则会直接通过回调返回当前app的frame对象
    console.log(app.contentWindow);
  })
  .then((res) => {
    console.log("打开成功", res);
  })
  .catch((e) => {
    console.error("打开失败", e);
  });

应用间内部通信

凡是引用了 bw-platform-sdk 的应用都会在 window 对象中挂载 sdk 实例，如果 app 需要向其他 app 提供特色功能的话，可在 sdk 中注册自定义函数然后挂载到 sdk 内部 methods 对象上

app1：

sdk.methods.yourmethod = function() {
  console.log("method invoked");
};

其他 app 需要调用 app 自定义方法可通过如下步骤

1. 首先打开 app 获取 app 实例
2. 调用 app 注册的自定义函数

app2：

sdk.app.open("app1", (app) => {
  //判断app有没有这个函数，有的话调用
  app.contentWindow.sdk &&
    app.contentWindow.sdk.methods &&
    app.contentWindow.sdk.methods.yourmethod &&
    app.contentWindow.sdk.methods.yourmethod();
});

用户管理

用户登录

sdk.user.login({
  username: "admin",
  password: "123456",
});

获取当前登录账号详情

sdk.user.my();

返回内容:

{
  "code": 0,
  "message": "ok",
  "data": {
    "data": {
      "id": 1,
      "username": "admin",
      "realname": "管理员",
      "email": null,
      "phone": "88888888888",
      "gender": null,
      "birth": null,
      "type": "user",
      "meta": null,
      "note": null,
      "createdAt": "2021-09-24T01:46:11.026Z",
      "updatedAt": "2021-09-24T01:46:11.026Z"
    },
    "iat": 1632448488,
    "exp": 1632534888
  }
}

获取指定账号详情

sdk.user.get({
  id: 1,
});

获取当前登录账号通知列表

sdk.user.myMessages({
  page: 0, //页码
  count: 5, //分页数
  keyword: "%", //关键词
  sender: [1, 3], //发送人-不传代表全部
  type: ["test"], //类型
  state: ["new", "open", "close", "other"], //状态
  startTime: "2020-07-16 16:00:00", //开始时间
  endTime: "2033-07-16 16:05:59", //结束时间
  //扩展字段自定义查询语句
  extend: {
    "meta.isDeal.$eq": 1,
  },
});

添加用户

sdk.user.add({
  username: "test",
  password: "123456",
  realname: "真实姓名",
  email: "xxx@xxx.com",
  phone: "13888888888",
  gender: "男",
  birth: "1983-10-08",
  type: "user",
  note: "备注",
});

更新用户

sdk.user.update({
  id: 1, //用户id
  //以下字段不传代表不更新
  username: "test",
  password: "123456",
  realname: "真实姓名",
  email: "xxx@xxx.com",
  phone: "13888888888",
  gender: "男",
  birth: "1983-10-08",
  type: "user",
  note: "备注",
});

删除用户

sdk.user.remove({
  id: [1, 2, 3], //用户id数组，支持批量删除
});

列出用户

sdk.user.list({
  user: [1, 2],
});

权限管理

添加角色

sdk.role.add({
  name: "管理员",
  code: "ADMIN",
  functions: ["open-camera", "ptz", "delete-user"],
  note: "系统管理员",
});

更新角色

sdk.role.update({
  id: 1, //角色id
  //以下字段不传代表不更新
  name: "物业管理员",
  code: "USER",
  functions: ["open-camera", "ptz"],
  note: "查看摄像机，控制摄像机",
});

删除角色

sdk.role.remove({
  id: [1, 2, 3], //角色id数组，支持批量删除
});

列出角色

sdk.role.list();

通知管理

添加通知

sdk.message.add({
    "title":"通知标题",
    "type":"通知类型",
    "state":"new",//可用['new', 'closed', 'readed', 'replied', 'rejected', 'other']
    "sender":1,//发送者id
    "receiver":1,//接收者id
    "content":{}//消息内容
    "meta":{}//自定义内容
})

接口调用成功后会在 mqtt 队列中推送如下 topic 的消息体

没有具体接收者：
/platform/messages/add
有具体的接收者：
/platform/messages/add/:userId

更新通知

sdk.message.update({
    "id":1//通知id
    "title":"通知标题",
    "type":"通知类型",
    "state":"new",//可用['new', 'closed', 'readed', 'replied', 'rejected', 'other']
    "sender":1,//发送者id
    "receiver":1,//接收者id
    "content":{}//消息内容
    "meta":{}//自定义内容
})

通知被更新成功后会在 mqtt 队列中推送如下 topic 的消息体给发送者

/platform/messages/update/:senderUserId

删除通知

sdk.message.delete({
  id: [1, 2, 3],
});

查询通知

sdk.message.list({
  page: "0", //分页号
  count: 2, //分页数量
  keyword: "新%", //关键词
  sender: [1, 3], //发送者
  receiver: [1, 3], //接收者
  type: ["test"], //类型
  state: ["new", "open", "close", "other"], //状态
  startTime: "2020-07-16 16:00:00",
  endTime: "2033-07-16 16:05:59",
  //自定义扩展查询
  extend: {
    "meta.isDeal.$eq": 1,
  },
});

区域地点管理

获取区域地点类型字典

sdk.location.types();

添加区域地点

sdk.location.add({
  name: "博康正大门",
  type: "出入口",
  code: "123456",
  parentId: null,
});

更新区域地点

sdk.location.update({
  id: 1, //区域地点id
  //以下字段不传则不更新
  name: "博康正大门-出",
  type: "出入口",
  code: "123456",
  parentId: null,
});

删除区域地点

sdk.location.remove({
  id: [1, 2], //id数组，支持批量删除
});

列出区域地点

sdk.location.list({
  type: "tree", //tree表述树级展示，list表示列表展示
});

列出区域地点父级

sdk.location.parent({
  id: 1,
});

列出区域地点子集

sdk.location.child({
  id: 1,
});

组织机构管理

获取组织机构类型字典

sdk.organization.types();

添加组织机构

sdk.organization.add({
  name: "博康研发部",
  type: "部门",
  code: "123456",
  parentId: null,
});

更新组织机构

sdk.organization.update({
  id: 1, //组织机构id
  //以下字段不传则不更新
  name: "人事部",
  type: "部门",
  code: "123456",
  parentId: null,
});

删除组织机构

sdk.organization.remove({
  id: [1, 2], //id数组，支持批量删除
});

列出组织机构

sdk.organization.list({
  type: "tree", //tree表述树级展示，list表示列表展示
});

列出组织机构父级

sdk.organization.parent({
  id: 1,
});

列出组织机构子集

sdk.organization.child({
  id: 1,
});

配置管理

配置管理为 key-value 的结构形式，主要用于保存配置信息，例如网站标题、LOGO、布局、收藏夹等信息，其分为全局配置和个人配置 主要包含两个函数，globa 参数代表是否全局保存，true 表示全局，默认为 false

• 设置配置 sdk.option.set(key,value,global)
• 读取配置 sdk.option.get(key,value,global)

设置全局配置

sdk.option.set("Site-Title", "博康智慧物业管理平台", true);

读取全局配置

sdk.option.get("Site-Title", true).then((res) => {
  console.log(res.data.value);
  //博康智慧物业管理平台
});

设置个人配置

//保存视频收藏夹，key名称根据应用需要自定义，请取个不容易重复的名称，以免与其他app冲突
sdk.option.set("Favorites-Cameras", ["CAM001", "CAM002", "CAM003", "CAM004"]);

读取个人配置

sdk.option.get("Favorites-Cameras");

设备管理

获取设备类型字典

sdk.device.types();

添加设备

sdk.device.add({
  name: "摄像机", //设备名称
  code: "CAMERA000001", //设备编码
  type: "camera", //设备类型(字典请参考项目配置)
  manufactor: "海康", //设备厂家
  model: "D70000", //设备型号
  ip: "192.168.1.1", //ip地址
  port: "37777", //端口
  username: "admin", //设备账号
  password: "123456", //设备密码
  meta: {
    custom1: "自定义字段1",
    custom2: "自定义字段2",
    //此处可以随意增加业务字段
  },
  locationId: 1, //设备所属区域地点id
  organizationId: null, //设备所属组织机构id
  parentId: null, //设备父级设备ID，例如摄像机挂载的dvr
});

获取指定设备详情

sdk.device.get({
  id: 1,
});

更新设备

sdk.device.update({
  id: 1, //设备id

  //以下字段不传表示不更新
  name: "摄像机", //设备名称
  code: "CAMERA000001", //设备编码
  type: "camera", //设备类型(字典请参考项目配置)
  manufactor: "海康", //设备厂家
  model: "D70000", //设备型号
  ip: "192.168.1.1", //ip地址
  port: "37777", //端口
  username: "admin", //设备账号
  password: "123456", //设备密码
  netAddress: "rtsp://admin:123456@192.168.1.1:37777", //设备网络地址
  meta: {
    custom1: "自定义字段1",
    custom2: "自定义字段2",
  },
  locationId: 1, //设备所属区域地点id
  organizationId: null, //设备所属组织机构id
  parentId: null, //设备父级设备ID，例如摄像机挂载的dvr
});

删除设备

sdk.device.remove({
  id: [7, 8, 9], //设备id数组
});

设备列表

sdk.device.list({
  page: "0", //当前页面
  count: 20, //分页数量
  location: [1, 2], //位置id：非必填
  organization: [1, 2], //组织id：非必填
  type: ["摄像机", "dvr"], //设备类型：非必填
  keyword: "设备", //设备名称：非必填，支持模糊查询，%代表通配
});

获取设备对应的父设备

sdk.device.parent({
  id: 1,
});

获取设备对应的子设备

sdk.device.child({
  id: 1,
});

人口管理

获取人口模型字典

sdk.people.types();

添加人口

sdk.people.add({
{
    "type":"jm",//人口模型
    "name":"顾黎峰",//姓名
    "idType":"sfz",//证件类型
    "idNumber":"310111",//证件号码
    "gender":"男",//性别
    "JG":"上海",//籍贯
    "MZ":"汉",//民族
    "meta.custom1":"自定义字段1",
    "meta.custom2":"自定义字段2"
}})

获取指定人口详情

sdk.people.get({
  id: 1,
});

更新人口

sdk.people.update({
  id: 1, //人口id

  type: "jm", //人口模型
  name: "顾黎峰", //姓名
  idType: "sfz", //证件类型
  idNumber: "310111", //证件号码
  gender: "男", //性别
  JG: "上海", //籍贯
  MZ: "汉", //民族
  "meta.custom1": "自定义字段1",
  "meta.custom2": "自定义字段2",
});

删除人口

sdk.people.remove({
  id: [7, 8, 9], //人口id数组
});

人口列表

sdk.people.list({
  page: "0", //当前页面
  count: 20, //分页数量
  type: ["jm", "wm"], //模型类型：非必填
  keyword: "%顾%", //关键词：非必填，支持模糊查询，%代表通配
});

车辆管理

获取车辆模型字典

sdk.car.types();

添加车辆

sdk.car.add({
{
    "type":"jm",//车辆模型
    //待补充
}})

获取指定车辆详情

sdk.car.get({
  id: 1,
});

更新车辆

sdk.car.update({
  id: 1, //人口id
  //待补充
});

删除车辆

sdk.car.remove({
  id: [7, 8, 9], //车辆id数组
});

车辆列表

sdk.car.list({
  page: "0", //当前页面
  count: 20, //分页数量
  type: ["jyc", "jc"], //模型类型：非必填
  keyword: "%沪A%", //关键词：非必填，支持模糊查询，%代表通配
});

报警管理

报警级别字典

sdk.alarm.levels();

报警分类字典

sdk.alarm.types();

添加报警

sdk.alarm.add({
    "name":"xxx报警",//报警名称
    "type":"周界",//报警类型(类型字典请依据项目实际配置)
    "level":1,//报警级别
    "state":"new",//报警当前状态(new,open,close,other)
    "note":"测试报警",//报警描述信息
    "meta":{
        "custom1":"自定义数据1"
        "custom2":"自定义数据2"
    },
    "deviceId":null,//关联的设备ID
    "locationId":1//关联的区域位置ID
})

获取指定报警详情

sdk.alarm.get({
  id: 1,
});

更新报警

sdk.alarm.update({
  state: "close", //消除报警
  //如有其他字段需要改动，可在这里继续增加
  //"level":2, //提升等级
  //"note":"处置完成"
});

也可以给报警增加自定义属性

sdk.alarm.update({
    "state":"open",
    "meta.customProp1":"自定义属性1"
    "meta.customProp2":"自定义属性2"
    //其他...
})

删除报警

sdk.alarm.remove({
  id: [1, 2, 3], //可传入多个id批量删除
});

报警列表

sdk.alarm.list({
  page: "0", //当前分页
  count: 20, //单页数量
  keyword: "%", //关键词：非必填
  startTime: "2021-01-01 00:00:00", //开始时间：非必填
  endTime: "2022-01-01 23:59:59", //结束时间：非必填
  type: ["camera", "smoke"], //报警类型：非必填
  level: ["1", "2"], //报警级别：非必填
  state: ["new", "open", "close", "other"], //状态：非必填
  locationId: [1, 2], //报警地点：非必填
  deviceId: [1, 2], //报警设备：非必填
});

报警处置管理

添加处置记录

上传处置过程(图片，视频，音频，评论)

sdk.alarmHistory.add({
  //报警Id
  alarmId: 1,
  //setMeida表示添加处置媒体内容，setState表示修改报警状态,other表示其他（文字）
  action: "setMedia",
  //media是一个数组，请传入1-n个列表
  media: [
    {
      type: "image",
      address: "xxx.jpg",
    },
    {
      type: "video",
      address: "xxx.mp4",
    },
    {
      type: "voice",
      address: "xxx.mp3",
    },
  ],
  note: "文字评论内容",
});

修改报警状态

sdk.alarmHistory.add({
  //报警Id
  alarmId: 1,
  //setMeida表示添加处置媒体内容，setState表示修改报警状态
  action: "setState",
  //state可选值：["new", "open", "close", "other"]，分别代表：新报警(未处置)，处置中，处置完成，其他
  state: "open",
  note: "文字评论内容",
});

列出报警处置列表

sdk.alarmHistory.get({
  alarmId: 1,
});

API 请求日志管理

日志查询

sdk.log.list({
  page: 0, //当前页面
  count: 20, //分页数量
  startTime: "2021-01-01 00:00:00", //开始时间：非必填
  endTime: "2022-01-01 23:59:59", //结束时间：非必填
  users: [1, 2, 3], //对应用户：非必填
  url: "%", //对应请求url：非必填
});

具体返回如下内容

{
    "code": 0,
    "message": "ok",
    "data": {
        "count": 469,//符合的记录总数
        "rows": [
            {
                "id": 651,
                "method": "POST",
                "url": "/API/alarm/list",
                "status": "200",
                "contentLength": "5.6kb",
                "responseTime": "10ms",
                "remoteIP": "::ffff:127.0.0.1",
                "browser": {
                    "name": "Chrome",
                    "version": "91.0.4472.124",
                    "major": "91"
                },
                "device": {},
                "engine": {
                    "name": "Blink",
                    "version": "91.0.4472.124"
                },
                "os": {
                    "name": "Windows",
                    "version": "10"
                },
                "cpu": {
                    "architecture": "amd64"
                },
                "createdAt": "2021-07-16T02:43:15.390Z",
                "updatedAt": "2021-07-16T02:43:15.390Z",
                "userId": 1,
                "User": {
                    "id": 1,
                    "username": "admin",
                    "realname": "管理员",
                    "email": null,
                    "phone": "88888888888",
                    "gender": null,
                    "birth": null,
                    "type": "user",
                    "note": null,
                    "createdAt": "2021-07-12T07:11:25.363Z",
                    "updatedAt": "2021-07-12T07:11:25.363Z"
                }
            }
        ]
    }
}

获取指定日志详情

sdk.log.get({
  id: 1,
});

用户自定义日志管理

添加日志

sdk.userlog.add({
  type: "open-app", //必填
  appid: "emap-app", //可不传
  //meta为json字段，根据业务需要自行扩展
  meta: {
    test: true,
  },
  userId: 1, //必填
});

更新日志

sdk.userlog.update({
  id: 1, //必填，日志对应id
  type: "open-app", //必填
  appid: "emap-app", //可不传
  //meta为json字段，根据业务需要自行扩展
  meta: {
    test: true,
  },
  userId: 1, //必填
});

删除日志

sdk.userlog.remove({
  id: [1, 2, 3],
});

查询日志

sdk.userlog.list({
  page: 0,
  count: 20,
  type: ["open-app"],
  userId: [1, 4],
  startTime: "2020-07-16 16:00:00",
  endTime: "2033-07-16 16:05:59",
  //自定义扩展字段查询
  extend: {
    "meta.test.$eq": true,
  },
});