docs: uni-clientDB

docs/uniCloud/uni-clientDB.md

@@ -119,7 +119,7 @@ db.action('get-info') // 不使用action时可以不调用action方法
 - 上传时会对query进行序列化，除Date类型、RegExp之外的所有不可序列化的参数类型均不支持（例如：undefined）
 - 为方便控制禁止前端使用set方法，一般情况下也不需要前端使用set
 - 更新数据库时不可使用更新操作符`db.command.inc`等
-- 新数据时键值不可使用`{'a.b.c': 1}`的形式（后续会对此进行优化）
+- 更新数据时键值不可使用`{'a.b.c': 1}`的形式（后续会对此进行优化）
 
 ### 语法扩展
 
@@ -141,14 +141,14 @@ clientDB目前内置了3个变量可以供客户端使用，客户端并非直
 2. validator目录用于存放字段数据校验规则。和db-permission一样，validator目录下每个文件的文件名对应一个表名。
 3. action目录下的预处理后处理逻辑。action下每个目录对应一个操作，前端页面在callFunction时传入action参数指明当前操作需要使用哪个action（可以在权限规则内指定某些操作必须使用指定的action，比如`"action in ['action-a','action-b']"`）
 
+**注意**
+
+- clientDB依赖uni-id提供用户身份，如果你不了解uni-id，请参考[uni-id文档](https://uniapp.dcloud.net.cn/uniCloud/uni-id)
+- 通常在管理控制台使用clientDB，需要获取不同角色用户拥有的权限（在权限规则内使用auth.permission），请先查阅[uni-id 角色权限](https://uniapp.dcloud.net.cn/uniCloud/uni-id?id=rbac)
 
 **云函数内部执行顺序**
-
-1. permission权限校验，校验未通过则流程终止
-2. validator数据校验，校验未通过则流程终止。如果是新增会在这一步之前执行defaultValue的逻辑
-3. 执行action.before，内部可以对数据进行修改，开启事务等操作
-4. 执行command数据库操作
-5. 执行action.after，可以对错误处理、对结果调整
+
+![](https://vkceyugu.cdn.bspapp.com/VKCEYUGU-dc-site/b7d96a10-ff35-11ea-8ff1-d5dcf8779628.jpg)
 
 云函数默认返回值形式如下，开发者可以在action的after内修改返回结果，传入after内的result不带code和message。
 
@@ -186,6 +186,8 @@ clientDB目前内置了3个变量可以供客户端使用，客户端并非直
 可以参考db-permission内的使用示例说明
 
 ### db-permission
+
+db-permission内为数据表权限，以表名作为文件名，clientDB会自动读取要访问的表的权限。
 
 使用db-permission之前需要先了解以下db-permission的原理。db-permission会对客户端上传的数据库指令进行校验，即客户端的查询条件应该满足db-permission内规定的条件。比如db-permission内规定doc.a > 1,那么查询条件里面就必须有a且条件内的a也满足a>1，`{a:2}`、`{a:db.command.gt(3)}`都是满足条件的查询。
 
@@ -246,7 +248,7 @@ uniCloud.callFunction({
         book_id: '$book_id'
       },
       pipeline: $.pipeline()
-      // 此match方法内的条件会和book表对应的权限规则进行校验，{status: 'OnSell'}会参与校验。这里如果将dbCmd.and换成dbCmd.or会校验不通过
+      // 此match方法内的条件会和book表对应的权限规则进行校验，{status: 'OnSell'}会参与校验，整个expr方法转化成一个不与任何条件产生交集的特别表达式。这里如果将dbCmd.and换成dbCmd.or会校验不通过
       .match(dbCmd.and([ 
         {
           status: 'OnSell'
@@ -324,26 +326,23 @@ db.collection('street').where(dbCmd.or([
 ])).get()
 ```
 
-### action
+### action
+
+action主要用于进行数据操作前后处理数据
 
 ```js
-// 客户端指定action
-import db from '@/js_sdk/uni-clientDB/index.js'
-const dbCmd = db.command
-uniCloud.callFunctin({
-  name:'uni-clientDB',
-  data: {
-    action: 'add-todo', // 传入云函数内action目录下对应的文件名即可
-    command: db.collection('todo')
-    .add({
-    	title: 'todo title'
-    })
-  }
-}).then(res => {
-  console.log(res)
-}).catch(err => {
-  console.error(err)
-})
+// 客户端指定action为add-todo
+import db from '@/js_sdk/uni-clientDB/index.js'
+db.action('add-todo')
+  .collection('todo')
+  .add({
+    title: 'todo title'
+  })
+  .then(res => {
+    console.log(res)
+  }).catch(err => {
+    console.error(err)
+  })
 
 // 一个云函数内action文件示例 action/add-todo.js
 module.exports = {
@@ -356,7 +355,7 @@ module.exports = {
     state.newData.create_time = Date.now()
     // 指定插入或修改的数据内的create_time为Date.now()
     // 执行了此操作之后实际插入的数据会变成 {title: 'todo title', create_time: xxxx}
-    // 如果是执行插入操作时指定当前时间为创建时间的场景，有更简单的实现方案：在validator内配置defaultValue
+    // 如果是执行插入操作时指定当前时间为创建时间的场景，有更简单的实现方案：在validator内配置defaultValue或者forceDefaultValue
   },
   // 在数据库操作之后执行
   after:async (state,event,error,result)=>{
@@ -364,6 +363,10 @@ module.exports = {
     // event为传入云函数的event对象
     // error为执行操作的错误对象，如果没有错误error的值为null
     // result为执行command返回的结果
+    
+    if(error) {
+      throw error
+    }
     
     // after内可以对result进行额外处理并返回，如果有after方法，则云函数返回值会是after方法的返回值
     result.msg = 'hello'
@@ -377,15 +380,19 @@ module.exports = {
 ```js
 // state参数格式如下
 {
-  command: {
-    getMethod,
-    getParam,
+  command: {
+    // getMethod('where') 获取所有的where方法，返回结果为[{$method:'where',$param: [{a:1}]}]
+    getMethod,
+    // getMethod({name:'where',index: 0}) 获取第1个where方法的参数，结果为数组形式，例：[{a:1}]
+    getParam,
+    // setParam({name:'where',index: 0, param: [{a:1}]}) 设置第1个where方法的参数，调用之后where方法实际形式为：where({a:1})
     setParam
   },
   // 需要注意的是clientDB可能尚未获取用户信息，如果权限规则内没使用auth对象且数据库指令里面没使用db.env.uid则clientDB不会自动取获取用户信息
   auth: {
     uid, // 用户ID，如果未获取或者获取失败uid值为null
-    role, // role暂时没有在uni-id支持，如果未获取或者获取失败uid值为[]
+    role, // 通过uni-id获取的用户角色，需要使用1.1.9以上版本的uni-id，如果未获取或者获取失败role值为[]
+    permission, // 通过uni-id获取的用户权限，需要使用1.1.9以上版本的uni-id，如果未获取或者获取失败permission值为[]，注意登录时传入needPermission才可以获取permission，请参考 https://uniapp.dcloud.net.cn/uniCloud/uni-id?id=rbac
     checked // 是否已经获取了用户信息
   },
   // 事务对象，如果需要用到事务可以在action的before内使用state.transaction = await db.startTransaction()传入