账户管理 API

概述

账户管理主要包括了用户, 组织结构, 角色和权限的管理, 以及用户后台操作记录的查询.

系统前缀

API:

https://{domain-name}/v2/account/

版本

V3.2

作者

@author ChengZhen

修改历史

2020/6/28

• 添加多个属性

2019/8/15

• 删除部门和角色的 title 属性
• 添加 Key-Value API

2019/5/22

• 更新部分错误码等

2018/8/10

• 添加评论 API

2018/8/2

• 基本属性添加最大长度列
• 添加消息通知 API

2018/7/23

• 为企业, 部门添加 owner 属性
• POST /user/login 添加 signdata 返回参数 (用于不同域名统一登录)
• GET /user/login 添加不同域名统一登录参数

用户注册

由于平台只面向企业内部使用, 所以暂不提供用户自助注册接口, 所有用户只能由管理员添加和维护.

用户身份认证机制

很多 API 都需要身份认证, 或者在未认证的情况下只返回一些公开信息.

目前主要提供 2 种身份认证的方式:

1. Session - HTTP 会话和 Cookie 的方式
2. API Key - 访问密钥的方式

HTTP 会话和实现方式

当用户登录系统时, 服务端会保存当前登录的用户的信息到服务端 Session 中, 并通过 Cookie 在客户端保存 Session 的 ID, 在后续的 API 请求中服务端会通过 Cookie 中的 Session ID 去查询 Session 中有没有用户的登录信息.

• 使用 express-session 实现 session 操作.
• 使用数据库存储 session, 这样可以在多个服务端共享 session 数据
• 认证后用户信息保存在 session 中
• 使用 cookie 在客户端保存 session 的 ID
• 目前实现在单一域名下的各个服务可以共享登录状态

在服务器端脚本中, 可以通过 req.session.user 来访问登录的用户的信息:

let userInfo = req.session.user
console.log(userInfo.name)

Session 配置方式

为 express 添加如下的中间件, 不同的服务端之间可以通过数据库共享统一的 Session 会话.

// session
app.use(session({
    saveUninitialized: false, // 初始化 session 时是否保存到存储中。
    secret: 'sae-cmpp', // 作为服务器端生成 session 的签名。
    cookie: {
        maxAge: 1000 * 3600 * 12, // 12 hours
        httpOnly: true
    },
    store: new MongoStore({ // 保存会话信息到 Mongodb
        url: config.session.url,
        autoRemove: 'native',  // Default
        touchAfter: 24 * 3600  // time period in seconds
    })
}));

具体请参考:

• https://www.npmjs.com/package/express-session
• https://www.npmjs.com/package/connect-mongo

统一登录页面

访问以下链接，进入到授权登录页面：

GET {{base_url}}/views/login

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
scope	-	String	系统代码
client_id	-	String	客户端 ID
response_type	-	String	应答类型, code 表示只返回 code 参数
redirect_uri	-	String	回调 URL

响应结果:

显示登录表单页面

回调:

GET {{callback}}?&signdata={{signdata}}&sign={{sign}}

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
signdata	true	String	加密的用户认证信息, Base64 编码
sign	-	String	签名方法, 默认为 md5
code	-	String	授权码
scope	-	String	权限范围

流程图:

Title: 流程图
浏览器->服务器S: GET http://test.a.com/s/info
服务器S->服务器S: 没有找到登录信息
服务器S->浏览器: 301 跳转到本服务器登录页面
浏览器->服务器S: GET http://test.a.com/s/auth/login
服务器S->浏览器: 301 跳转到认证服务器登录页面
浏览器->认证服务器A: GET http://{domain-name}/v2/account/auth/login?callback=http://test.a.com/s/auth/callback
认证服务器A->>浏览器: 200 返回认证信息 (with signdata & sign)
浏览器->服务器S: GET http://test.a.com/s/auth/callback?signdata={{认证信息}}&sign={{sign}}
服务器S->服务器S: 保存登录信息
服务器S->浏览器: 301 跳转到 http://test.a.com/s/info 页面
浏览器->服务器S: GET http://test.a.com/s/info
服务器S->浏览器: 200 返回页面内容

如上所示，通过统一登录接口，可以实现不同域名下的服务器认证和登录。

API Key 认证方式

API 请求可以带 api-key 的参数, 每个用户都会创建一个 api-key, 系统根据这个 key 来确定用户身份, 以及是否有权访问请求的资源.

api-key 可以在系统后台 Accouts 子系统进行管理.

在参数中使用 api-key 的例子:

GET /user/self?api-key=01234567890abcdefghijklmn

在 HTTP Header 中使用 api-key 的例子:

GET /user/self HTTP/1.1
API-Key: 01234567890abcdefghijklmn

