[Legacy] 数据库面向终端的API - WNJXYK/JLU_DSD GitHub Wiki

由于系统结构设计的缘故，数据库模块 作为一个单独且独立的模块在内网中运行，并向 服务器模块 提供公网不可见的 Web API。当前 数据库模块 提供的 API 分为两种：对终端的与对服务器的，允许使用 Get 或者 Post 请求进行访问。在接下来的内容中，将会介绍面向终端提供的每个 API 的功能、调用参数与具体返回。

/user/login

接口功能： 用户登录并返回登录令牌

参数列表：

email : 用户邮箱
password : 密码（已加密的）

正常返回(示例)：

{ 
    "status" : 0,
    "info" : {
        "UID" : 1, // 用户编号
        "SID" : "bdcd6f623a9141c5", // 随机登录令牌
        "Nickname" : "User", // 用户昵称
        "Authority" : 3 // 用户权限等级
    }
}

异常返回：

// 请求参数异常
{ 
    "status" : -1,
    "msg": "Invalid Request"
}
// 服务器异常
{ 
    "status" : -2,
    "msg" : "Some Reasons" // 服务器异常原因
}
// 登录失败
{ 
    "status" : -3,
    "msg":"Incorrect Email or Password"
}

其他说明： 无

/user/verify

接口功能： 验证用户令牌是否有效

参数列表：

UID : 用户编号
SID : 用户安全令牌

正常返回(示例)：

{ 
    "status" : 0,
    "info" : {
        "UID" : 1, // 用户编号
        "Nickname" : "User", // 用户昵称
        "Authority" : 3, // 用户权限等级
        "Admin" : 0 // 用户是否具有高级权限，具有时为 1
    }
}

异常返回：

// 服务器异常
    // 请求参数异常
{ 
    "status" : -1,
    "msg": "Invalid Request"
}
// 服务器异常
{ 
    "status" : -2,
    "msg" : "Some Reasons" // 服务器异常原因
}
// 安全令牌无效或用户无效
{ 
    "status" : -3,
    "msg":"Invalid User"
}

其他说明： 无

/user/room

接口功能： 获得用户可以看到的房间列表。若 BID 字段不存在则列表不仅过大楼筛选，否则只返回属于 BID 大楼的房间。若 Offset 字段存在，则返回第 Offset 个符合要求房间之后的房间。若 Delta 字段存在，则只返回 Delta 个符合要求的字段。

参数列表：

UID : 用户编号
SID : 用户安全令牌
BID : 大楼编号[可选参数]
Offset : 返回结果位移[可选参数]
Delta : 返回结果数量[可选参数]

正常返回(示例)：

