# CloudDocument

**Repository Path**: jimmynokia/CloudDocument

## Basic Information

- **Project Name**: CloudDocument
- **Description**: 描述云端与小程序接口文档
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2018-02-02
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

描述云端与小程序接口文档
====




|目录|函数名|函数用途描述|完成计划|
|:--|:--|:--|:--|
|1|login|用户登录，每次获取OPENID后调用|Done|
|2|borrow|用户开始借用设备接口|Done|
|3|creditpay|微信小程序支付统一下单接口|Done|
|4|locationquery|查询设备具体位置|Done|
|5|CreditCharge|余额充值接口|Done|
|6|DepositCharge|押金充值接口|Done|
|7|dockerreturn|用户设备归还|Done|
|8|CreditCheck|帐户余额查询|Done|
|9|depositpay|押金支付|？|
|10|findneardocker|附近的机柜|？|
|11|DeviceQuery|用户在借设备查询|Done|
|12|getdealinfo|优惠信息|TBD|
|13|HistoryDevice|查询用户的计费记录|Done|


![目前可用柜子二维码 2018-06-09](https://gitee.com/uploads/images/2018/0609/203445_7a0e67f5_1165280.png "Docker-31117571.png")


* appid: wxe0245765f6bf147c
* 腾讯地图key: WQLBZ-WILCJ-ZIYF2-KWDZY-CJUEQ-3TFHJ

####  Login

||||
|:--|:--|:--|
|函数名|Login| **确保每次获取用户小程序后都调用该接口** |
|输入参数|openid|从用户帐号获取的用户openid， 通过网络参数req.query.openid传入，以下类似|
|输入参数|UnionID|从用户帐号获取的用户UnionID|
|返回参数|res.data|'ok'|
|接口地址|https://www.xuburenlongjohnson.xyz/login||


详细行为定义：

    登录时携带用户openid和UnionID。确保小程序在每次获取用户openid后都调用该接口。


####  nicknameupdate

||||
|:--|:--|:--|
|函数名|nicknameupdate| **确保每次获取用户小程序后都调用该接口** |
|输入参数|openid|从用户帐号获取的用户openid|
|输入参数|nickname|从用户帐号获取的用户昵称|
|返回参数|成功|'ok'|
|接口地址|https://www.xuburenlongjohnson.xyz/wxlogin/nicknameupdate||



####  DeviceQuery

||||
|:--|:--|:--|
|函数名|DeviceQuery||
|输入参数|openid|从用户帐号获取的用户openid， 通过网络参数req.query.openid传入，以下类似|
|返回参数|见下文||
|返回参数|res.data|array对象|
|返回参数|res.data[x].StartTime|借用时间|
|返回参数|res.data[x].DeviceID|设备号（不需要展示给用户，后台绑定，用于查询历史位置）|
|返回参数|res.data[x].cost|单次服务计费|
|接口地址|https://www.xuburenlongjohnson.xyz/deviceinuse||


详细行为定义：

    登录时携带用户openid和手机号码信息

        若用户名下无设备，返回ErrorCode = 0;
        若用户名下有设备，返回设备Device ID list，最近十个设备;


ErrCode 详细定义见错误定义表格 3

####  HistoryDevice

||||
|:--|:--|:--|
|函数名|HistoryDevice||
|输入参数|openid|从用户帐号获取的用户openid|
|返回参数|见下文||
|返回参数|res.data|array对象|
|返回参数|res.data[x].cost|单次服务计费|
|返回参数|res.data[x].StartTime|借用时间|
|返回参数|res.data[x].EndTime|归还时间|
|接口地址|https://www.xuburenlongjohnson.xyz/historydevice||


详细行为定义：

   用户发送openid
   若用户名下有已归还的设备，返回设备Device ID list，最近十个设备;




####  Borrow

||||
|:--|:--|:--|
|函数名|borrow||
|输入参数|openid||
|输入参数|dockerid|用户扫描二维码得到的设备柜号(注意全小写）|
|输入参数|CellPhone|用户手机号|
|输入参数|openid|用户openid|
|返回参数|res.data.ErrorCode|错误代码，8 为正常|
|返回参数|res.data.DeviceID|成功借用的设备ID，用于查询位置和归还|
|返回参数|见下文||
|接口地址|https://www.xuburenlongjohnson.xyz/borrowtest||

    功能介绍：开始借用设备
    详细行为定义：
1	获取用户的OpenID，Docker的DockerID。

2	判断用户权限（余额是否充足）
如果权限通过，进行3，否则返回错误ErrorCode = 1 
向柜子发送借用请求

获取返回值：
    待借设备DeviceID号

如果无可用设备：通知小程序无设备
ErrorCode = 6

3	在云端进行权限绑定。

4	向微信小程序发送确认消息, deviceid

![输入图片说明](https://gitee.com/uploads/images/2018/0208/105846_b5656970_1165280.png "借用设备.png")

#### CreditPay

功能介绍：微信小程序支付统一下单接口

详细行为定义：
微信小程序模板，传入参数

||||
|:--|:--|:--|
|函数名|creditpay||
|输入参数|price||
|输入参数|openid||
|输入参数|chargetype|0为余额，1为押金|
|返回参数|res.data.timestamp|微信支付返回的标准参数：时间戳|
|返回参数|res.data.nonceStr|微信支付返回的标准参数：随机检验字符串|
|返回参数|res.data.package|微信支付返回的标准参数：|
|返回参数|res.data.paySign|微信支付返回的标准参数：签名|
|接口地址|https://www.xuburenlongjohnson.xyz/p1/ordergenerate||



#### locationquery:

功能介绍：查询用户位置

||||
|:--|:--|:--|
|函数名|locationquery||
|输入参数|openid|用户的openid|
|输入参数|deviceid|用户名下的设备号|
|返回参数|lat|经度|
|返回参数|lon|纬度|
|返回参数|CSQ|信号质量，从1到32，最优为32，可根据信号显示格数图形，5格或者四格都可|
|返回参数|Battery|电池余量，从0到100，显示为电池图标|
|返回参数|temp |设备温度，单位为摄氏度|


|接口地址|https://www.xuburenlongjohnson.xyz/locationquery||


详细行为定义：

    data = [OpenID , DeviceID]
    首先查询OpenID和DeviceID的匹配关系，
    若找不到设备，返回ErrorCode 2
    若找到设备，但用户权限已过期，则返回ErrorCode 1.
    查询DEVICE ID在OPENID下在权限。
        若权限过期，则返回ErrorCode = 1;
        若权限成功，则返回DEVICE ID在OPENID下的最近十次（最多）记录。
    返回格式为jason列表：[loc:[[lat1,gat1],[lat2,gat2]…];

####	getcoupon
功能介绍：获取优惠券
||||
|:--|:--|:--|
|函数名|getcoupon||
|输入参数|openid|用户的openid|
|返回参数|coupon|优惠券编号|
|返回参数|value|优惠券面值|
|接口地址|https://www.xuburenlongjohnson.xyz/getcoupon||

本接口只返回用户未使用的优惠券，如果用户已经使用过，不会返回有效的优惠券。

####	couponquery
功能介绍：获取优惠券
||||
|:--|:--|:--|
|函数名|couponquery||
|输入参数|openid|用户的openid|
|返回参数|coupon|优惠券编号|
|返回参数|value|优惠券面值|
|接口地址|https://www.xuburenlongjohnson.xyz/couponquery||

####	usermodeupdate
功能介绍：获取优惠券

||||
|:--|:--|:--|
|函数名|getcoupon||
|输入参数|openid|用户的openid|
|输入参数|deviceid|用户的设备id|
|输入参数|usermode|用户模式选择，０为自动，１为随身，２为游客，３为wlakie，４为包裹，５商旅|
|输入参数|fencecenterlat|电子围栏的经度, |
|输入参数|fencecenterlon|电子围栏的纬度|
|输入参数|fencerad1|电子围栏的半径|
|输入参数|fencerad2|电子围栏的半径|
|输入参数|boxalarm|开箱检测开关|
|输入参数|boxsensitivity|开箱检测灵敏度|
|输入参数|proximityenable|迫近开关|
|输入参数|proximitybeep|双向模式开关|
|输入参数|proximitydistance|迫近模式检测距离|
|输入参数|connectgprs|连接方式：ＧＰＲＳ开关|
|输入参数|connectblue|连接方式：蓝牙开关|
|输入参数|connectlora|连接方式：lora|
|接口地址|https://www.xuburenlongjohnson.xyz/usermodeupdate||

一共有五种接口：
用户模式，包括参数usermode
电子围栏，包括参数fencecenterlat，fencecenterlon,fencerad1,fencerad2,注意这里为了将来接口，有两个半径，在目前情况下只用第一个，但第二个参数必须携带
开箱检测,包括参数boxalarm，boxsensitivity
迫近，包括参数proximityenable，proximitybeep，proximitydistance
连接方式，包括参数connectgprs，connectblue，connectlora
每次只能更新一种接口，每个接口下的所有参数必须带全，否则会出错。



####	usermodeget
功能介绍：获取优惠券

||||
|:--|:--|:--|
|函数名|getcoupon||
|输入参数|openid|用户的openid|
|输入参数|deviceid|用户的设备id|
|返回参数|usermode|用户模式选择，０为自动，１为随身，２为游客，３为wlakie，４为包裹，５商旅|
|返回参数|fencecenterlat|电子围栏的经度|
|返回参数|fencecenterlon|电子围栏的纬度|
|返回参数|fencerad1|电子围栏的半径|
|返回参数|boxalarm|开箱检测开关|
|返回参数|boxsensitivity|开箱检测灵敏度|
|返回参数|proximityenable|迫近开关|
|返回参数|proximitybeep|双向模式开关|
|返回参数|proximitydistance|迫近模式检测距离|
|返回参数|connectgprs|连接方式：ＧＰＲＳ开关|
|返回参数|connectblue|连接方式：蓝牙开关|
|返回参数|connectlora|连接方式：lora|
|接口地址|https://www.xuburenlongjohnson.xyz/usermodeget||







####	DockerReturn
功能介绍：用户设备归还

||||
|:--|:--|:--|
|函数名|DockerReturn||
|输入参数|openid|用户的openid|
|输入参数|deviceid|用户名下的设备号|
|输入参数|coupon|抵用券号码|
|输入参数|DockerID|用户的希望归还的机柜号，通过二维码扫描得到|
|返回参数|cost|用户本次消费量，单位暂定为小时|
|返回参数|credit|用户余额，单位暂定为元|
|接口地址|https://www.xuburenlongjohnson.xyz/dockerreturntest||


![输入图片说明](https://gitee.com/uploads/images/2018/0302/172430_491e4bf3_1165280.png "DockerReturn.png")

详细行为定义：
输入参数：用户微信openid，DockerID，设备ID


#### creditcheck:
功能介绍：查询用户帐户余额

||||
|:--|:--|:--|
|函数名|creditcheck||
|输入参数|openid|用户的openid|
|返回参数|credit|用户余额，单位暂定为元|
|接口地址|https://www.xuburenlongjohnson.xyz/creditcheck||

#### getopenid:
功能介绍：查询用户设备列表

||||
|:--|:--|:--|
|函数名|creditcheck||
|输入参数|openid|用户的openid|
|返回参数|res.data.name|devicelist|
|返回参数|res.data.devicenum|设备数量|
|返回参数|res.data[x]|x从0开始，代表每个设备的deviceid|
|接口地址|https://www.xuburenlongjohnson.xyz/getopenid||

#### CreditCharge:
功能介绍：用户余额充值

||||
|:--|:--|:--|
|函数名|CreditCharge||
|输入参数|openid|用户的openid|
|输入参数|chargetype|0:充值，1：押金|
|输入参数|chargefee|用户充值额度，单位为分（目前在测试阶段无论充多少只扣一分钱）|
|返回参数|res.data[x]|x从0开始，代表每个设备的deviceid|
|接口地址|https://www.xuburenlongjohnson.xyz/oredergenerate||



#### BillCheck:
功能介绍：查询用户计费列表

||||
|:--|:--|:--|
|函数名|BillCheck||
|输入参数|openid|用户的openid|
|返回参数|res.data.time|计费时间|
|返回参数|res.data.cost|单次计费数目|
|返回参数|res.data.device|计费设备|
|接口地址|https://www.xuburenlongjohnson.xyz/paylistcheck||

#### CreditCheck:
功能介绍：查询用户计费列表

||||
|:--|:--|:--|
|函数名|CreditCheck||
|输入参数|openid|用户的openid|
|返回参数|res.data.credit|帐户余额|
|接口地址|https://www.xuburenlongjohnson.xyz/creditcheck||

#### user transfer :
功能介绍：帐户转移

||||
|:--|:--|:--|
|函数名|usertransfer||
|输入参数|openid_master|待转用户的openid|
|输入参数|openid_slave|被转用户的openid|
|输入参数|deviceid|用户的unicode|
|输入参数|ShareType|帐户转移类型，3为共享，1 为转移 |
|返回参数|ErrCode|错误代码|
|接口地址|https://www.xuburenlongjohnson.xyz/feature1/acceptshare||

在迁移帐户这个逻辑中，一个用户有权限把自己的设备分享给自己的微信好友。
迁移分为共享和转移， 共享的用户只能看到设备的一些基本信息，但是无法归还。
转移的用户替换了原来的用户的一切权利，可以归还，并且付费。

需要准备的数据包括双方的openid和待转的设备号，这里的关键是待分享的用户OPENID如何获取。
由于小程序的限制，这里建议使用转发功能，用户把自己的openid和设备号转发给待转用户。
待转用户获取后，再汇合自己的OPENID一起发给服务器。




#### Device command :
功能介绍：向设备发送远程命令

用来向设备发送命令，目前的主要命令是改变上报频率， 自检。


||||
|:--|:--|:--|
|函数名|devicedcmd||
|输入参数|openid|用户的openid|
|输入参数|deviceid|用户的deviceid|
|输入参数|cmds|待发送的命令，字符串形式|
|返回参数|ErrCode|错误代码|
|接口地址|https://www.xuburenlongjohnson.xyz/devicecmd/changerate||

#### 获取用户共享用户

||||
|:--|:--|:--|
|函数名|usertransferquery||
|输入参数|openid|用户的openid|
|输入参数|deviceid|设备号|
|返回参数|userdata|json数据，openid为键，nickname为用户昵称|
|接口地址|https://www.xuburenlongjohnson.xyz/usertransferquery||


#### 获取用户借用的柜子编号

||||
|:--|:--|:--|
|函数名|borrowdockerquery||
|输入参数|openid|用户的openid|
|输入参数|deviceid|设备号|
|返回参数|dockerid|柜子号|
|接口地址|https://www.xuburenlongjohnson.xyz/borrowdockerquery||


#### 获取柜子信息

||||
|:--|:--|:--|
|函数名|dockerinfoquery||
|输入参数|dockerid|柜子编号|
|返回参数|data|json数据，柜子的GPS信息，以及唯一编号|
|接口地址|https://www.xuburenlongjohnson.xyz/dockerinfoquery||



#### 删除共享用户
||||
|:--|:--|:--|
|函数名|usertransferdel||
|输入参数|openid|用户的openid|
|输入参数|deviceid|设备号|
|输入参数|openiddel|待删除的openid|
|接口地址|https://www.xuburenlongjohnson.xyz/usertransferdel||


#### 获取用户手机号码
||||
|:--|:--|:--|
|函数名|getphonenumber||
|输入参数|openid|用户的openid|
|输入参数|iv|解密初始向量|
|输入参数|encryptedData|待解密字符串|
|返回参数|data|详细见下面的例子|
|接口地址|https://www.xuburenlongjohnson.xyz/wxlogin/getphonenumber||

解密后的数据为

{
    "phoneNumber": "13580006666",  
    "purePhoneNumber": "13580006666", 
    "countryCode": "86",
    "watermark":
    {
        "appid":"APPID",
        "timestamp":TIMESTAMP
    }
}

#### locationquery:

功能介绍：查询用户位置

||||
|:--|:--|:--|
|函数名|locationqueryhistory||
|输入参数|openid|用户的openid|
|输入参数|deviceid|用户名下的设备号|
|输入参数|timestart|开始时间段|
|输入参数|timeend|结束时间段|
|返回参数|lat|经度|
|返回参数|lon|纬度|
|返回参数|CSQ|信号质量，从1到32，最优为32，可根据信号显示格数图形，5格或者四格都可|
|返回参数|Battery|电池余量，从0到100，显示为电池图标|
|返回参数|temp |设备温度，单位为摄氏度|
|接口地址|https://www.xuburenlongjohnson.xyz/locationqueryhistory||


详细行为定义：

    data = [OpenID , DeviceID]
    首先查询OpenID和DeviceID的匹配关系，
    若找不到设备，返回ErrorCode 2
    若找到设备，但用户权限已过期，则返回ErrorCode 1.
    查询DEVICE ID在OPENID下在权限。
        若权限过期，则返回ErrorCode = 1;
        若权限成功，则返回DEVICE ID在OPENID下的规定时间内的位置信息。
    返回格式为jason列表：[loc:[[lat1,gat1],[lat2,gat2]…];


#### 暂不使用alarmcheck:

功能介绍：暂时不使用

||||
|:--|:--|:--|
|函数名|alarmcheck||
|输入参数|openid|用户的openid|
|输入参数|deviceid|用户名下的设备号|
|返回参数|Alarm|告警信息|
|返回参数|lon|纬度|
|返回参数|CSQ|信号质量，从1到32，最优为32，可根据信号显示格数图形，5格或者四格都可|
|返回参数|Battery|电池余量，从0到100，显示为电池图标|
|返回参数|temp |设备温度，单位为摄氏度|
|接口地址|https://www.xuburenlongjohnson.xyz/?||

告警信息为数字，具体含义由一个表格决定，待定。

#### alarmquery:

功能介绍：查看用户告警

||||
|:--|:--|:--|
|函数名|alarmcheck||
|输入参数|openid|用户的openid|
|输入参数|deviceid|用户名下的设备号|
|返回参数|data|告警列表|
|返回参数|data.alarmlevel|告警级别|
|返回参数|data.note|告警内容|
|返回参数|data.triggertime|告警触发时间|
|接口地址|https://www.xuburenlongjohnson.xyz/wxalarm/alarmquery||

告警信息为数字，具体含义由一个表格决定，待定。



#### 错误告警表:

||||
|:--|:--|:--|
|ErrorCode|||
|0|用户权限有效，但无设备|需要扫码添加设备（例如是借用其它人），或者借用设备在云端添加设备（Docker）|
|1|用户权限过期|需要充值|
|2|	设备查找失败|用户上报的设备并没有绑定关系，需要重新绑定|
|4|	设备未有任何记录|新设备（或者设备未注册）|
|5|	柜子反应超时	||
|6|	柜子无可用设备	||
|8|	正常状态 |在借用设备时，根据该标记来判断借用是否成功|
|14|	无押金  |需要发起押金支付，支付量为固定值|
|15|	余额不足 ||