通过 API Key 认证方式可以方便地实现 APP 等非 WEB 客户端的认证和登录。

Title: 流程图
应用程序->服务器S: GET http://test.a.com/s/api/info
服务器S->服务器S: 没有找到登录信息
服务器S->应用程序: 401 没有认证
应用程序->认证服务器A: POST /account/auth/login (username & password)
认证服务器A->>应用程序: 200 返回认证信息 (API Key)
应用程序->服务器S: GET http://test.a.com/s/info?api-key={{API-KEY}}
服务器S->服务器S: 没有缓存 API-KEY
服务器S->认证服务器A: GET /account/auth/self (API-KEY)
认证服务器A->>服务器S: 200 返回认证信息
服务器S->应用程序: 200 返回页面内容

OAUTH 认证

客户端检查登录状态

客户端可以通过 GET /auth/self 接口查询当前登录的用户, 如果返回了用户的信息则表示用户已登录. 具体请查询相关的 API 文档.

用户认证

账号登录

POST /auth/login

请求参数: 通过用户名和密码登录

当需要用户输入用户名和密码时用这种方式登录。

NAME	REQUIRED	TYPE	DESCRIPTION
password	true	String	密码
username	true	String	用户名
scope	-	String	认证范围
response_type	-	String	返回类型，code 表示返回认证代码

请求参数: 通过 token 登录

其他 APP 或第三方系统访问 API 接口时用这种方式登录, 可以避免暴露用户名和密码。

用户 token 可随时在管理控制台重设。

NAME	REQUIRED	TYPE	DESCRIPTION
token	true	String	用户 Token
scope	-	String	认证范围
response_type	-	String	返回类型，code 表示返回认证代码

响应结果:

返回登录的用户的信息

{
    "id": String,
    "avatar": String,
    "country": String,
    "created": Date,
    "email": String,
    "name": String,
    "phone": String,
    "realname": String,
    "state": String,
    "token": String,
    "updated": Date,
    "username": String,
    "code": String,
    "isOwner": Boolean,
    "isAdmin": Boolean,
    "company": {
        "id": String,
        "name": String
    }，
    "department": {
        "id": String,
        "name": String
    },
    "roles": [{
        "id": String,
        "name": String
    }],
    "permissions": {
        "<module>": ["<permission>"]
    }
}

下面是比较重要的返回参数:

• username 用户登录名
• code 当请求参数 response_type 为 code 时返回这个参数，具体请参考 oauth
• isAdmin 表示当前用户为超级用户
• isOwner 表示当前用户为 (企业) 账号持有人
• permissions 这个用户的所有权限 (他拥有的所有角色的权限)
• company 这个用户所属的公司
• department 这个用户所属的部门

注销登录

POST /auth/logout

请求参数: 通过 Cookie ID 注销

请求中必须包含 Cookie 参数 (包含了服务端会话的 ID), 具体请参考 express-session

请求参数: 通过 token 注销

NAME	REQUIRED	TYPE	DESCRIPTION
token	true	String	用户 Token

响应结果:

如果当前有登录任何账号, 将立即注销登录并返回如下信息.

{
    "code": 0,
    "message": "User logged out"
}

忘记密码

POST /auth/forgot

请求参数: - 通过用户名找回密码

NAME	REQUIRED	TYPE	DESCRIPTION
username	ture	String	用户名

请求参数: - 通过邮箱地址找回密码

NAME	REQUIRED	TYPE	DESCRIPTION
email	ture	String	邮箱地址

响应结果:

如果成功, 系统会发送一封包含密码重置码的邮件到用户注册的邮箱地址, 并返回如下信息.

{
    code: 0,
    message: "Password reset email sent successful."
}

重置密码

POST /auth/reset

请求参数: 通过旧密码重置密码

NAME	REQUIRED	TYPE	DESCRIPTION
username	ture	String	用户名
password	ture	String	旧密码
new_password	ture	String	新密码

请求参数: 通过验证码重置密码

NAME	REQUIRED	TYPE	DESCRIPTION
username	ture	String	用户名
code	ture	String	验证码
new_password	ture	String	新密码

密码重置码可以通过忘记密码接口获取.

响应结果:

如果密码重置成功将返回如下的消息.

{
    "code": 0,
    "message": "Password reset successful."
}

修改个人资料

POST /auth/update

请求参数: 通过旧密码重置密码

NAME	REQUIRED	TYPE	DESCRIPTION
password	ture	String	旧密码
new_password	ture	String	新密码

请求参数: 更新个人资料

NAME	TYPE	DESCRIPTION
country	String	国家/地区
email	String	邮箱地址
name	String	英文/拼音姓名
title	String	标题
phone	String	电话号码
realname	String	中文/本地姓名