{ 
    "status" : 0,
    "info" : {
        "arr" : [
            {
                "RID" : 1, // 房间编号
                "Nickname" : "Room 1", // 房间昵称
                "Details" : "房间1号", // 房间详细信息
                "sCNT" : 0, // 已废弃
                "dCNT" : 0, // 已废弃
                "BID" : 1 // 房间所属大楼编号
            },
            {
                "RID" : 2, // 房间编号
                "Nickname" : "Room 2", // 房间昵称
                "Details" : "房间2号", // 房间详细信息
                "sCNT" : 0, // 已废弃
                "dCNT" : 0, // 已废弃
                "BID" : 2 // 房间所属大楼编号
            }, // 可能有更多
        ],
        "cnt" : 2, // 所有符合条件的房间数量
        "Modify" : 0 // 用户是否具有修改权限，具有时为 1
}

异常返回：

// 请求参数异常
{ 
    "status" : -1,
    "msg": "Invalid Request"
}
// 服务器异常
{ 
    "status" : -2,
    "msg" : "Some Reasons" // 服务器异常原因
}
// 安全令牌无效或用户无效
{ 
    "status" : -3,
    "msg":"Invalid User"
}

其他说明： Offset 与 Delta 实现分页功能。传入 SID 与 UID 将来可以控制不同用户看到不同房间。

/user/modify_room

接口功能： 修改房间信息。当 Delete 字段存在且为 1，则删除房间。当 Details 字段存在，则修改房间详细。

参数列表：

UID : 用户编号
SID : 用户安全令牌
RID : 房间编号
Delete : 是否删除房间[可选参数]
Details : 更改房间详细内容[可选参数]

正常返回(示例)：

{ 
    "status" : 0,
    "info" : 1 // 受影响的房间数量
}

异常返回：

// 请求参数异常
{ 
    "status" : -1,
    "msg": "Invalid Request"
}
// 服务器异常
{ 
    "status" : -2,
    "msg" : "Some Reasons" // 服务器异常原因
}
// 安全令牌无效或用户无效
{ 
    "status" : -3,
    "msg":"Invalid User"
}
// 用户无修改权限
{ 
    "status" : -4,
    "msg":"Invalid Authority"
}

其他说明： 无

/user/add_room

接口功能： 增加房间

参数列表：

UID : 用户编号
SID : 用户安全令牌
Nickname : 房间昵称
Details : 房间详细信息
BID : 所属大楼编号

正常返回(示例)：

{ 
    "status" : 0,
    "info" : 1 // 受影响的房间数量
}

异常返回：

// 请求参数异常
{ 
    "status" : -1,
    "msg": "Invalid Request"
}
// 服务器异常
{ 
    "status" : -2,
    "msg" : "Some Reasons" // 服务器异常原因
}
// 安全令牌无效或用户无效
{ 
    "status" : -3,
    "msg":"Invalid User"
}
// 用户无修改权限
{ 
    "status" : -4,
    "msg":"Invalid Authority"
}

其他说明： 无

/user/hardware

接口功能： 返回输出某个房间的所有硬件信息

参数列表：

UID : 用户编号
SID : 用户安全令牌
RID : 房间编号

正常返回(示例)：

{ 
    "status" : 0,
    "info" : [
        {
            "HID" : 1, // 硬件编号
            "Nickname" : "Raspi Light", // 硬件昵称
            "Type" : "Light", // 硬件类型
            "Ctrl" : 1, // 硬件是否可操作，不可操作为 0
        },
        {
            "HID" : 2, // 硬件编号
            "Nickname" : "Raspi Presence", // 硬件昵称
            "Type" : "PresenceSensor", // 硬件类型
            "Ctrl" : 0, // 硬件是否可操作，可操作为 1
        }, // 可能有更多
    ]
}

异常返回：

// 请求参数异常
{ 
    "status" : -1,
    "msg": "Invalid Request"
}
// 服务器异常
{ 
    "status" : -2,
    "msg" : "Some Reasons" // 服务器异常原因
}
// 安全令牌无效或用户无效
{ 
    "status" : -3,
    "msg":"Invalid User"
}
// 用户无访问权限【暂时无用】
{ 
    "status" : -4,
    "msg":"Invalid Authority"
}

其他说明： 无

/user/allHardware

接口功能： 获取所有硬件机器及其信息

参数列表：

UID : 用户编号
SID : 用户安全令牌

正常返回(示例)：

{ 
    "status" : 0,
    "info" : [
        {
            "HID" : 1, // 硬件编号
            "Nickname" : "Raspi Light", // 硬件昵称
            "Type" : "Light", // 硬件类型
            "Ctrl" : 1, // 硬件是否可操作，不可操作为 0
        },
        {
            "HID" : 2, // 硬件编号
            "Nickname" : "Raspi Presence", // 硬件昵称
            "Type" : "PresenceSensor", // 硬件类型
            "Ctrl" : 0, // 硬件是否可操作，可操作为 1
        }, // 可能有更多
    ]
}

异常返回：

// 请求参数异常
{ 
    "status" : -1,
    "msg": "Invalid Request"
}
// 服务器异常
{ 
    "status" : -2,
    "msg" : "Some Reasons" // 服务器异常原因
}
// 安全令牌无效或用户无效
{ 
    "status" : -3,
    "msg":"Invalid User"
}
// 用户无访问权限
{ 
    "status" : -4,
    "msg":"Invalid Authority"
}

其他说明： 此操作仅有管理员权限用户可以使用

/user/del_hardware

接口功能： 删除某个硬件

参数列表：

UID : 用户编号
SID : 用户安全令牌
HID : 硬件编号

正常返回(示例)：

{ 
    "status" : 0,
    "info" : 1 // 受影响硬件数量
}

异常返回：

// 请求参数异常
{ 
    "status" : -1,
    "msg": "Invalid Request"
}
// 服务器异常
{ 
    "status" : -2,
    "msg" : "Some Reasons" // 服务器异常原因
}
// 安全令牌无效或用户无效
{ 
    "status" : -3,
    "msg":"Invalid User"
}
// 用户无删除权限
{ 
    "status" : -4,
    "msg":"Invalid Authority"
}

其他说明： 此操作仅管理员可使用

/user/add_hardware

接口功能： 添加硬件

参数列表：

UID : 用户编号
SID : 用户安全令牌
HID : 硬件编号
Nickname : 硬件昵称

正常返回(示例)：

{ 
    "status" : 0
}

异常返回：

// 请求参数异常
{ 
    "status" : -1,
    "msg": "Invalid Request"
}
// 服务器异常
{ 
    "status" : -2,
    "msg" : "Some Reasons" // 服务器异常原因
}
// 安全令牌无效或用户无效
{ 
    "status" : -3,
    "msg":"Invalid User"
}
// 用户无添加权限
{ 
    "status" : -4,
    "msg":"Invalid Authority"
}
// 添加的硬件类型不存在
{ 
    "status" : -5,
    "msg":"Invalid Type"
}

其他说明： 此操作仅管理员可使用

/user/bind_hardware

接口功能： 将硬件与房间关联/解绑（添加删除硬件到房间）

参数列表：

UID : 用户编号
SID : 用户安全令牌
HID : 硬件编号
RID : 房间编号
Bind : 是否绑定，为 0 解除绑定，为 1 绑定

正常返回(示例)：

{ 
    "status" : 0
}

异常返回：

// 请求参数异常
{ 
    "status" : -1,
    "msg": "Invalid Request"
}
// 服务器异常
{ 
    "status" : -2,
    "msg" : "Some Reasons" // 服务器异常原因
}
// 安全令牌无效或用户无效
{ 
    "status" : -3,
    "msg":"Invalid User"
}
// 用户无添加权限
{ 
    "status" : -4,
    "msg":"Invalid Authority"
}
// （绑定时）绑定关系已存在
{ 
    "status" : -5,
    "msg":"Relation existed"
}
// （解绑时）不存在绑定关系
{ 
    "status" : -6,
    "msg":"Relation is not existed"
}
// 不存在此硬件
{ 
    "status" : -7,
    "msg":"No such hardware"
}
// 不存在此房间
{ 
    "status" : -8,
    "msg":"No such room"
}
// 一个可操作设备将被多个房间绑定
{ 
    "status" : -9,
    "msg":"A device can only bind with one room"
}
// 一个房间将绑定多个可操作设备
{ 
    "status" : -10,
    "msg":"A room can only contains one device"
}

其他说明： 此操作仅管理员可使用

/user/building

接口功能： 返回大楼列表

参数列表： 空

正常返回(示例)：

{ 
    "status" : 0,
    "info" : [
        { 
            "BID" : 大楼编号,
            "Nickname" : 大楼昵称,
            "Details" : 大楼详细
        },
        { 
            "BID" : 大楼编号,
            "Nickname" : 大楼昵称,
            "Details" : 大楼详细
        }, // 可能有更多
    ]
}

异常返回：

// 服务器异常
{ 
    "status" : -2,
    "msg" : "Some Reasons" // 服务器异常原因
}

其他说明： 无