diff --git a/docs/uniCloud/uni-id.md b/docs/uniCloud/uni-id.md index ea844a1acfbd5d85cdee8aa59a944bb4519be811..97b481381ea4b52d7ae2ffc96e36c1c0a1fcdcc8 100644 --- a/docs/uniCloud/uni-id.md +++ b/docs/uniCloud/uni-id.md @@ -173,11 +173,12 @@ DCloud暂无计划开发百度、头条、QQ等小程序的登录，以及Apple **user参数说明** -| 字段 | 类型 | 必填| 说明 | -| --- | --- | --- | --- | -| username | String| 是 |用户名，唯一 | -| password | String| 是 |密码 | -| myInviteCode | String| 否 |自行设置用户的邀请码 | +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| username | String | 是 |用户名，唯一 | +| password | String | 是 |密码 | +| needPermission| Boolean | 否 |设置为true时会在checkToken时返回用户权限（permission），建议在管理控制台中使用 | +| myInviteCode | String | 否 |自行设置用户的邀请码 | username可以是字符串、可以是email、可以是手机号，本插件不约束，开发者可以自己定。 @@ -261,6 +262,7 @@ uniCloud.callFunction({ | --- | --- | --- | --- | | username | String| 是 |用户名 | | password | String| 是 |密码 | +| needPermission| Boolean | 否 |设置为true时会在checkToken时返回用户权限（permission），建议在管理控制台中使用 | | queryField | Array| 否 |指定从哪些字段中比对username，不填默认与数据库内的username字段对比, 可取值'username'、'email'、'mobile'| **响应参数** @@ -306,14 +308,16 @@ exports.main = async function(event,context) { **响应参数** -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| code | Number |错误码，0表示成功 | -| msg | String |详细信息 | -| uid | String |用户Id，校验成功之后会返回 | +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| code | Number |错误码，0表示成功 | +| msg | String |详细信息 | +| uid | String |用户Id，校验成功之后会返回 | | token | String |新增于uni-id 1.1.7版本，用户token快要过期时，新生成的token，只有在config内配置了`tokenExpiresThreshold`的值时才会有此行为| -| tokenExpired| TimeStamp |新增于uni-id 1.1.7版本，新token的过期时间 | -| userInfo | Object |用户信息，uid对应的uni-id-users全部字段 | +| tokenExpired| TimeStamp |新增于uni-id 1.1.7版本，新token的过期时间 | +| role | Array |新增于uni-id 1.1.9版本，用户角色列表 | +| permission | Array |新增于uni-id 1.1.9版本，用户权限列表，只有登录操作时传入needPermission才会返回，否则为空数组 | +| userInfo | Object |用户信息，uid对应的uni-id-users全部字段 | **注意：** @@ -633,6 +637,7 @@ exports.main = async function(event,context) { | password |String | 否 |密码，type为`register`时生效 | | inviteCode |String | 否 |邀请人的邀请码，type为`register`时生效 | | myInviteCode|String | 否 |设置当前注册用户自己的邀请码，type为`register`时生效 | +| needPermission| Boolean | 否 |设置为true时会在checkToken时返回用户权限（permission），建议在管理控制台中使用 | **响应参数** @@ -764,6 +769,7 @@ exports.main = async function(event,context) { | type | String| 否 |指定操作类型，覆盖存在则登录不存在则注册的默认行为，可选值为`login`、`register`| | password |String | 否 |密码，type为`register`时生效 | | myInviteCode |String | 否 |设置当前注册用户自己的邀请码，type为`register`时生效 | +| needPermission| Boolean | 否 |设置为true时会在checkToken时返回用户权限（permission），建议在管理控制台中使用 | **响应参数** @@ -933,6 +939,7 @@ exports.main = async function(event,context) { | code | String| 是 |微信登录返回的code | | platform |String | 否 |客户端类型：`mp-weixin`、`app-plus`，默认uni-id会自动取客户端类型，但是在云函数url化等场景无法取到客户端类型，可以使用此参数指定 | | myInviteCode|String | 否 |设置当前注册用户自己的邀请码，type为`register`时生效 | +| needPermission| Boolean | 否 |设置为true时会在checkToken时返回用户权限（permission），建议在管理控制台中使用 | **响应参数** @@ -1154,7 +1161,8 @@ exports.main = async function(event,context) { | --- | --- | --- | --- | | code | String| 是 |支付宝登录返回的code | | platform | String| 否 |客户端类型：`mp-weixin`、`app-plus`，默认uni-id会自动取客户端类型，但是在云函数url化等场景无法取到客户端类型，可以使用此参数指定 | -| myInviteCode| String| 否 |设置当前注册用户自己的邀请码，type为`register`时生效 | +| myInviteCode| String| 否 |设置当前注册用户自己的邀请码，type为`register`时生效 | +| needPermission| Boolean | 否 |设置为true时会在checkToken时返回用户权限（permission），建议在管理控制台中使用 | **响应参数** @@ -1187,7 +1195,7 @@ exports.main = async function(event,context) { ``` -## 获取微信openid +## 获取支付宝用户ID 用法：`uniID.code2SessionWeixin(Object Code2SessionWeixinParams);` @@ -1360,6 +1368,298 @@ exports.main = async function(event,context) { } ``` +## 获取用户角色 + +根据uid获取用户角色 + +用法：`uniID.getRoleByUid(Object GetRoleByUidParams)` + +**参数说明** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| uid | String| 是 |用户Id，可以通过checkToken返回 | + +**响应参数** + +| 字段| 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code| Number| 是 |错误码，0表示成功| +| msg | String| 是 |详细信息 | +| role | Array | 是 |用户拥有的角色列表| + +## 获取角色内的权限 + +根据roleID获取角色权限 + +用法：`uniID.getPermissionByRole(Object GetPermissionByRoleParams)` + +**参数说明** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| roleID| String| 是 |角色Id | + +**响应参数** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | Number| 是 |错误码，0表示成功 | +| msg | String| 是 |详细信息 | +| permission| Array | 是 |用户拥有的角色列表 | + +## 获取用户的权限 + +根据uid获取用户权限 + +用法：`uniID.getPermissionByUid(Object GetPermissionByUidParams)` + +**参数说明** + +| 字段| 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| uid | String| 是 |用户Id | + +**响应参数** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | Number| 是 |错误码，0表示成功 | +| msg | String| 是 |详细信息 | +| permission| Array | 是 |用户拥有的角色列表 | + +## 为用户绑定角色 + +用法：`uniID.bindRole(Object BindRoleParams)` + +**参数说明** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| uid | String | 是 |用户Id | +| roleList| Array | 是 |角色Id（role_id）列表 | +| reset | Boolean | 否 |是否直接覆盖用户角色，true：直接将roleList设置为用户角色，false：在用户已有角色后追加角色| + +**响应参数** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | Number| 是 |错误码，0表示成功 | +| msg | String| 是 |详细信息 | + +## 为角色绑定权限 + +用法：`uniID.bindPermission(Object BindPermissionParams)` + +**参数说明** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| roleID | String | 是 |用户Id | +| permissionList| Array | 是 |权限Id（permission_id）列表 | +| reset | Boolean | 否 |是否直接覆盖角色权限，true：直接将permissionList设置为角色权限，false：在角色已有权限后追加权限| + +**响应参数** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | Number| 是 |错误码，0表示成功 | +| msg | String| 是 |详细信息 | + +## 为用户解绑角色 + +用法：`uniID.unbindRole(Object UnbindRoleParams)` + +**参数说明** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| uid | String | 是 |用户Id | +| roleList| Array | 是 |角色Id（role_id）列表 | + +**响应参数** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | Number| 是 |错误码，0表示成功 | +| msg | String| 是 |详细信息 | + +## 为角色解绑权限 + +用法：`uniID.unbindPermission(Object UnbindPermissionParams)` + +**参数说明** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| roleID | String| 是 |角色Id | +| permissionList| Array | 是 |权限Id（permission_id）列表| + +**响应参数** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | Number| 是 |错误码，0表示成功 | +| msg | String| 是 |详细信息 | + +## 新增角色 + +用法：`uniID.addRole(Object AddRoleParams)` + +**参数说明** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| roleID | String| 是 |角色Id，唯一标识 | +| roleName | String| 否 |角色名称，展示用 | +| comment | String| 否 |备注 | +| permission| Array | 否 |权限Id（permission_id）列表| + +**响应参数** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | Number| 是 |错误码，0表示成功 | +| msg | String| 是 |详细信息 | + +## 获取角色列表 + +用法：`uniID.getRoleList(Object GetRoleListParams)` + +**参数说明** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| limit | Number | 是 |限制返回数量 | +| offset | Number | 是 |偏移量 | +| needTotal | Boolean | 否 |是否需要返回总数 | + +**响应参数** + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| code | Number| 错误码，0表示成功 | +| msg | String| 详细信息 | +| roleList| Array |roles表记录数组（包含role_name、comment等）| +| total | Number|总数量 | + +## 更新角色信息 + +**注意不可修改role_id** + +用法：`uniID.updateRole(Object UpdateRoleParams)` + +**参数说明** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| roleID | String| 是 |角色Id，唯一标识 | +| roleName | String| 否 |角色名称，展示用 | +| comment | String| 否 |备注 | +| permission| Array | 否 |权限Id（permission_id）列表| + +**响应参数** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | Number| 是 |错误码，0表示成功 | +| msg | String| 是 |详细信息 | + +## 删除角色 + +用法：`uniID.deleteRole(Object DeleteRoleParams)` + +**参数说明** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| roleID| String| 是 |角色Id，唯一标识 | + +**响应参数** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | Number| 是 |错误码，0表示成功 | +| msg | String| 是 |详细信息 | + +## 新增权限 + +用法：`uniID.addPermission(Object AddPermissionParams)` + +**参数说明** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| permissionID | String| 是 |权限Id，唯一标识 | +| permissionName| String| 否 |权限名称，展示用 | +| comment | String| 否 |备注 | + +**响应参数** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | Number| 是 |错误码，0表示成功 | +| msg | String| 是 |详细信息 | + +## 获取权限列表 + +用法：`uniID.getPermissionList(Object GetPermissionListParams)` + +**参数说明** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| limit | Number | 是 |限制返回数量 | +| offset | Number | 是 |偏移量 | +| needTotal | Boolean | 否 |是否需要返回总数 | + +**响应参数** + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| code | Number| 错误码，0表示成功 | +| msg | String| 详细信息 | +| permissionList| Array |permissions表记录数组（包含permission_name、comment等）| +| total | Number|总数量 | + +## 修改权限 + +**注意：不可修改permissionID** + +用法：`uniID.updatePermission(Object UpdatePermissionParams)` + +**参数说明** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| permissionID | String| 是 |权限Id，唯一标识 | +| permissionName| String| 否 |权限名称，展示用 | +| comment | String| 否 |备注 | + +**响应参数** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | Number| 是 |错误码，0表示成功 | +| msg | String| 是 |详细信息 | + +## 删除权限 + +用法：`uniID.deletePermission(Object DeletePermissionParams)` + +**参数说明** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| permissionID | String| 是 |权限Id，唯一标识 | + +**响应参数** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | Number| 是 |错误码，0表示成功 | +| msg | String| 是 |详细信息 | + ## 设置用户邀请码 针对未生成邀请码的用户使用此方法生成邀请码 @@ -1498,6 +1798,18 @@ exports.main = async function(event,context) { } ``` +# 角色权限@rbac + +自`1.1.9`版本起uni-id支持角色权限（通常情况下管理后台会需要角色权限）。除API列表内列出的角色权限相关的接口外，还有以下调整： + +1. 所有登录注册接口可以接收`needPermission`参数，配置为true时会在`checkToken`接口返回用户权限（permission），否则permission字段会是一个空数组。开发者可以在用户登录管理后台时，传入此参数表示当前登录的用户需要返回permission。 + +2. 新增两个数据表`uni-id-roles`、`uni-id-permissions`，可以使用示例项目里面的db_init.json创建，也可以直接使用opendb中的这两个数据表 + +**注意** + +- 我们推荐以`admin`角色作为超级管理员（即role内包含admin即可有所有接口访问权限）。clientDB内就做了这种实现，如果用户角色包含`admin`就拥有所有数据表的全部权限。 + # 裂变@fission 自`1.1.2`版本起uni-id支持裂变功能，目前仅适用手机号+验证码方式注册可以填写邀请码（inviteCode）接受邀请。 @@ -1553,7 +1865,8 @@ exports.main = async function(event,context) { | last_login_ip | String | 否 | 最后登录时 IP 地址 | | login_ip_limit | Array | 否 | 登录 IP 限制 | | inviter_uid | Array | 否 | 邀请人uid，按层级从下往上排列的uid数组，即第一个是直接上级| -| my_invite_code | String | 否 | 用户自己的邀请码 | +| my_invite_code | String | 否 | 用户自己的邀请码 | +| role | Array | 否 | 用户角色列表，由role_id组成的数组 | **wx_openid字段定义** @@ -1621,6 +1934,31 @@ exports.main = async function(event,context) { | ip | String | 是 | 请求时 IP 地址 | | created_at | Timestamp | 是 | 创建时间 | | expired_at | Timestamp | 是 | 验证码过期时间 | + +## 角色表 + +表名：`uni-id-roles` + +| 字段 | 类型 | 必填| 描述 | +| ---------- | --------- | ----| --------------------------------------| +| \_id | Object ID | 是 | 系统自动生成的Id | +| role_id | String | 是 | 角色唯一标识 | +| role_name | String | 否 | 角色名，展示用 | +| permission | Array | 是 | 角色拥有的权限列表 | +| comment | String | 否 | 备注 | +| created_date| Timestamp | 是 | 角色创建时间 | + +## 权限表 + +表名：`uni-id-permissions` + +| 字段 | 类型 | 必填| 描述 | +| ---------- | --------- | ----| --------------------------------------| +| \_id | Object ID | 是 | 系统自动生成的Id | +| permission_id | String | 是 | 权限唯一标识 | +| permission_name | String | 否 | 权限名，展示用 | +| comment | String | 否 | 备注 | +| created_date | Timestamp | 是 | 权限创建时间 | # 错误码 @@ -1684,6 +2022,8 @@ exports.main = async function(event,context) { |获取支付宝openid |807 |01 |未能获取openid | | | |02 |调用获取openid接口失败 | |公用码 |900 |01 |数据库读写异常 | + +**另外还有一些字符串类型的扩展错误码在各自接口的文档中展示，请不要直接使用`code>0`这种方式来判断是否有错误** # FAQ