响应结果:

返回修改后的用户的信息

{
    "country": String,
    "created": Date,
    "companyId": String,
    "departmentId": String,
    "email": String,
    "id": String,
    "name": String,
    "title": String,
    "phone": String,
    "realname": String,
    "roles": String[],
    "state": String,
    "token": String,
    "updated": Date,
    "username": String
}

检查当前登录状态

GET /auth/self

请求参数: 通过 token 登录

NAME	REQUIRED	TYPE	DESCRIPTION
token	true	String	用户 Token
response_type	-	String	返回类型，code 表示返回认证代码

响应结果:

返回当前登录的用户的会话信息

{
    "company": {
        "id": String,
        "name": String,
        "owner": String,
        "logo": String,
        "title": String
    },
    "department": {
        "id": String,
        "name": String
    },
    "code": String,
    "isOwner": Boolean,
    "isAdmin": Boolean,
    "email": String,
    "id": String,
    "md5sum": String,
    "permissions": Array,
    "realname": String,
    "roles": [],
    "token": String,
    "username": String
}

下面是比较重要的返回参数:

• username 用户登录名
• code 当请求参数 response_type 为 code 时返回这个参数，具体请参考 oauth
• isAdmin 表示当前用户为超级用户
• isOwner 表示当前用户为 (企业) 账号持有人
• permissions 这个用户的所有权限 (他拥有的所有角色的权限)
• company 这个用户所属的公司
• department 这个用户所属的部门

绑定微信账号

GET /auth/wechat

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
code	true	String	认证码

返回结果:

重定向到 ../views/login 页面

OAUTH 用户认证

获取 access_token

GET /auth/access_token

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
code	true	String	授权码
client_id	-	String	客户端 ID
client_secret	-	String	客户端密钥
grant_type	-	String	authorization_code

返回结果:

{
    "access_token": "xxxxxx",
    "refresh_token": "xxxxxx",  
    "expires_in": "xxxxxx"
}

企业

企业账号是一个组织的根节点，相关的平台资源都会关联到用户所属的企业。

企业号属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	yes	ObjectId	-	企业 ID
applications	-	String[]	100	开放的应用程序
children	-	Company[]	-	子企业账号列表
code	yes	String	32	企业编号, 由字母数字组成
created	yes	Date	-	创建日期
departments	-	Department[]	-	部门列表
description	-	String	200	企业简要描述
industry	yes	String	32	所属行业类型
logo	-	String	200	企业Logo图片
members	-	User[]	-	成员列表
metadata	-	Object	-	企业元数据
name	yes	String	32	企业全称, 不允许重名
owner	yes	String	-	企业账号持有人用户名
parent	-	Company	-	所属上一级企业
parentId	yes	ObjectId	-	所属上一级企业的 ID
roles	-	Role[]	-	角色列表
title	yes	String	32	企业简称
type	yes	String	32	企业账号类型
updated	yes	Date	-	最后更新日期
users	-	User[]	-	用户列表

企业号级联

企业号通过 parentId 属性实现级联，parentId 为空表示为顶级企业号

开放的应用程序

applications 属性包含了这个企业号开通的应用的名称的列表

查询企业号列表

GET /company/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
limit	Number	100	最多返回的记录数
offset	Number	0	开始返回的记录的索引
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
q	String	-	搜索条件字符串
query	String	-	模糊搜索企业名称
select	String[]	-	选择返回的属性
parentId	ObjectId	-	上级企业 ID

• 如果指定了查询参数 companyId 则返回该企业和其所有子企业号
• 如果未指定则返回当前用户所属企业和其所有子企业号

示例:

GET /company/list?offset=0&limit=100&order=desc&orderBy=name&q=name~=test

响应结果:

返回包含企业信息的列表

{
    "total": Number,
    "offset": Number,
    "limit": Number,
    "companies": [{
        "code": String,
        "created": Date,
        "description": String,
        "id": String,
        "name": String,
        "owner": String,
        "title": String,
        "type": String,
        "updated": Date
    }]
}

查询指定企业号信息

POST /company/get

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	企业 ID
select	-	string[]	选择要返回的属性

• id 为 @parent 时表示获取上级企业号的信息

响应结果:

返回指定的企业的信息

{
    "applications": String[],
    "children": Object[],
    "code": String,
    "created": Date,
    "description": String,
    "metadata": Object,
    "id": String,
    "name": String,
    "owner": String,
    "parent": Object,
    "title": String,
    "type": String,
    "updated": Date
}

创建新的企业号

POST /company/add

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
applications	-	String[]	开放的应用
code	-	String	企业编码
description	-	String	企业描述
logo	-	String	Logo图片
metadata	-	Object	元数据
name	true	String	企业名称
owner	-	String	拥有者用户名
title	true	String	显示标题
type	-	String	账号类型

