diff --git a/README.md b/README.md index baf89da..0e32a02 100644 --- a/README.md +++ b/README.md @@ -1,178 +1,59 @@ -## 星云SDK +# 星云SDK -### 1. 安装 +## 介绍 +星云SDK是一款为开发者打造的智能锁SDK,旨在简化与智能锁与星云平台的交互。通过封装底层操作,使接入者无需关注锁的操作逻辑,能够将更多精力集中在业务开发中。 -在需要引用的项目中执行命令 +星云SDK项目可根据不同的打包命令生成用于不同平台的npm包,目前支持的平台有:uni,web。 -```git -git subtree add --prefix=starCloud git@code.star-lock.cn:StarlockTeam/starcloud-sdk-uniapp.git master -``` +## 文件说明 +- `star-cloud`:星云SDK支持的对外暴露的功能,根据功能模块拆分成多个文件 +- `uni`:星云SDK需要的uniapp平台的底层功能,如请求、缓存等。index.js为uni平台npm包的入口文件,可选择暴露哪些功能到uni平台 +- `web`:星云SDK需要的web平台的底层功能,如请求、缓存等。index.js为web平台npm包的入口文件,可选择暴露哪些功能到web平台 +- `api`: 星云内部接口请求地址 +- `common`: 公共方法 +- `constant`: 常量 +- `env`: 环境配置,打包版本设置 +- `export.js`: 根据不同平台暴露平台支持的功能 +- `format.js`: 格式化数据相关公共方法 +- `log.js`: 不同平台的日志上报方法 +- `obfuscation.js`: 不同平台的混淆打包方法 +- `star-cloud.js`: StarCloud类 -更新 +## 使用方法 +1. 安装npm包 + ```shell + npm install + ``` +2. 打包uni平台npm包 + ```shell + npm run uni-build + ``` + 打包web平台npm包 + ```shell + npm run web-build + ``` +3. 发布npm包 + 进入dist目录,执行npm publish命令 + ```shell + cd dist + npm publish + ``` + 若未登录npm账号,需先登录 + ```shell + npm login + ``` -```git -git subtree pull --prefix=starCloud git@code.star-lock.cn:StarlockTeam/starcloud-sdk-uniapp.git master -``` +## 调试方法 +1. 在测试项目中执行以下命令,将星云SDK项目作为子项目添加到测试项目中,直接调用对应平台的index.js文件中的方法 + ``` + git subtree add --prefix=starCloud git@code.star-lock.cn:StarlockTeam/starcloud-sdk-uniapp.git master + ``` +2. 更新子项目 + ``` + git subtree pull --prefix=starCloud git@code.star-lock.cn:StarlockTeam/starcloud-sdk-uniapp.git master + ``` +3. 推送子项目 + ``` + git subtree push --prefix=starCloud git@code.star-lock.cn:StarlockTeam/starcloud-sdk-uniapp.git master + ``` -推送 - -```git -git subtree push --prefix=starCloud git@code.star-lock.cn:StarlockTeam/starcloud-sdk-uniapp.git master -``` - -### 2. 需安装的npm包 - -`npm install buffer crc js-md5 pinia sm-crypto` - -pinia是全局状态管理工具,需在main.js中引入 - -```javascript -import * as Pinia from 'pinia' - -const store = Pinia.createPinia() -app.use(store) -``` - -### 3. 使用 - -```javascript -import { useStarCloudStore } from '@/starCloud/starCloud' - -const $starCloud = useStarCloudStore() - -/** - * 初始化星云 - * @param params - * @param {String} params.clientId 客户端Id - * @param {String} params.clientSecret 客户端密码 - * @param {String} params.env 环境 - * @param {Boolean} params.isReportLog 是否上报日志 - */ -$starCloud.initStarCloud(params) - -// 注册,后续所有方法调用返回值均为code, data, message -// code对应报错码有三部分组合构成,锁端报错码+星云服务端报错码+自定义报错码 -// Result类定义了所有自定义报错码,具体报错码请查看Result类 -const { code, data, message } = await $starCloud.register() -if (code === Result.Success.code) { - // 逻辑代码 -} else { - // 错误处理 -} - -/** - * 退出登录 - * @param params - * @param {Number} params.uid 用户ID - */ -const { code, data, message } = await $starCloud.logout(params) - -/** - * 选择锁 - * @param params - * @param {AccountInfo} params.accountInfo 账号信息 - * @param {Number} params.lockId 锁ID - * @returns {Promise} - */ -const { code, data, message } = await $starCloud.selectLock(params) - -/** - * 开门 - * @param params - * @param {AccountInfo} params.accountInfo 账号信息 - * @param {String} params.type 开门方式 close: 关门 open: 开门 - * @param {Boolean} params.disconnect 操作后是否断开连接 - * @returns {Promise} - */ -const { code, data, message } = await $starCloud.openDoor(params) - -/** - * 获取离线密码 - * @param params - * @param {AccountInfo} params.accountInfo 账号信息 - * @param {OfflinePassword} params.password 密码信息 - * @returns {Promise} - */ -const data = await $starCloud.getOfflinePassword(params) - -/** - * 自定义密码 - * @param params - * @param {AccountInfo} params.accountInfo 账号信息 - * @param {CustomPassword} params.password 密码信息 - * @param {Boolean} params.disconnect 操作后是否断开连接 - * @returns {Promise} - */ -const data = await $starCloud.customPassword(params) - -/** - * 搜索蓝牙设备 - */ -await $starCloud.searchDevice(searchDevice) -const searchDevice = async result => { -} - -/** - * 停止搜索 - */ -await $starCloud.stopSearchDevice() - -/** - * 绑定设备 - * @param params - * @param {AccountInfo} params.accountInfo 账号信息 - * @param {String} params.name 设备名称 - * @returns {Promise} - */ -const data = await $starCloud.bindDevice(params) - -/** - * 移除坏锁 - * @param params - * @param {AccountInfo} params.accountInfo 账号信息 - * @param {List[int]} params.lockIds 锁Id列表 - * @returns {Promise} - */ -const data = await $starCloud.removeBadLock(params) - -/** - * 删除锁 - * @param params - * @param {AccountInfo} params.accountInfo 账号信息 - */ -const data = await $starCloud.deleteLock(params) - -/** - * 修改管理员密码 - * @param params - * @param {AccountInfo} params.accountInfo 账号信息 - * @param {String} params.adminPwd 管理员密码 - * @param {Boolean} params.disconnect 操作后是否断开连接 - * @returns {Promise} - */ -const data = await $starCloud.updateAdminPassword(params) - -/** - * 同步全部开门记录 - * @param params - * @param {AccountInfo} params.accountInfo 账号信息 - * @param {Boolean} params.disconnect 操作后是否断开连接 - * @returns {Promise} - */ -const data = await $starCloud.syncAllOpenRecord(params) - -/** - * 获取服务器时间 - * @returns {Promise} - */ -const data = await $starCloud.getServerTimestamp() - -/** - * 获取锁支持项 - * @param params - * @param {AccountInfo} params.accountInfo 账号信息 - * @param {Number} params.lockId 锁 Id - * @returns {Promise} - */ -const data = await $starCloud.getLockSupportFeatures(params) -``` diff --git a/obfuscate-uni.js b/obfuscate-uni.js index 3ed9342..c29de8e 100644 --- a/obfuscate-uni.js +++ b/obfuscate-uni.js @@ -2,7 +2,7 @@ import JavaScriptObfuscator from 'javascript-obfuscator' import fs from 'fs' import path from 'path' import ignore from 'ignore' -import { uniVersion } from './env.js' // 导入 webVersion +import { uniVersion } from './env.js' // 获取当前目录和构建目标目录 const sourceDir = path.dirname(new URL(import.meta.url).pathname) diff --git a/obfuscate-web.js b/obfuscate-web.js index 87d6f6d..4318111 100644 --- a/obfuscate-web.js +++ b/obfuscate-web.js @@ -27,7 +27,7 @@ const updatePackageJsonForWeb = () => { const packageJsonPath = path.join(sourceDir, 'package.json') const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8')) - packageJson.name = 'star-cloud-web-1' + packageJson.name = 'star-cloud-web' packageJson.main = './web/index.js' packageJson.version = webVersion diff --git a/package-lock.json b/package-lock.json index 4b2c366..faf6d01 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,13 +1,12 @@ { - "name": "star-cloud", + "name": "star-cloud-web-1", "version": "1.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "star-cloud", + "name": "star-cloud-web-1", "version": "1.0.0", - "license": "ISC", "dependencies": { "buffer": "^6.0.3", "crc": "^4.3.2", @@ -15,6 +14,7 @@ "sm-crypto": "^0.3.13" }, "devDependencies": { + "ignore": "^6.0.2", "javascript-obfuscator": "^4.1.1" } }, @@ -714,6 +714,16 @@ ], "license": "BSD-3-Clause" }, + "node_modules/ignore": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/ignore/-/ignore-6.0.2.tgz", + "integrity": "sha512-InwqeHHN2XpumIkMvpl/DCJVrAHgCsG5+cn1XlnLWGwtZBm8QJfSusItfrwx81CTp5agNZqpKU2J/ccC5nGT4A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 4" + } + }, "node_modules/inherits": { "version": "2.0.4", "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", diff --git a/package.json b/package.json index 5d34df7..49ebc8b 100644 --- a/package.json +++ b/package.json @@ -1,8 +1,8 @@ { - "name": "star-cloud-web-1", + "name": "star-cloud-uni", "version": "1.0.0", "type": "module", - "main": "./web/index.js", + "main": "./uni/index.js", "author": "zzc059", "scripts": { "web-build": "node obfuscate-web.js", @@ -15,6 +15,7 @@ "sm-crypto": "^0.3.13" }, "devDependencies": { + "ignore": "^6.0.2", "javascript-obfuscator": "^4.1.1" } } \ No newline at end of file diff --git a/uni.md b/uni.md index 955baa0..04b8d5b 100644 --- a/uni.md +++ b/uni.md @@ -1,84 +1,579 @@ -## 星云SDK +# 说明 -### 1. 安装 +星云SDK-Uni版是一款专为Uniapp开发者打造的智能锁SDK,旨在简化与智能锁与星云平台的交互。通过封装底层操作,使接入者无需关注锁的操作逻辑,能够将更多精力集中在业务开发中。 + +# 引用 ```git npm install star-cloud-uni ``` -### 2. 使用 +# 公共参数 + +## Result 方法的统一返回结构 ```javascript -import { - init, - Result, - register, - logout, - getOfflinePassword, - removeBadLock, - getLockSupportFeatures, - getServerTimestamp -} from 'star-cloud-uni' - -/** - * 初始化星云 - * @param params - * @param {String} params.clientId 客户端Id - * @param {String} params.clientSecret 客户端密码 - * @param {Array} params.accounts 账号列表,后续方法中需传入uid,若未传入则默认使用第一个账号 - * @param {String} params.env 环境 - */ -init(params) - -/** - * 注册星云 - * @returns Result - */ -const { code, data, message } = await register() +// Result类是所有有返回结果的方法,统一的返回结构,以下接口文档的返回只列出data中的数据结构 +import { Result } from 'star-cloud-web' +// Result.Success中code=0,message='成功',data根据不同方法返回不同数据,默认为{} +const { code, data, message } = Result.Success +// 常用判断方式 if (code === Result.Success.code) { // 逻辑代码 } else { // 错误处理 } - -/** - * 退出登录 - * @param params - * @param {Number} params.uid 用户ID - * @returns Result - */ -const { code, data, message } = await logout(params) - -/** - * 获取离线密码 - * @param params - * @param {Number} [params.uid] 用户ID - * @param {OfflinePassword} params.password 密码信息 - * @returns Result - */ -const data = await getOfflinePassword(params) - -/** - * 移除坏锁 - * @param params - * @param {Number} [params.uid] 用户ID - * @param {List[Number]} params.lockIds 锁Id列表 - * @returns Result - */ -const data = await removeBadLock(params) - -/** - * 获取服务器时间 - * @returns Result - */ -const data = await getServerTimestamp() - -/** - * 获取锁支持项 - * @param params - * @param {Number} [params.uid] 用户ID - * @param {Number} params.lockId 锁 Id - * @returns Result - */ -const data = await getLockSupportFeatures(params) ``` + +| code | 变量名 | 描述(message) | +|------|-------------------------------------------|----------------------------------| +| 0 | Success | 成功 | +| -1 | Fail | 失败 | +| -10 | NotMoreData | 没有更多数据 | +| -20 | NotAvailableBluetooth | 蓝牙尚未打开,请先打开蓝牙 | +| -21 | NotAvailableBluetoothPermission | 小程序蓝牙功能被禁用,请打开小程序蓝牙权限 | +| -22 | NotAvailableWeChatNearbyDevicesPermission | 蓝牙功能需要附近设备权限,请前往设置开启微信的附近设备权限后再试 | +| -23 | NotAvailableWeChatLocationPermission | 蓝牙功能需要定位权限,请前往设置开启微信的定位权限后再试 | +| -24 | NotAvailableWeChatNearbyDevicesEmpty | 蓝牙功能需要定位服务,请前往设置开启定位服务后再试 | +| -25 | NotAvailableWeChatBluetoothPermission | 微信的蓝牙权限被禁用,请前往设置开启微信的蓝牙权限后再试 | +| -30 | DeviceHasBeenReset | 设备已被重置 | +| 251 | ReadyHasPassword | 该密码已存在 | + +## AccountInfo 账号信息 + +| 参数名称 | 数据类型 | 描述 | +|----------|--------|-------| +| uid | Number | 用户uid | +| username | String | 用户名 | +| password | String | 密码 | + +## LockInfo 锁信息 + +| 参数名称 | 数据类型 | 描述 | +|------------------------|-----------------|-----------| +| deviceId | String | 设备 ID | +| serviceId | String | 服务 ID | +| notifyCharacteristicId | String | 通知特征值 ID | +| writeCharacteristicId | String | 写入特征值 ID | +| pwdTimestamp | Number | 密码时间戳(毫秒) | +| featureValue | String | 功能值 | +| featureSettingValue | String | 功能设置值 | +| featureSettingParams | Array.\ | 功能设置参数 | +| lockUserNo | Number | 锁用户编号 | +| lockId | Number | 锁 ID | +| keyId | Number | 钥匙 ID | +| adminPwd | String | 管理密码 | +| bluetooth | Bluetooth | 蓝牙信息 | +| lockConfig | LockConfig | 锁配置信息 | + +## Bluetooth 蓝牙信息 + +| 参数名称 | 数据类型 | 描述 | +|---------------------|-----------------|---------| +| bluetoothDeviceId | String | 蓝牙设备 ID | +| bluetoothDeviceName | String | 蓝牙设备名称 | +| publicKey | Array.\ | 公钥 | +| privateKey | Array.\ | 私钥 | +| signKey | Array.\ | 签名密钥 | + +## LockConfig 锁配置信息 + +| 参数名称 | 数据类型 | 描述 | +|-------------------------|--------|------------| +| vendor | String | 厂商 | +| product | Number | 产品号 | +| model | String | 型号 | +| fwVersion | String | 固件版本 | +| hwVersion | String | 硬件版本 | +| serialNum0 | String | 序列号 0 | +| serialNum1 | String | 序列号 1 | +| btDeviceName | String | 蓝牙设备名称 | +| electricQuantity | Number | 电量 | +| electricQuantityStandby | Number | 备用电量 | +| restoreCount | Number | 重置次数 | +| restoreDate | Number | 重置日期(时间戳秒) | +| icPartNo | String | 芯片型号 | +| indate | Number | 入网日期(时间戳秒) | +| mac | String | MAC 地址 | +| timezoneOffset | Number | 时区偏移(秒) | + +# 初始化 + +## 初始化星云 + +**调用方法** + +```javascript +import { init } from 'star-cloud-web' + +init(params) +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|--------------|----------------------|----|---------------------------------| +| clientId | String | Y | 客户端Id | +| clientSecret | String | Y | 客户端密码 | +| env | String | Y | 环境('SKY':斯凯环境 'XHJ':鑫泓佳环境) | +| accounts | Array\ | Y | 账号列表,后续方法中需传入uid,若未传入则默认使用第一个账号 | +| isReportLog | Boolean | N | 是否上报日志,默认不上报 | + +**返回** +无 + +# 用户 + +## 注册 + +**调用方法** + +```javascript +import { register } from 'star-cloud-web' + +register() +``` + +**入参** +无 + +**返回** + +| 参数名称 | 数据类型 | 描述 | +|----------|--------|-------| +| username | String | 用户名 | +| password | String | 密码 | +| uid | Number | 用户uid | + +## 退出登录 + +**调用方法** + +```javascript +import { logout } from 'star-cloud-web' + +logout(params) +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|------|--------|----|-------| +| uid | Number | Y | 用户uid | + +**返回** +无 + +# 设备 + +## 搜索设备 + +**调用方法** + +```javascript +import { searchDevice } from 'star-cloud-web' + +searchDevice(callback) +const callback = async result => {} +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|----------|----------|----|------------| +| callback | Function | Y | 回调方法,名称自定义 | + +**返回** + +| 参数名称 | 数据类型 | 描述 | +|------|---------------------|------| +| list | Array.\ | 设备列表 | + +DeviceInfo 设备信息 + +| 参数名称 | 数据类型 | 描述 | +|----------------------|------------------|--------------------------------------| +| deviceId | String | 蓝牙设备 id | +| RSSI | Number | 当前蓝牙设备的信号强度,单位 dBm | +| connectable | Boolean | 当前蓝牙设备是否可连接( Android 8.0 以下不支持返回该值 ) | +| advertisData | ArrayBuffer | 当前蓝牙设备的广播数据段中的 ManufacturerData 数据段 | +| advertisServiceUUIDs | Array.\ | 当前蓝牙设备的广播数据段中的 ServiceUUIDs 数据段 | +| localName | String | 当前蓝牙设备的广播数据段中的 LocalName 数据段 | +| name | String | 蓝牙设备名称,某些设备可能没有 | + +## 停止搜索设备 + +**调用方法** + +```javascript +import { stopSearchDevice } from 'star-cloud-web' + +const result = await stopSearchDevice() +``` + +**入参** +无 + +**返回** +无 + +## 绑定设备 + +**调用方法** + +```javascript +import { bindDevice } from 'star-cloud-web' + +bindDevice(params) +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|------|--------|----|-------| +| uid | Number | N | 用户uid | +| name | String | Y | 设备名称 | + +**返回** + +| 参数名称 | 数据类型 | 描述 | +|------|----------|-----| +| lock | LockInfo | 锁信息 | + +# 锁基本功能 + +## 选择锁(对锁进行蓝牙操作前调用) + +**调用方法** + +```javascript +import { selectLock } from 'star-cloud-web' + +selectLock(params) +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|--------|--------|----|-------| +| uid | Number | N | 用户uid | +| lockId | Number | Y | 锁ID | + +**返回** +无 + +## 开关门 + +**调用方法** + +```javascript +import { openDoor } from 'star-cloud-web' + +openDoor(params) +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|------------|---------|----|----------------| +| uid | Number | N | 用户uid | +| type | String | Y | 开门方式 | +| disconnect | Boolean | N | 操作后是否断开连接,默认断开 | + +**返回** +无 + +## 删除锁 + +**调用方法** + +```javascript +import { deleteLock } from 'star-cloud-web' + +deleteLock(params) +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|------|--------|----|-------| +| uid | Number | N | 用户uid | + +**返回** +无 + +## 获取锁支持功能 + +**调用方法** + +```javascript +import { getLockSupportFeatures } from 'star-cloud-web' + +getLockSupportFeatures(params) +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|--------|--------|----|-------| +| uid | Number | N | 用户uid | +| lockId | Number | Y | 锁 Id | + +**返回** + +以下所有功能字段0代表不支持,1代表支持 + +| 参数名称 | 数据类型 | 描述 | +|----------------------------|--------|----------------| +| password | Number | 是否支持密码 | +| icCard | Number | 是否支持 IC 卡 | +| fingerprint | Number | 是否支持指纹 | +| fingerVein | Number | 是否支持指静脉 | +| palmVein | Number | 是否支持掌静脉 | +| d3Face | Number | 是否支持 3D 人脸 | +| qrCode | Number | 是否支持二维码 | +| bluetoothRemoteControl | Number | 是否支持蓝牙遥控器 | +| wirelessKey | Number | 是否支持无线钥匙 | +| gatewayUnlock | Number | 是否支持网关开锁 | +| lockCommand | Number | 是否支持闭锁指令 | +| firmwareUpgrade | Number | 是否支持固件升级设置指令 | +| passwordIssue | Number | 是否支持密码下发 | +| cardIssue | Number | 是否支持卡片下发 | +| fingerprintIssue | Number | 是否支持指纹下发 | +| fingerVeinIssue | Number | 是否支持指静脉下发 | +| palmVeinIssue | Number | 是否支持掌静脉下发 | +| d3FaceIssue | Number | 是否支持 3D 人脸下发 | +| lockFreeze | Number | 是否支持冻结/解冻锁 | +| readAdminPassword | Number | 是否支持读取管理员密码 | +| passwordManagement | Number | 是否支持密码管理功能 | +| passwordWithDelete | Number | 是否支持密码带删除功能 | +| remoteUnlock | Number | 是否支持配置远程开锁 | +| autoLock | Number | 是否支持自动闭锁设置 | +| antiPrySwitch | Number | 是否支持防撬开关配置 | +| resetSwitch | Number | 是否支持重置键配置 | +| lockSwitch | Number | 是否支持反锁功能配置 | +| lockSound | Number | 是否支持语音提示管理 | +| languageSetting | Number | 是否支持语言设置 | +| realTimeClock | Number | 是否支持实时时钟 | +| wifi | Number | 是否支持 WIFI | +| videoIntercom | Number | 是否支持可视对讲 | +| cyclePassword | Number | 是否支持循环密码 | +| cycleFingerprintCard | Number | 是否支持循环指纹/卡 | +| doubleAuthentication | Number | 是否支持双重认证 | +| openDirection | Number | 是否支持开门方向设置 | +| proximitySensing | Number | 是否支持接近感应 | +| doorStatus | Number | 是否支持门磁状态 | +| wiredDoorMagnet | Number | 是否支持有线门磁 | +| wirelessDoorMagnet | Number | 是否支持无线门磁 | +| doorNotClosedAlarm | Number | 是否支持门未关报警 | +| unlockReminder | Number | 是否支持开锁提醒 | +| wirelessKeyboard | Number | 是否支持无线键盘 | +| lightingTime | Number | 是否支持照明灯时间配置 | +| passageMode | Number | 是否支持常开模式 | +| hotelLockCardSystem | Number | 是否支持酒店锁卡系统 | +| appUnlockOnline | Number | 是否支持 APP 开锁需联网 | +| bluetoothBroadcast | Number | 是否支持蓝牙广播 | +| attendance | Number | 是否支持考勤 | +| motorTorsion | Number | 是否支持电机扭力 | +| stayWarn | Number | 是否支持逗留警告 | +| abnormalWarn | Number | 是否支持异常警告 | +| isSupportIris | Number | 是否支持虹膜识别 | +| isSupportCatEye | Number | 是否支持猫眼 | +| deviceEnMultiLanguage | Number | 是否支持设备支持的多国语言 | +| isNoSupportedBlueBroadcast | Number | 是否不支持蓝牙广播 | +| isSupportAutoLight | Number | 是否支持自动亮屏 | +| isSupportBackupBattery | Number | 是否支持备用电池 | +| isSupportForcedOpen | Number | 是否支持胁迫开门 | +| isSupportOpen | Number | 是否支持开门器开锁 | +| isSupportPush | Number | 是否支持推送 | +| offlinePasswordEncryption | Number | 是否支持密码算法 | +| offlinePasswordNumMax | Number | 是否支持离线密码最大个数 | + +# 密码 + +## 获取离线密码 + +**调用方法** + +```javascript +import { getOfflinePassword } from 'star-cloud-web' + +getOfflinePassword(params) +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|----------|-----------------|----|-------| +| uid | Number | N | 用户uid | +| password | OfflinePassword | Y | 密码信息 | + +OfflinePassword 密码信息 + +| 属性 | 数据类型 | 必须 | 描述 | +|-----------------|--------|----|--------------------| +| lockId | Number | Y | 锁 Id | +| keyboardPwdName | String | Y | 密码名称 | +| keyboardPwdType | Number | Y | 密码类型 | +| isCoerced | Number | Y | 是否胁迫模式 1:胁迫 2:非胁迫 | +| startDate | Number | Y | 开始日期时间戳(毫秒,永久默认为0) | +| endDate | Number | Y | 结束日期时间戳(毫秒,永久默认为0) | +| hoursStart | Number | Y | 开始时间(小时, 不需要时传0) | +| hoursEnd | Number | Y | 结束时间(小时, 不需要时传0) | + +keyboardPwdType 密码类型 + +| 状态 | 状态说明 | +|----|-------| +| 1 | 单次 | +| 2 | 永久 | +| 3 | 限时 | +| 4 | 删除 | +| 5 | 周末循环 | +| 6 | 每日循环 | +| 7 | 工作日循环 | +| 8 | 周一循环 | +| 9 | 周二循环 | +| 10 | 周三循环 | +| 11 | 周四循环 | +| 12 | 周五循环 | +| 13 | 周六循环 | +| 14 | 周天循环 | + +**返回** + +| 属性 | 数据类型 | 描述 | +|-------------------|--------|-----------------------| +| keyboardPwd | Number | 密码 | +| keyboardPwdId | Number | 密码ID | +| keyboardPwdStatus | Number | 密码状态 1:正常 2:已过期 3:待生效 | + +## 修改超级管理员密码 + +**调用方法** + +```javascript +import { updateAdminPassword } from 'star-cloud-web' + +updateAdminPassword(params) +``` + +**入参** + +| 属性 | 数据类型 | 必须 | 描述 | +|------------|---------|----|----------------| +| uid | Number | N | 用户uid | +| adminPwd | String | Y | 管理员密码 | +| disconnect | Boolean | N | 操作后是否断开连接,默认断开 | + +**返回** +无 + +## 操作自定义密码 + +**调用方法** + +```javascript +import { customPassword } from 'star-cloud-web' + +customPassword(params) +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|------------|----------------|----|----------------| +| uid | Number | N | 用户uid | +| password | CustomPassword | Y | 密码信息 | +| disconnect | Boolean | N | 操作后是否断开连接,默认断开 | + +CustomPassword password 密码信息 + +| 属性 | 数据类型 | 必须 | 描述 | +|-----------------|--------|----|---------------------------------| +| keyboardPwdName | String | Y | 密码名称 | +| keyboardPwdId | Number | N | 密码Id(创建无需传) | +| keyboardPwdType | Number | Y | 密码类型:2:永久 3:限期 | +| keyboardPwd | String | Y | 密码 | +| addType | Number | Y | 添加方式 1:应用 2:网关 | +| isCoerced | Number | Y | 是否是胁迫密码,1:是 2:否 | +| startDate | Number | Y | 起始时间(毫秒) | +| endDate | Number | Y | 结束时间(毫秒) | +| operate | Number | Y | 操作 0:注册 1:修改 2:删除自定义密码 3:删除离线密码 | +| pwdRight | Number | Y | 是否是管理员密码 0:不是 1:是 | +| pwdNo | Number | N | 密码编号(创建无需传) | +| lockId | Number | Y | 锁Id | + +**返回** + +operate=0时返回 + +| 属性 | 数据类型 | 描述 | +|-------------------|--------|-----------------------| +| keyboardPwdId | Number | 密码Id | +| keyboardPwdStatus | Number | 密码状态 1:正常 2:已过期 3:待生效 | +| keyboardPwd | String | 密码 | +| pwdNo | Number | 密码编号 | + +# 记录 + +## 同步开门记录 + +**调用方法** + +```javascript +import { syncOpenDoorRecord } from 'star-cloud-web' + +syncOpenDoorRecord(params) +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|------------|---------|----|----------------| +| uid | Number | N | 用户uid | +| disconnect | Boolean | N | 操作后是否断开连接,默认断开 | + +**返回** +无 + +# 其他 + +## 获取服务器时间 + +**调用方法** + +```javascript +import { getServerTime } from 'star-cloud-web' + +getServerTime() +``` + +**入参** +无 + +**返回** + +| 参数名称 | 数据类型 | 描述 | +|------|--------|---------| +| date | Number | 时间戳(毫秒) | + +## 移除坏锁 + +**调用方法** + +```javascript +import { removeBadLock } from 'star-cloud-web' + +removeBadLock(params) +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|---------|----------------|----|-------| +| uid | Number | N | 用户uid | +| lockIds | Array. | Y | 锁Id列表 | + +**返回** +无 diff --git a/web.md b/web.md index 11309d9..7098a33 100644 --- a/web.md +++ b/web.md @@ -1,84 +1,305 @@ -## 星云SDK +# 说明 -### 1. 安装 +星云SDK-Web版是一款专为web开发者打造的智能锁SDK,旨在简化与智能锁与星云平台的交互。通过封装底层操作,使接入者无需关注锁的操作逻辑,能够将更多精力集中在业务开发中。 + +# 引用 ```git npm install star-cloud-web ``` -### 2. 使用 +# 公共参数 + +## Result 方法的统一返回结构 ```javascript -import { - init, - Result, - register, - logout, - getOfflinePassword, - removeBadLock, - getLockSupportFeatures, - getServerTimestamp -} from 'star-cloud-web' - -/** - * 初始化星云 - * @param params - * @param {String} params.clientId 客户端Id - * @param {String} params.clientSecret 客户端密码 - * @param {Array} params.accounts 账号列表,后续方法中需传入uid,若未传入则默认使用第一个账号 - * @param {String} params.env 环境 - */ -init(params) - -/** - * 注册星云 - * @returns Result - */ -const { code, data, message } = await register() +// Result类是所有有返回结果的方法,统一的返回结构,以下接口文档的返回只列出data中的数据结构 +import { Result } from 'star-cloud-web' +// Result.Success中code=0,message='成功',data根据不同方法返回不同数据,默认为{} +const { code, data, message } = Result.Success +// 常用判断方式 if (code === Result.Success.code) { // 逻辑代码 } else { // 错误处理 } - -/** - * 退出登录 - * @param params - * @param {Number} params.uid 用户ID - * @returns Result - */ -const { code, data, message } = await logout(params) - -/** - * 获取离线密码 - * @param params - * @param {Number} [params.uid] 用户ID - * @param {OfflinePassword} params.password 密码信息 - * @returns Result - */ -const data = await getOfflinePassword(params) - -/** - * 移除坏锁 - * @param params - * @param {Number} [params.uid] 用户ID - * @param {List[Number]} params.lockIds 锁Id列表 - * @returns Result - */ -const data = await removeBadLock(params) - -/** - * 获取服务器时间 - * @returns Result - */ -const data = await getServerTimestamp() - -/** - * 获取锁支持项 - * @param params - * @param {Number} [params.uid] 用户ID - * @param {Number} params.lockId 锁 Id - * @returns Result - */ -const data = await getLockSupportFeatures(params) ``` + +| code | 变量名 | 描述(message) | +|------|-------------------------------------------|----------------------------------| +| 0 | Success | 成功 | +| -1 | Fail | 失败 | +| -10 | NotMoreData | 没有更多数据 | +| -20 | NotAvailableBluetooth | 蓝牙尚未打开,请先打开蓝牙 | +| -21 | NotAvailableBluetoothPermission | 小程序蓝牙功能被禁用,请打开小程序蓝牙权限 | +| -22 | NotAvailableWeChatNearbyDevicesPermission | 蓝牙功能需要附近设备权限,请前往设置开启微信的附近设备权限后再试 | +| -23 | NotAvailableWeChatLocationPermission | 蓝牙功能需要定位权限,请前往设置开启微信的定位权限后再试 | +| -24 | NotAvailableWeChatNearbyDevicesEmpty | 蓝牙功能需要定位服务,请前往设置开启定位服务后再试 | +| -25 | NotAvailableWeChatBluetoothPermission | 微信的蓝牙权限被禁用,请前往设置开启微信的蓝牙权限后再试 | +| -30 | DeviceHasBeenReset | 设备已被重置 | +| 251 | ReadyHasPassword | 该密码已存在 | + + +## AccountInfo 账号信息 + +| 参数名称 | 数据类型 | 描述 | +|----------|--------|-------| +| uid | Number | 用户uid | +| username | String | 用户名 | +| password | String | 密码 | + +# 初始化 + +## 初始化星云 + +**调用方法** + +```javascript +import { init } from 'star-cloud-web' + +init(params) +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|--------------|----------------------|----|---------------------------------| +| clientId | String | Y | 客户端Id | +| clientSecret | String | Y | 客户端密码 | +| env | String | Y | 环境('SKY':斯凯环境 'XHJ':鑫泓佳环境) | +| accounts | Array\ | Y | 账号列表,后续方法中需传入uid,若未传入则默认使用第一个账号 | + +**返回** +无 + +# 用户 + +## 注册 + +**调用方法** + +```javascript +import { register } from 'star-cloud-web' + +register() +``` + +**入参** +无 + +**返回** + +| 参数名称 | 数据类型 | 描述 | +|----------|--------|-------| +| username | String | 用户名 | +| password | String | 密码 | +| uid | Number | 用户uid | + +## 退出登录 + +**调用方法** + +```javascript +import { logout } from 'star-cloud-web' + +logout(params) +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|------|--------|----|-------| +| uid | Number | Y | 用户uid | + +**返回** +无 + +# 锁基本功能 + +## 获取锁支持功能 + +**调用方法** + +```javascript +import { getLockSupportFeatures } from 'star-cloud-web' + +getLockSupportFeatures(params) +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|--------|--------|----|-------| +| uid | Number | N | 用户uid | +| lockId | Number | Y | 锁 Id | + +**返回** + +以下所有功能字段0代表不支持,1代表支持 + +| 参数名称 | 数据类型 | 描述 | +|----------------------------|--------|----------------| +| password | Number | 是否支持密码 | +| icCard | Number | 是否支持 IC 卡 | +| fingerprint | Number | 是否支持指纹 | +| fingerVein | Number | 是否支持指静脉 | +| palmVein | Number | 是否支持掌静脉 | +| d3Face | Number | 是否支持 3D 人脸 | +| qrCode | Number | 是否支持二维码 | +| bluetoothRemoteControl | Number | 是否支持蓝牙遥控器 | +| wirelessKey | Number | 是否支持无线钥匙 | +| gatewayUnlock | Number | 是否支持网关开锁 | +| lockCommand | Number | 是否支持闭锁指令 | +| firmwareUpgrade | Number | 是否支持固件升级设置指令 | +| passwordIssue | Number | 是否支持密码下发 | +| cardIssue | Number | 是否支持卡片下发 | +| fingerprintIssue | Number | 是否支持指纹下发 | +| fingerVeinIssue | Number | 是否支持指静脉下发 | +| palmVeinIssue | Number | 是否支持掌静脉下发 | +| d3FaceIssue | Number | 是否支持 3D 人脸下发 | +| lockFreeze | Number | 是否支持冻结/解冻锁 | +| readAdminPassword | Number | 是否支持读取管理员密码 | +| passwordManagement | Number | 是否支持密码管理功能 | +| passwordWithDelete | Number | 是否支持密码带删除功能 | +| remoteUnlock | Number | 是否支持配置远程开锁 | +| autoLock | Number | 是否支持自动闭锁设置 | +| antiPrySwitch | Number | 是否支持防撬开关配置 | +| resetSwitch | Number | 是否支持重置键配置 | +| lockSwitch | Number | 是否支持反锁功能配置 | +| lockSound | Number | 是否支持语音提示管理 | +| languageSetting | Number | 是否支持语言设置 | +| realTimeClock | Number | 是否支持实时时钟 | +| wifi | Number | 是否支持 WIFI | +| videoIntercom | Number | 是否支持可视对讲 | +| cyclePassword | Number | 是否支持循环密码 | +| cycleFingerprintCard | Number | 是否支持循环指纹/卡 | +| doubleAuthentication | Number | 是否支持双重认证 | +| openDirection | Number | 是否支持开门方向设置 | +| proximitySensing | Number | 是否支持接近感应 | +| doorStatus | Number | 是否支持门磁状态 | +| wiredDoorMagnet | Number | 是否支持有线门磁 | +| wirelessDoorMagnet | Number | 是否支持无线门磁 | +| doorNotClosedAlarm | Number | 是否支持门未关报警 | +| unlockReminder | Number | 是否支持开锁提醒 | +| wirelessKeyboard | Number | 是否支持无线键盘 | +| lightingTime | Number | 是否支持照明灯时间配置 | +| passageMode | Number | 是否支持常开模式 | +| hotelLockCardSystem | Number | 是否支持酒店锁卡系统 | +| appUnlockOnline | Number | 是否支持 APP 开锁需联网 | +| bluetoothBroadcast | Number | 是否支持蓝牙广播 | +| attendance | Number | 是否支持考勤 | +| motorTorsion | Number | 是否支持电机扭力 | +| stayWarn | Number | 是否支持逗留警告 | +| abnormalWarn | Number | 是否支持异常警告 | +| isSupportIris | Number | 是否支持虹膜识别 | +| isSupportCatEye | Number | 是否支持猫眼 | +| deviceEnMultiLanguage | Number | 是否支持设备支持的多国语言 | +| isNoSupportedBlueBroadcast | Number | 是否不支持蓝牙广播 | +| isSupportAutoLight | Number | 是否支持自动亮屏 | +| isSupportBackupBattery | Number | 是否支持备用电池 | +| isSupportForcedOpen | Number | 是否支持胁迫开门 | +| isSupportOpen | Number | 是否支持开门器开锁 | +| isSupportPush | Number | 是否支持推送 | +| offlinePasswordEncryption | Number | 是否支持密码算法 | +| offlinePasswordNumMax | Number | 是否支持离线密码最大个数 | + +# 密码 + +## 获取离线密码 + +**调用方法** + +```javascript +import { getOfflinePassword } from 'star-cloud-web' + +getOfflinePassword(params) +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|----------|-----------------|----|-------| +| uid | Number | N | 用户uid | +| password | OfflinePassword | Y | 密码信息 | + +OfflinePassword 密码信息 + +| 属性 | 数据类型 | 必须 | 描述 | +|-----------------|--------|----|--------------------| +| lockId | Number | Y | 锁 Id | +| keyboardPwdName | String | Y | 密码名称 | +| keyboardPwdType | Number | Y | 密码类型 | +| isCoerced | Number | Y | 是否胁迫模式 1:胁迫 2:非胁迫 | +| startDate | Number | Y | 开始日期时间戳(毫秒,永久默认为0) | +| endDate | Number | Y | 结束日期时间戳(毫秒,永久默认为0) | +| hoursStart | Number | Y | 开始时间(小时, 不需要时传0) | +| hoursEnd | Number | Y | 结束时间(小时, 不需要时传0) | + +keyboardPwdType 密码类型 + +| 状态 | 状态说明 | +|----|-------| +| 1 | 单次 | +| 2 | 永久 | +| 3 | 限时 | +| 4 | 删除 | +| 5 | 周末循环 | +| 6 | 每日循环 | +| 7 | 工作日循环 | +| 8 | 周一循环 | +| 9 | 周二循环 | +| 10 | 周三循环 | +| 11 | 周四循环 | +| 12 | 周五循环 | +| 13 | 周六循环 | +| 14 | 周天循环 | + +**返回** + +| 属性 | 数据类型 | 描述 | +|-------------------|--------|-----------------------| +| keyboardPwd | Number | 密码 | +| keyboardPwdId | Number | 密码ID | +| keyboardPwdStatus | Number | 密码状态 1:正常 2:已过期 3:待生效 | + + +# 其他 + +## 获取服务器时间 + +**调用方法** + +```javascript +import { getServerTime } from 'star-cloud-web' + +getServerTime() +``` + +**入参** +无 + +**返回** + +| 参数名称 | 数据类型 | 描述 | +|------|--------|---------| +| date | Number | 时间戳(毫秒) | + +## 移除坏锁 + +**调用方法** + +```javascript +import { removeBadLock } from 'star-cloud-web' + +removeBadLock(params) +``` + +**入参** + +| 参数名称 | 数据类型 | 必须 | 描述 | +|---------|----------------|----|-------| +| uid | Number | N | 用户uid | +| lockIds | Array. | Y | 锁Id列表 | + +**返回** +无