响应结果:

返回添加后的企业的信息

{
    "applications": String[],
    "code": String,
    "created": Date,
    "description": String,
    "metadata": Object,
    "id": String,
    "name": String,
    "owner": String,
    "parentId": String,
    "title": String,
    "type": String,
    "updated": Date
}

修改企业号属性

POST /company/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	企业 ID
applications	-	String	开放的应用程序
code	-	String	企业编码
description	-	String	企业描述
logo	-	String	企业Logo图片
metadata	-	String	元数据
name	-	String	企业名称
owner	-	String	拥有者用户名
parentId	-	ObjectId	所属的上级企业的 ID
title	-	String	显示标题
type	-	String	账号类型

响应结果:

返回修改后的企业的信息

{
    "applications": String[],
    "code": String,
    "created": Date,
    "description": String,
    "metadata": Object,
    "id": String,
    "name": String,
    "owner": String,
    "parentId": String,
    "title": String,
    "type": String,
    "updated": Date
}

删除企业号

POST /company/del

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	企业 ID

响应结果:

返回删除的企业的信息

{
    "applications": String[],
    "code": String,
    "created": Date,
    "description": String,
    "metadata": Object,
    "id": String,
    "name": String,
    "owner": String,
    "parentId": String,
    "title": String,
    "type": String,
    "updated": Date
}

注意:

• 不能删除含有部门、成员或角色的企业

用户

• 每个用户有相关的 API-Key, 用来访问 API 接口时提供身份认证.
• 系统安装时, 内置一个超级管理员账号, 不可以删除

属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	-	ObjectId	-	用户 ID
isAdmin	-	Boolean	-	虚拟属性, 是否系统管理员
isOwner	-	Boolean	-	虚拟属性, 是否有 (企业) 账号持有人
avatar	-	String	100	用户头像图片路径
company	-	Object	-	虚拟属性, 所属企业详情
companyId	-	ObjectId	-	所属企业 ID
country	yes	String	32	国家/地区, 限数字和+, 如 +86
created	yes	Date	-	创建时间
department	yes	Object	-	虚拟属性, 所属部门详情
departmentId	-	ObjectId	-	所属部门 ID
description	yes	String	200	简介, 限 UTF-8 字符
email	yes	String	100	邮箱地址, 限邮箱格式
ext	yes	String	32	分机号码, 限数字和-
gender	yes	String	32	性别
metadata	-	Object	-	元数据
name	yes	String	32	姓名(英文或拼音), 限字母数字空格和-_.
password	-	String	32	密码, 最少6个字符, 限 UTF-8 字符
phone	yes	String	32	电话号码, 限数字和-
realname	yes	String	32	姓名(中文), 限 UTF-8 字符
roles	-	ObjectId[]	-	所属角色列表
state	yes	String	32	用户状态, 默认为 active
title	yes	String	32	用户职务
token	-	String	32	API-Key
updated	yes	Date	-	最后修改时间
username	yes	String	32	用户名, 限字母数字和-_.
wechat	-	Object	-	微信账号

用户状态

状态

VALUE	NOTE
active	正常状态
inactive	表示这个用户已被禁用

性别

VALUE	NOTE
male	男性
female	女性

微信账号绑定

wechat 对象属性:

NAME	TYPE	NOTE
openid	String	微信公众号用户 OpenID
updated	Date	绑定日期

查询用户列表

GET /user/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
limit	String	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc
orderBy	String	id	排序字段名
offset	String	0	开始返回的记录的索引
q	String	-	搜索条件字符串
companyId	ObjectId	-	公司 ID
departmentId	ObjectId	-	部门 ID

响应结果:

返回包含用户信息的列表

{
    "total": Number,  // 分页信息 (总记录数)
    "offset": Number, // 分页信息 (开始索引)
    "limit": Number,  // 分页信息 (分页大小)
    "users": [{
        "id": String,
        "company": { "id": String "name": String },
        "country": String,
        "created": Date,
        "department": { "id": String, "name": String },
        "email": String,
        "name": String,
        "phone": String,
        "realname": String,
        "roles": [{ "id": String, "name": String }],
        "state": String,
        "title": String,
        "updated": Date,
        "username": String
    }]
}

查询指定用户信息

GET /user/get

请求参数: - 通过 ID 查询

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	用户 ID

请求参数: - 通过 email 地址查询

NAME	REQUIRED	TYPE	DESCRIPTION
email	true	String	用户邮箱地址

响应结果:

只返回这个用户的公共信息

{
    "id": String,
    "company": { "id": String "name": String },
    "country": String,
    "created": Date,
    "department": { "id": String, "name": String },
    "email": String,
    "name": String,
    "phone": String,
    "realname": String,
    "roles": [{ "id": String, "name": String }],
    "state": String,
    "updated": Date,
    "username": String
}

创建新的用户

POST /user/add

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
companyId	true	ObjectId	所属企业 ID
country	-	String	国家/地区
departmentId	-	ObjectId	所属部门 ID
email	-	String	邮箱地址
name	-	String	英文/拼音姓名
phone	-	String	电话号码
realname	-	String	中文/本地姓名
roles	-	ObjectId	角色 ID, 多个角色以逗号分隔
title	-	String	标题
username	true	String	用户名

响应结果:

返回创建的用户的信息

{
    "companyId": String,
    "country": String,
    "created": Date,
    "departmentId": String,
    "email": String,
    "id": String,
    "name": String,
    "phone": String,
    "realname": String,
    "roles": String[],
    "state": String,
    "title": String,
    "token": String,
    "updated": Date,
    "username": String
}

修改用户属性

POST /user/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	用户 ID
companyId	-	ObjectId	所属公司 ID
country	-	String	国家/地区
departmentId	-	ObjectId	部门 ID
email	-	String	邮箱地址
name	-	String	名称
password	-	String	密码
phone	-	String	电话号码
realname	-	String	真实名称
roles	-	ObjectId	角色 ID
state	-	String	用户状态: active, inactive
title	-	String	标题
token	-	String	API-Key

响应结果:

返回修改后的用户的信息

{
    "id": String,
    "companyId": String,
    "country": String,
    "created": Date,
    "departmentId": String,
    "email": String,
    "name": String,
    "phone": String,
    "realname": String,
    "roles": String[],
    "state": String,
    "title": String,
    "token": String,
    "updated": Date,
    "username": String
}

删除用户

注意不能删除默认超级管理员

POST /user/del

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	用户 ID

响应结果:

返回被删除的用户信息

{
    "id": String,
    "companyId"; String,
    "country": String,
    "created": Date,
    "departmentId": String,
    "email": String,
    "name": String,
    "phone": String,
    "realname": String,
    "roles": [String],
    "state": String,
    "title": String,
    "updated": Date,
    "username": String
}

角色

• 一个角色可以分配多个权限
• 一个用户可以关联一个角色

角色属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	-	ObjectId	-	角色 ID
code	yes	String	32	角色编码，用于标识，由字母数字组成
companyId	-	ObjectId	-	所属企业 ID
created	yes	Date	-	创建时间
description	-	String	200	简介
name	yes	String	32	角色名称
permissions	-	Object	-	权限列表
updated	yes	Date	-	最后修改时间
departments	-	Department[]	-	部门列表
members	-	User[]	-	成员列表

权限列表

权限由 服务 + 模块 + 操作 组成, 如:

• account.user_add 表示添加用户的权限
• account.user_update 表示修改用户的权限
• account.user_del 表示删除用户的权限
• account.user 表示所有操作用户的权限

当有多个权限时用 JSON 格式表示, 如:

{
    "account": ["user", "role_add", "role_del"],
    "device": ["device", "product"],
}

查询角色列表

GET /role/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	String	0	开始返回的记录的索引
limit	String	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
q	String	-	搜索条件字符串
query	String	-	模糊搜索名称
select	String[]	-	选择要返回的属性
companyId	ObjectId	-	所属企业 ID

响应结果:

返回包含角色信息的列表

{
    "total": Number,
    "offset": Number,
    "limit": Number,
    "roles": [{
        "id": ObjectId,
        "companyId": String,
        "created": Date,
        "description": String,
        "name": String,
        "permissions": { String: [String] },
        "title": String,
        "updated": Date
    }]
}

创建新的角色

POST /role/add

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
name	true	String	角色名
code	-	String	角色编码
description	-	String	简介
permissions	-	String	权限列表, 编码的 JSON 字符串格式
companyId	-	ObjectId	所属公司 ID

permissions 示例:

{
    "account": ["user", "role", "department"],
    "device": ["device", "product"]
}

响应结果:

返回创建的角色的信息

{
    "id": String,
    "companyId": String,
    "created": Date,
    "description": String,
    "name": String,
    "permissions": { String: [String] },
    "title": String,
    "updated": Date
}

修改角色属性

POST /role/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	角色 ID
name	-	String	角色名称
code	-	String	角色编码
description	-	String	简介
permissions	-	String	权限列表, 编码的 JSON 字符串格式

响应结果:

返回修改后的角色的信息

{
    "id": String,
    "companyId": String,
    "created": Date,
    "description": String,
    "name": String,
    "permissions": { "<name>": String[] },
    "title": String,
    "updated": Date
}

删除角色

POST /role/del

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	角色 ID

响应结果:

返回删除的角色的信息

{
    "id": String,
    "companyId": String,
    "created": Date,
    "description": String,
    "name": String,
    "permissions": { "<name>": String[] },
    "title": String,
    "updated": Date
}

注意:

• 不能删除包含成员的角色

部门

部门用于对企业内部成员进行分组，目前暂时只支持一级结构

• 一个部门可以包含多个用户
• 一个用户只能属于一个部门

部门属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	-	ObjectId	-	部门 ID
code	yes	String	32	部门编号或英文名称
companyId	-	ObjectId	-	所属企业 ID
created	yes	Date	-	创建时间
description	-	String	200	部门简介
name	yes	String	32	部门名称
parentId	-	ObjectId	-	上级部门 ID
roles	-	ObjectId[]	-	所属角色列表
updated	yes	Date	-	最后修改时间
members	-	User[]	-	成员列表

查询部门列表

GET /department/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	String	0	开始返回的记录的索引
limit	String	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
q	String	-	搜索条件字符串
query	String	-	模糊搜索部门名称
select	String[]	-	选择要返回的属性
companyId	ObjectId	-	所属企业 ID

示例:

GET /department/list?offset=0&limit=100&order=desc&orderBy=name&q=name~=test

响应结果:

返回包含部门信息的列表

{
    "total": Number,
    "offset": Number,
    "limit": Number,
    "departments": [{
        "companyId": String,
        "created": Date,
        "id": String,
        "name": String,
        "updated": Date
    }]
}

查询指定部门信息

POST /department/get

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	部门 ID

响应结果:

返回指定的部门的信息

{
    "id": String,
    "company": { "id": String, "name": String },
    "created": Date,
    "name": String,
    "updated": Date
}

创建新的部门

POST /department/add

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
companyId	true	ObjectId	所属企业 ID
description	-	String	部门简介
name	true	String	部门名称
code	-	String	部门编号
parentId	-	ObjectId	上级部门编号

响应结果:

返回创建的部门的信息

{
    "id": String,
    "companyId": String,
    "created": Date,
    "name": String,
    "updated": Date
}

修改部门属性

POST /department/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	部门 ID
code	-	String	部门编码
companyId	true	ObjectId	公司 ID
description	-	String	部门简介
name	-	String	部门名称

响应结果:

返回修改后的部门的信息

{
    "id": String,
    "companyId": String,
    "created": Date,
    "name": String,
    "updated": Date
}

删除部门

POST /department/del

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	部门 ID

响应结果:

返回删除的部门的信息

{
    "id": String,
    "companyId": String,
    "created": Date,
    "name": String,
    "updated": Date
}

注意:

• 不能删除含有子部门、成员的部门

操作日志

用于记录用户操作记录

• 记录和查询用户后台操作日志
• 方便对用户后台管理操作进行追溯

操作日志属性列表

NAME	SORTABLE	TYPE	DESCRIPTION
id	-	ObjectId	日志 ID
companyId	-	ObjectId	所属企业号 ID
created	true	Date	操作时间
details	-	Object	详细操作内容
ip	true	String	操作者的 IP 地址
module	true	String	操作对象模块
target	true	String	操作的对象类型
type	true	String	操作类型
user	-	User	操作者的用户
user.id	-	ObjectId	操作者的用户 ID

module - 模块名

模块名, 如 account, device, asset, nms 等.

target - 对象类型

对象类型为操作的实体对象类型, 如 user, role, department 等.

type - 操作类型

NAME	DESCRIPTION
login	登录
add	添加
del	删除
update	修改

查询操作日志列表

GET /log/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	String	0	开始返回的记录的索引
limit	String	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
q	String	-	过滤条件
companyId	ObjectId	-	公司 ID
end	Number	-	结束时间, 默认为当前时间
start	Number	-	开始时间
type	String	-	操作类型
userId	ObjectId	-	操作者的用户 ID

示例:

GET /department/list?offset=0&limit=100&order=desc&orderBy=created&module=account&type=update&start=12304045454&q=target~=user

响应结果:

返回包含操作记录信息的列表

{
    "total": Number,
    "offset": Number,
    "limit": Number,
    "logs": [{  
        "id": String,
        "created": Date,
        "details": { "id": String },
        "ip": String,
        "module": String,
        "target": String,
        "type": String,
        "user": { "id": String, "username": String, "realname": String }
    }]
}

删除操作日志

POST /log/del

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	角色 ID

响应结果:

返回删除的日志的信息

{
    "id": String,
        "created": Date,
        "details": { "id": String },
        "ip": String,
        "module": String,
        "target": String,
        "type": String,
        "user": { "id": String, "username": String, "realname": String }
}

评论

表示用户对任何对象发表的评论信息

这个模块当前暂未使用

评论属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	-	ObjectId	-	评论 ID
comments	-	Array	-	回复的评论
content	-	String	200	内容
created	true	Date	-	创建日期
target	-	Object	-	评论对象
updated	true	Date	-	阅读日期
user	-	Object	-	用户

查询评论列表

GET /comment/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	String	0	开始返回的记录的索引
limit	String	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
targetId	String	-	评论对象 ID
userId	String	-	用户 ID

响应结果:

返回评论列表

{
    "total": Number,
    "comments": [{
        "id": String,
        "content": String,
        "created": Date,
        "updated": Date,
        "user": {
            "id": String,
            "username": String,
            "name": String
        },
        "comments": [{
            "id": String,
            "content": String,
            "created": Date,
            "updated": Date,
            "user": {
                "id": String,
                "username": String,
                "name": String
            }
        }]
    }]
}

查询指定的评论

GET /comment/get

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	通知 ID

响应结果:

返回通知内容

{
    "id": String,
    "content": String,
    "created": Date,
    "updated": Date,
    "user": {
        "id": String,
        "username": String,
        "name": String
    },
    "comments": [{
        "id": String,
        "content": String,
        "created": Date,
        "updated": Date,
        "user": {
            "id": String,
            "username": String,
            "name": String
        }
    }]
}

创建新的评论

POST /comment/add

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
content	true	String	评论内容
targetId	-	OjbectId	评论对象 ID

响应结果:

返回创建的评论的内容

{
    "id": String,
    "content": String,
    "created": Date,
    "updated": Date,
    "user": {
        "id": String,
        "username": String,
        "name": String
    }
}

修改指定的评论

POST /comment/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
content	-	String	评论内容
id	true	OjbectId	评论 ID

响应结果:

返回修改后的评论的内容

{
    "id": String,
    "content": String,
    "created": Date,
    "updated": Date,
    "user": {
        "id": String,
        "username": String,
        "name": String
    }
}

删除评论

POST /comment/del

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	OjbectId	评论 ID

响应结果:

返回删除的评论的内容

{
    "id": String,
    "content": String,
    "created": Date,
    "updated": Date,
    "user": {
        "id": String,
        "username": String,
        "name": String
    }
}

KV 存储

属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	-	ObjectId	-	键值对 ID
companyId	-	ObjectId	-	所属的公司
created	true	Date	-	创建日期
key	true	String	100	键
updated	true	Date	-	最后更新日期
value	-	String|Object	1024	值

查询 Key 列表

GET /keyvalue/keys

响应结果:

{
    "total": Number,
    "keys": [
        "a",
        "b",
        "c"
    ]
}

查询 Key-Value 列表

GET /keyvalue/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	Number	0	开始返回的记录的索引
limit	Number	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
companyId	ObjectId	-	公司 ID

响应结果**:

{
    "limit": Number,
    "offset": Number,
    "total": Number,
    "values": [
        {
            "id": String,
            "companyId": String,
            "created": Date,
            "key": String,
            "updated": Date,
            "value": String
        }
    ]
}

查询指定的值

GET /keyvalue/get

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
key	true	String	键值

响应结果:

{
    "companyId": String,
    "created": Date,
    "id": String,
    "key": String,
    "updated": Date,
    "value": String
}

设置指定的值

POST /keyvalue/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
key	true	String	键值
value	true	String	要设置的值

响应结果:

{
    "companyId": String,
    "created": Date,
    "id": String,
    "key": String,
    "updated": Date,
    "value": String
}

删除指定的值

POST /keyvalue/del

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
key	true	String	键值

响应结果:

{
    "companyId": String,
    "created": Date,
    "id": String,
    "key": String,
    "updated": Date,
    "value": String
}

通知

指系统推送给用户的通知消息

通知属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	-	ObjectId	-	通知 ID
body	-	String	200	消息内容
companyId	-	ObjectId	-	所属公司账号 ID
confirmed	true	Date	-	确认时间
created	true	Date	-	创建日期
details	-	Object	-	消息详细数据
pinned	true	Boolean	-	是否置顶
read	true	Boolean	-	是否已读, 默认为 true
sender	-	Object	-	发送者信息
title	true	String	32	消息标题
type	true	String	32	消息类型
updated	true	Date	-	阅读日期
userId	-	ObjectId	-	用户 ID

type 消息类型

• system 系统通知
• user 用户信息
• alert 告警通知

sender 发送者信息

• type 发送者类型，如 user, device, system
• id 发送者的 ID
• name 发送者的名称

查询通知列表

GET /notification/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	Number	0	开始返回的记录的索引
limit	Number	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
read	Boolean	-	是否已读
type	String	-	消息类型
companyId	ObjectId	-	公司 ID
userId	ObjectId	-	用户 ID

响应结果:

返回通知列表

{
    "total": Number,
    "notifications": [{
        "id": String,
        "body": String,
        "created": Date,
        "details": Object,
        "read": Boolean,
        "sender": { "id": String, "type": String, "name": String },
        "title": String,
        "type": String,
        "updated": Date
    }]
}

查询指定的通知

GET /notification/get

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	通知 ID

响应结果:

返回通知内容

{
    "id": String,
    "body": String,
    "created": Date,
    "details": Object,
    "read": Boolean,
    "sender": { "id": String, "type": String, "name": String },
    "title": String,
    "type": String,
    "updated": Date
}

修改指定的通知

POST /notification/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	通知 ID
read	-	Boolean	是否已读
confirmed	-	Date	确认时间

响应结果:

返回修改后的通知内容

{
    "id": String,
    "body": String,
    "created": Date,
    "details": Object,
    "read": Boolean,
    "sender": { "id": String, "type": String, "name": String },
    "title": String,
    "type": String,
    "updated": Date
}

删除通知

POST /notification/del

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	通知 ID

响应结果:

返回删除的通知的内容

{
    "id": String,
    "body": String,
    "created": Date,
    "details": Object,
    "read": Boolean,
    "sender": { "id": String, "type": String, "name": String },
    "title": String,
    "type": String,
    "updated": Date
}

发送通知消息

POST /notification/send

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	通知 ID
type	-	String	通知类型，默认为 'alert'
username	true	String	通知用户名
userId	-	String	通知用户 ID
device	true	String	设备名称
deviceId	-	String	设备 ID
event	true	String	事件名称
location	-	String	位置
time	true	String	时间
title	true	String	通知标题
url	-	String	HTTP URL 地址
remark	-	String	备注信息
alertId	-	String	相关的报警的 ID

响应结果:

{

}

系统信息

应用列表

GET /system/applications

响应结果:

返回所有可用的应用列表

{
    "applications": {
        "<name>": {
            "title": String,
            "description": String,
            "icon": String,
            "href": String,
        }
    }
}

权限列表

GET /system/permissions

响应结果:

返回所有可选的权限

{
    "permissions": [{
        "title": String,
        "titles": { "zh-CN": String },
        "name": String,
        "permissions": [
            {
                "name": String,
                "title": String,
                "titles": { "zh-CN": String }
            }
        ]
    }]
}

• name 权限名称
• title 权限显示标题
• titles 多语言标题
  • permissions 权限子项

统计信息

GET /system/stat

响应结果:

返回账号系统各模块统计信息

{
    "company": {
        "total": Number // 企业总数
    },
    "user": {
        "total": Number // 用户总数
    },
    "department": {
        "total": Number // 部门总数
    },
    "role": {
        "total": Number // 角色总数
    }
}

系统状态

GET /system/status

返回服务器软件版本等信息

响应结果:

{
    "description": String,
    "name": String,
    "version": String // 系统软件版本号
}

错误码

错误码:

CODE	MESSAGE	NOTE
100401	Unauthorized	用户没有登录, 或身份没有认证
100403	Permission denied	禁止访问, 如用户状态为 inactive
104001	Miss required parameter	缺失必选参数，请参考 API 文档
104002	Parameter error	参数错误
300301	User not exists	用户不存在
300308	Wrong account or password	账号或密码错误
300312	Reset code is invalid	无效的验证码

管理权限列表

表示系统支持并可以分配的权限列表:

注意如果没有 account 系统权限时不可以查看 account 服务下的所有信息.

NAME	DESCRIPTION	NOTE
account	账号管理权限	查看账号管理系统基本权限
account.company	管理公司的权限	没有权限时仅且可以查看本公司信息
account.department	管理部门的权限	没有权限时仅且可以查看本公司部门信息
account.log	查询日志的权限	没有权限时不可以查看所有日志
account.role	管理角色的权限	没有权限时仅且可以查看本公司角色信息
account.user	管理用户的权限	没有权限时仅且可以查看相关的用户

权限分配表

API	PERMISSION	NOTE
/stat	-	-
/user/*	account	-
/user/add	account.user	-
/user/del	account.user	-
/user/update	account.user	-
/user/self	-	-
/auth/reset	*	-
/auth/forgot	*	-
/auth/login	*	-
/auth/logout	-	-
/role/*	account	-
/role/add	account.role	-
/role/del	account.role	-
/role/update	account.role	-
/department/*	-	-
/department/add	account.department	-
/department/del	account.department	-
/department/update	account.department	-
/log/list	account	-
/system/*	*	-

• '-' 表示必须登录后才能访问
• '*' 表示不需要登录也能访问