فهرست منبع

web-doc:feat > web 接口

shaun-sheep 4 سال پیش
والد
کامیت
53eb08e0a3

+ 84 - 77
docs/.vuepress/config.js

@@ -34,95 +34,102 @@ module.exports = {
             text: "首页",
             link: "/"
         },
-        {
-            text: "安装配置",
-            items: [{
-                text: "开发环境",
-                items: [{
-                    text: "IDEA",
-                    link: "/setup/ide/idea"
-                },
-                {
-                    text: "VS Code",
-                    link: "/setup/ide/vscode"
-                },
-                {
-                    text: "Node.js",
-                    link: "/setup/ide/nodejs"
-                },
-                {
-                    text: "vue-cli",
-                    link: "/setup/ide/vuecli"
-                },
-                {
-                    text: "plantUML",
-                    link: "/setup/ide/plantUML"
-                }
-                ]
-            },
             {
-                text: "服务器",
+                text: "安装配置",
                 items: [{
-                    text: "基础配置",
-                    link: "/setup/server/nginx"
-                }, {
-                    text: "应用配置",
-                    link: "/setup/application/tuopu"
-                }
-                ]
-            },
-            ]
-        },
-        {
-            text: "开发文档",
-            items: [
-                {
-                    text: "引擎",
-                    items: [
-                        { text: "数据格式", link: "/guides/format/floorMap.md" },
-                        { text: "图形引擎", link: "/guides/engine/" },
-                        { text: "场景管理", link: "/guides/scene/" },
-                        { text: "楼层平面图", link: "/guides/big/" },
-                        // {text: "系统图", link: "/guides/system-diagram/"},
-                        { text: "编辑器", link: "/guides/edit/" },
+                    text: "开发环境",
+                    items: [{
+                        text: "IDEA",
+                        link: "/setup/ide/idea"
+                    },
                         {
-                            text: "平面图嵌入指南",
-                            link: "/guides/tDInsert/brief.md"
+                            text: "VS Code",
+                            link: "/setup/ide/vscode"
                         },
                         {
-                            text: "拓扑图嵌入指南",
-                            link: "/guides/tuopuInsert/brief.md"
+                            text: "Node.js",
+                            link: "/setup/ide/nodejs"
+                        },
+                        {
+                            text: "vue-cli",
+                            link: "/setup/ide/vuecli"
+                        },
+                        {
+                            text: "plantUML",
+                            link: "/setup/ide/plantUML"
                         }
                     ]
                 },
-            ]
-        },
-        {
-            text: "开发规范",
-            items: [
-                { text: "javascript", link: "/standard/javascript.md" },
-                { text: "typescript", link: "/standard/typescript/" },
-                { text: "约定", link: "/standard/appoint.md" },
-                { text: "git", link: "/standard/git.md" },
-                { text: "typescript 自动生成 api 文档", link: "/standard/typedoc.md" },
-            ]
-        },
-        {
-            text: "API参考",
-            items: [{
-                text: "图形引擎",
-                link: "http://doc.sagacloud.cn/api/web/graph/"
+                    {
+                        text: "服务器",
+                        items: [{
+                            text: "基础配置",
+                            link: "/setup/server/nginx"
+                        }, {
+                            text: "应用配置",
+                            link: "/setup/application/tuopu"
+                        }
+                        ]
+                    },
+                ]
+            },
+            {
+                text: "开发文档",
+                items: [
+                    {
+                        text: "引擎",
+                        items: [
+                            {text: "数据格式", link: "/guides/format/floorMap.md"},
+                            {text: "图形引擎", link: "/guides/engine/"},
+                            {text: "场景管理", link: "/guides/scene/"},
+                            {text: "楼层平面图", link: "/guides/big/"},
+                            // {text: "系统图", link: "/guides/system-diagram/"},
+                            {text: "编辑器", link: "/guides/edit/"},
+                            {
+                                text: "平面图嵌入指南",
+                                link: "/guides/tDInsert/brief.md"
+                            },
+                            {
+                                text: "拓扑图嵌入指南",
+                                link: "/guides/tuopuInsert/brief.md"
+                            }
+                        ]
+                    },
+                    {
+                        text: "接口",
+                        items: [
+                            {text: 'web 接口', link: "/guides/interface/"},
+                        ]
+                    },
+                ]
             },
+
             {
-                text: "建筑信息图",
-                link: "http://doc.sagacloud.cn/api/web/big/"
+                text: "开发规范",
+                items: [
+                    {text: "javascript", link: "/standard/javascript.md"},
+                    {text: "typescript", link: "/standard/typescript/"},
+                    {text: "约定", link: "/standard/appoint.md"},
+                    {text: "git", link: "/standard/git.md"},
+                    {text: "typescript 自动生成 api 文档", link: "/standard/typedoc.md"},
+                ]
             },
             {
-                text: "编辑器",
-                link: "http://doc.sagacloud.cn/api/web/edit/"
+                text: "API参考",
+                items: [{
+                    text: "图形引擎",
+                    link: "http://doc.sagacloud.cn/api/web/graph/"
+                },
+                    {
+                        text: "建筑信息图",
+                        link: "http://doc.sagacloud.cn/api/web/big/"
+                    },
+                    {
+                        text: "编辑器",
+                        link: "http://doc.sagacloud.cn/api/web/edit/"
+                    },
+                ]
             },
-            ]
-        },
             // {
             //     text: "概念解释",
             //     items: [{
@@ -177,7 +184,7 @@ module.exports = {
                     '^/gogs': '',
                 },
                 bypass: function (req, res, proxyOptions) {
-                    req.headers["Authorization"] = "Basic bGJzbDoyMDIwMDgyOQ=="
+                    req.headers["Authorization"] = "Basic bGJzbDoyMDIwMDgyOQ==";
                 }
             },
             '/labsl': {

+ 25 - 13
docs/guides/index.js

@@ -1,7 +1,7 @@
 const content = [
     {
-        title: '简介',
-        path: '/guides/'
+        title: "简介",
+        path: "/guides/"
     },
     {
         title: "数据格式",
@@ -9,7 +9,7 @@ const content = [
             ["/guides/format/floorMap", "底图数据"],
             ["/guides/format/systemJson", "系统图数据"],
             ["/guides/format/planJson", "平面图数据"],
-            ["/guides/format/style", "底图风格"],
+            ["/guides/format/style", "底图风格"]
         ]
     },
     {
@@ -25,11 +25,11 @@ const content = [
             ["/guides/engine/arrow", "绘制带有箭头的线段"],
             ["/guides/engine/selectContainer", "选择容器"],
             {
-                title: '综合示例',
+                title: "综合示例",
                 children: [
                     ["/guides/engine/demo/elsfk", "俄罗斯方块"],
                     ["/guides/engine/demo/elsfkDifficult", "俄罗斯方块-英雄版"],
-                    ["/guides/engine/demo/2048", "2048"],
+                    ["/guides/engine/demo/2048", "2048"]
                 ]
             }
         ]
@@ -47,7 +47,7 @@ const content = [
                     ["/guides/scene/items/text", "文字"],
                     ["/guides/scene/items/image", "图片"],
                     ["/guides/scene/items/svg", "SVG 图"],
-                    ["/guides/scene/items/imgText", "图例 item"],
+                    ["/guides/scene/items/imgText", "图例 item"]
                 ]
             },
             {
@@ -55,9 +55,9 @@ const content = [
                 children: [
                     ["/guides/scene/items/clock", "时钟"],
                     ["/guides/scene/regularPolygon", "正多边形"],
-                    ["/guides/scene/star", "星形"],
+                    ["/guides/scene/star", "星形"]
                 ]
-            },
+            }
         ]
     },
     {
@@ -73,7 +73,7 @@ const content = [
                     ["/guides/big/items/space", "空间"],
                     ["/guides/big/items/virtualWall", "虚拟墙"],
                     ["/guides/big/items/window", "窗户"],
-                    ["/guides/big/items/zone", "业务空间"],
+                    ["/guides/big/items/zone", "业务空间"]
                 ]
             },
             ["/guides/big/workLine", "工作流程"],
@@ -81,7 +81,7 @@ const content = [
             ["/guides/big/layerOrder", "图层"],
             ["/guides/big/factory/itemFactory", "item 创建工厂"],
             ["/guides/big/divide", "划分"],
-            ["/guides/big/mapDemo", "楼层平面图范例"],
+            ["/guides/big/mapDemo", "楼层平面图范例"]
         ]
     },
     {
@@ -95,7 +95,7 @@ const content = [
             ["/guides/tDInsert/install.md", "实现tooltip"],
             ["/guides/tDInsert/install.md", "画布拖动"],
             ["/guides/tDInsert/install.md", "切换楼层"],
-            ["/guides/tDInsert/install.md", "平面图示例代码"],
+            ["/guides/tDInsert/install.md", "平面图示例代码"]
         ]
     },
     {
@@ -109,7 +109,7 @@ const content = [
             ["/guides/tuopuInsert/viewColor.md", "画布颜色"],
             ["/guides/tuopuInsert/derive.md", "派生---设备类"],
             ["/guides/tuopuInsert/anther.md", "修改设备类状态"],
-            ["/guides/tDInsert/install.md", "平面图示例代码"],
+            ["/guides/tDInsert/install.md", "平面图示例代码"]
         ]
     },
     {
@@ -134,9 +134,21 @@ const content = [
                     ["/guides/edit/items/editTriangle", "编辑三角形"]
                 ]
             },
-            ["/guides/edit/undo/undo", "Undo示例"],
+            ["/guides/edit/undo/undo", "Undo示例"]
         ]
     },
+    {
+        title: "web 接口",
+        path: "/guides/interface/",
+        children: [
+            ["/guides/interface/create", "创建"],
+            ["/guides/interface/edit", "修改"],
+            ["/guides/interface/delete", "删除"],
+            ["/guides/interface/query", "查询"],
+            ["/guides/interface/count", "统计"],
+            ["/guides/interface/filters", "条件过滤"]
+        ]
+    }
 ];
 
 module.exports = content;

+ 64 - 0
docs/guides/interface/README.md

@@ -0,0 +1,64 @@
+# web接口
+
+::: details 目录
+[[toc]]
+:::
+
+## 接口文档
+接口文档,相当于后端对产品需求提供数据以及功能的一个说明书,为什么这样说那,一个产品的说明书,内容详细介绍,突出功能明确指出应该怎样操作执行的指令是什么,会达到什么样的效果,
+减少客户和客服沟通的频率,或者不需要询问客服看说明书就能明白功能以及达到的效果。接口文档意是如此,我们不可能每完成一个接口都开会或发到工作群中给大家讲解,也不可能一个产品的
+数据结构定好,所有的接口开发完统一大家一起开会做现场解说,不能保证所有的能记得所有内容,都会使用。为了高效而又节省时间需要我们写一个简单易懂的文档出来,而对于接口,在明确数
+据结构以及功能,还要测试接口是否可用,是否正确处理了数据,是否达到了前端的效果。即使后端测试过了,前端也要测试功能,还需要每个属性结构进行确认,这就需要我们整理出一份详细的
+文档出来,把功能、数据结构、示例都介绍详细、清楚,最好直接提供可以测试的接口文档,这样只要有一份接口文档就够了,不用再看着接口文档一个一个粘贴到别的工具上调试,节省了前端调
+试沟通数据结构了解属性功能接口使用方式的时间。
+
+### 接口文档调试工具
+
+![接口文档 swagger](./img/web-swager_001.jpg)
+
+* swagger 接口文档调试工具,保证了代码和文档的一致性,swagger 是直接集成在后端的项目中。使用注解的方式在代码中进行了更改 swagger 也会随之变化。
+* swagger 提供了接口测试功能,不需要安装 postmain , 文档中把每个属性、数据结构 接口的请求方式标注的很清楚,也可以把注意事项标记清楚。
+* 通过注解的方式自动生成文档,只需要补录一些需要注意事项,一些简单的示例介绍,节省了编写文档的时间
+
+![接口文档 swagger](./img/web-swager_004.jpg)
+
+![接口文档 swagger](./img/web-swager_005.jpg)
+
+点击 try it out 填写相应的参数
+
+![接口文档 swagger](./img/web-swager_006.jpg)
+点击 Execute 直接即可进行接口测试
+
+## 标准接口
+* 标准通用接口增删改查统计
+![接口文档 swagger](./img/web-swager_003.jpg)
+* 统一的请求体结构,应答结构
+* web端操作符的使用
+* 请求体重属性名不区分大小写,应答题返回标准的驼峰命名
+* 支持的值类型:int、float、double、boolean、char、date
+
+
+
+### 接口定义
+* 以对象为主的对象接口 ,唯物主义思想模式定义接口,面向对象编程理念,对象都一致,有相同接口,有利于前段使用接口的标准化,结构化,模块化,提高代码复用性,节约开发测试维护成本;
+![接口文档 swagger](./img/web-swager_002.jpg)
+* 规范化开发
+* 查询条件灵活的多样的
+* 专为应用服务的后台,比如数据中心就是围绕着物理世界或中台的壳,面向应用友好,主要针对应用和APP的需求,解决物理世界或中台对应用适配的问题
+
+## Web接口注意事项
+* 属性名不加引号且属性名不区分大小写;name与NAME代表相同的属性。
+* 属性名指的是实体类的属性名,不是指数据库的字段名(框架在操作数据库时,会自动将属性名转换为字段名)。
+* 数值型值、布尔型值,在写表达式时不需要写引号;
+* 字符串型值、日期型值,在写表达式时要写上单引号;
+* 表达式“包含”,“前缀”,“后缀”只用于字符串型属性;
+* 在“列表内”表达式,列表内的每个值的类型必须一致,否则会抛出异常;
+
+
+
+
+
+
+
+
+

+ 18 - 0
docs/guides/interface/count.md

@@ -0,0 +1,18 @@
+# 条件统计
+![web dev](./img/web-swager_012.jpg)
+## 统计数量
+请求体:
+```metadata json
+{
+  "Filters": "name = '低压开关'"
+}
+```
+应答体:
+```metadata json
+{
+  "Count": 6,
+  "Message": "",
+  "Result": "success"
+}
+```
+只需要填写项目id,然后编写过滤条件即可查询统计数量

+ 35 - 0
docs/guides/interface/create.md

@@ -0,0 +1,35 @@
+# 创建
+### 创建实体对象
+![web dev](./img/web-swager_007.jpg)
+例如创建设备实体对象:
+```metadata json
+{
+  "Content": [
+    {
+      "ProjectId": "Pj1102290001",
+      "Category": "TDLS",
+      "EquipLocalID": "ATFU-TOP-N-003",
+      "EquipLocalName": "低压开关柜-A03"
+    }
+  ]
+}
+
+```
+返回结果
+```metadata json
+{
+  "EntityList": [
+    {
+      "Category": "TDLS",
+      "EquipID": "Eq1102290001e2a2b859d59347af99649f7d234384d0",
+      "EquipLocalID": "ATFU-TOP-N-003",
+      "EquipLocalName": "低压开关柜-A03",
+      "EquipName": "低压开关柜-W55EJ",
+      "ProjectId": "Pj1102290001"
+    }
+  ],
+  "Message": "",
+  "Result": "success"
+}
+```
+创建对象,采用可以单个对象创建,也可以批量创建多个对象,创建返回的结果中会把创建的对象有值得属性返回,例如设备的ID,自动生成的名字都会在返回的结果中

+ 25 - 0
docs/guides/interface/delete.md

@@ -0,0 +1,25 @@
+# 删除
+## 删除数据
+![web dev](./img/web-swager_007.jpg)
+例如删除设备
+```
+[
+    {
+        "EquipID":"Eq1102290001e2a2b859d59347af99649f7d234384d0"
+    },
+    {
+        "EquipID":"Eq1102290001e2a2b859d59347af99649f7d23789445"
+    }
+]
+```
+返回结果
+
+```metadata json
+{
+  "Message": "",
+  "Result": "success"
+}
+```
+
+如果删除失败, Message 中会返回失败原因,删除接口目前只支持根据主键删除,例如设备的主键为设备id 所以只要传入设备id即可
+如果需要根据某些条件删除,目前需要定制接口来解决,删除接口支持单个对象删除以及批量删除多个对象

+ 67 - 0
docs/guides/interface/edit.md

@@ -0,0 +1,67 @@
+# 修改
+
+## 修改信息
+
+![web dev](./img/web-swager_010.jpg)
+修改数据信息支持整体数据覆盖,或只更新某几个或一个字段,或某几个或一个字段置空 例如修改设备数据
+```metadata json
+{
+  "Content": [
+    {
+      "Category": "TDLS",
+      "EquipID": "Eq1102290001135ba2e0ee574038bf2e6e5c3d81e7f6",
+      "EquipLocalID": "ATFU-TOP-N-003",
+      "EquipLocalName": "低压开关柜-A03",
+      "EquipName": "设备-DG5FN",
+      "ProjectId": "Pj1102290001"
+    }
+  ]
+}
+```
+返回结果
+```metadata json
+{
+  "Message": "",
+  "Result": "success"
+}
+```
+
+当前设备有值得所有信息点,把所有的信息点传给服务端,整体的数据覆盖,也可以指定更新某一个或几个信息点,例如: 只更新 EquipLocalName 本地名称
+```metadata json
+{
+  "Content": [
+    {
+      "Category": "TDLS",
+      "EquipID": "Eq1102290001135ba2e0ee574038bf2e6e5c3d81e7f6",
+      "EquipLocalID": "ATFU-TOP-N-003",
+      "EquipLocalName": "低压开关柜-A03",
+      "EquipName": "设备-DG5FN",
+      "ProjectId": "Pj1102290001"
+    }
+  ],
+    "Projection": [
+        "EquipLocalName"
+      ]
+}
+```
+在 Projection 中指定要更新的信息点,即使把所有信息点传给了服务端,只会更新 Projection 指定的信息点,其他信息点不会改变,,某一个信息点想要置空也需要指定这个信息点才可以置空例如:
+
+```metadata json
+{
+  "Content": [
+    {
+      "Category": "TDLS",
+      "EquipID": "Eq1102290001135ba2e0ee574038bf2e6e5c3d81e7f6",
+      "EquipLocalID": "ATFU-TOP-N-003",
+      "EquipLocalName": null,
+      "EquipName": "设备-DG5FN",
+      "ProjectId": "Pj1102290001"
+    }
+  ],
+    "Projection": [
+        "EquipLocalName","EquipLocalID"
+      ]
+}
+```
+上面的例子中把 EquipLocalName 信息点的值置空,需要在 Projection 中指定置空的信息点以及需要更新的信息点 ,在操作置空的请求体重可以不传需要置空的信息点
+只要在 Projection 中指定信息点的属性,就会把这个属性值置空 ,注意:更新是根据对象的主键进行数据更新,例如设备,一定要传设备id,否者更新失败,服务端会不知道要更新的是哪个对象

+ 149 - 0
docs/guides/interface/filters.md

@@ -0,0 +1,149 @@
+# 过滤条件
+
+## 表达式
+
+### 关系表达式
+| 关系 | 运算符 | 语法 |
+|:--:|:--:|:--:|
+| 等于 | = | 属性名 = 值 |
+| 不等于 | != | 属性名 != 值 |
+| 大于 | > | 属性名 > 值 |
+| 大于等于 | >= | 属性名 >= 值 |
+| 小于 | < | 属性名 < 值 |
+| 小于等于 | <= | 属性名 <= 值 |
+| 包含 | contain  | 属性名 contain  值 |
+| 前缀 | startwith  | 属性名 startwith  值 |
+| 后缀 | endwith   | 属性名 endwith   值 |
+| 为空 | isnull   | 属性名 isnull  |
+| 在列表内 | in   | 属性名 in [值1, 值2, 值3...] |
+
+::: warning 注意 
+* 表达式必须包含“属性名”;
+* 属性名必须在表达式左端;
+* 在列表内的 [] 方括号中值类型必须一致,使用 in 必须使用 [] 方括号
+:::
+
+#### 等于 =
+* 字符串类型,例如查询空调机组设备 category
+```metadata json
+"Filters":" category = 'ATAH'"
+```
+* 日期类型,例如查询 2020-08-12 创建的设备 createTime
+```metadata json
+"Filters":" createTime = '2020-08-12'"
+```
+* 数值类型,例如设备有贴码状态 0.完成贴码 1.待贴码 2.带换码 3.带撕码  codeType ,查询已完成的设备
+```metadata json
+"Filters":" codeType = 0 "
+```
+* 布尔类型,例如设备有一个开关属性,实时记录设备是否在运转,停止运转时会把这个属性设置为 false  ,查询为未开启的设备 switch
+```metadata json
+"Filters":" switch = false "
+```
+
+#### 不等于 !=
+* 字符串类型,例如查询空调机组类型以外的设备 category
+```metadata json
+"Filters":" category != 'ATAH'"
+```
+* 数值类型,例如设备有贴码状态 0.完成贴码 1.待贴码 2.带换码 3.带撕码  codeType ,查询待处理的设备
+```metadata json
+"Filters":" codeType != 0 "
+```
+
+#### 大于 >
+* 数值类型,例如设备有贴码状态 0.完成贴码 1.待贴码 2.带换码 3.带撕码  codeType ,查询带换码和带撕码的设备
+ ```metadata json
+ "Filters":" codeType > 1 "
+ ```
+* 日期类型,例如查询 2020-08-12 以后创建的设备 createTime 前提是不包含 2020-08-12 这个日期的
+```metadata json
+"Filters":" createTime > '2020-08-12'"
+```
+
+#### 大于等于 >=
+* 数值类型,例如设备有贴码状态 0.完成贴码 1.待贴码 2.带换码 3.带撕码  codeType ,查询待贴码、带换码和带撕码的设备
+ ```metadata json
+ "Filters":" codeType >= 1 "
+ ```
+* 日期类型,例如查询 2020-08-12 以后创建的设备 createTime 包含 2020-08-12 这个日期的
+```metadata json
+"Filters":" createTime >= '2020-08-12'"
+```
+
+#### 小于 <
+* 数值类型,例如设备有贴码状态 0.完成贴码 1.待贴码 2.带换码 3.带撕码  codeType ,查询待贴码、完成贴码
+ ```metadata json
+ "Filters":" codeType < 2 "
+ ```
+* 日期类型,例如查询 2020-08-12 之前创建的设备 createTime 不包含 2020-08-12 这个日期的
+```metadata json
+"Filters":" createTime < '2020-08-12'"
+```
+
+#### 小于等于 <=
+* 数值类型,例如设备有贴码状态 0.完成贴码 1.待贴码 2.带换码 3.带撕码  codeType ,查询待贴码、完成贴码和带换码的设备
+ ```metadata json
+ "Filters":" codeType <= 2 "
+ ```
+* 日期类型,例如查询 2020-08-12 之前创建的设备 createTime 包含 2020-08-12 这个日期的
+```metadata json
+"Filters":" createTime <= '2020-08-12'"
+```
+
+#### 包含 contain
+* 字符串,例如查询设备本地名称中包含 “风机” 两个字的设备 EquipLocalName
+```metadata json
+"Filters":" EquipLocalName contain '风机'"
+```
+
+#### 前缀
+只适用于字符串类型
+例如设备 id 是以 Eq 开头,空间id是以 Sp 开头,区分设备和空间就需要根据前缀来获取
+```metadata json
+"Filters":" Id startwith 'Eq'"
+```
+
+#### 后缀
+只适用于字符串类型
+例如楼层的 FloorMap 信息点是存储底图 key 值的,可能是 jsonz 压缩数据的 key ,也可能是 png 、jpg,查询后缀为 jsonz 的楼层数据
+```metadata json
+"Filters":" floorMap endwith 'jsonz'"
+```
+
+#### 空
+判断某一个对象的某个信息点是否有值,例如查询本地名称为空的设备
+```metadata json
+"Filters":" EquipLocalName isnull "
+```
+
+#### 在...内
+通常查询的时候会根据同一条件的多个值来获取数据,只适用于字符串类型
+例如有一组设备的id列表,查询值这个把列表中的所有设备 ['id1','id2','id3','id4','id5']
+```metadata json
+"Filters":" EquipID in ['id1','id2','id3','id4','id5'] "
+```
+* 数值类型,例如设备有贴码状态 0.完成贴码 1.待贴码 2.带换码 3.带撕码  codeType ,查询完成贴码、带换码和带撕码的设备。
+```metadata json
+"Filters":" codeType in [0,2,3] "
+```
+
+### 逻辑表达式
+| 逻辑 | 运算符 | 语法 |
+|:--:|:--:|:--:|
+| 非 | not <br> ! | not 表达式 <br> !表达式 |
+| 与 |  && <br> and | 表达式1 && 表达式2 <br> 表达式1 and 表达式2 |
+| 或 | \|\| <br> or | 表达式1 \|\| 表达式2  <br> 表达式1 or 表达式2 |
+| 多表达式 | ; | 表达式1 ; 表达式2 ; 表大式3 ... |
+
+#### 非 
+* not 例如设备有贴码状态 0.完成贴码 1.待贴码 2.带换码 3.带撕码  codeType ,查询完成贴码、带换码和带撕码的设备。
+
+
+
+
+
+
+
+
+

BIN
docs/guides/interface/img/web-swager_001.jpg


BIN
docs/guides/interface/img/web-swager_002.jpg


BIN
docs/guides/interface/img/web-swager_003.jpg


BIN
docs/guides/interface/img/web-swager_004.jpg


BIN
docs/guides/interface/img/web-swager_005.jpg


BIN
docs/guides/interface/img/web-swager_006.jpg


BIN
docs/guides/interface/img/web-swager_007.jpg


BIN
docs/guides/interface/img/web-swager_008.jpg


BIN
docs/guides/interface/img/web-swager_009.jpg


BIN
docs/guides/interface/img/web-swager_010.jpg


BIN
docs/guides/interface/img/web-swager_012.jpg


+ 339 - 0
docs/guides/interface/query.md

@@ -0,0 +1,339 @@
+# 查询
+## 请求体 json
+![web dev](./img/web-swager_009.jpg)
+::: details 查看代码
+```
+{
+  "Cascade": [
+    {
+      "Cascade": [
+        null
+      ],
+      "Distinct": true,
+      "Filters": "string",
+      "Group": {
+        "AvgList": [
+          "string"
+        ],
+        "Count": true,
+        "MaxList": [
+          "string"
+        ],
+        "MinList": [
+          "string"
+        ],
+        "NameList": [
+          "string"
+        ],
+        "SumList": [
+          "string"
+        ]
+      },
+      "Name": "string",
+      "Orders": "name asc, createTime desc",
+      "Projection": [
+        "string"
+      ]
+    }
+  ],
+  "Distinct": true,
+  "Filters": "string",
+  "Group": {
+    "AvgList": [
+      "string"
+    ],
+    "Count": true,
+    "MaxList": [
+      "string"
+    ],
+    "MinList": [
+      "string"
+    ],
+    "NameList": [
+      "string"
+    ],
+    "SumList": [
+      "string"
+    ]
+  },
+  "Orders": "name asc, createTime desc",
+  "PageNumber": 1,
+  "PageSize": 50,
+  "Projection": [
+    "string"
+  ]
+}
+```
+:::
+
+## 应答 json
+::: details 查看代码
+```metadata json
+{
+    "Content":[
+        {
+            "EquipID":"Eq3702020002f9052971335b417b896c73bdcd832f2d",
+            "EquipLocalId":"CCTV-15F-06-05",
+            "BimId":"Pj37020200023d180a0a876a11eaad60abc9d54aea48F20:8240980",
+            "BimLocation":"-106089.73,64853.35,92300.0"
+        }
+    ],
+    "Message":"接口失败会返回原因",
+    "PageNumber":1,
+    "PageSize":50,
+    "Result":"success",
+    "Total":1
+}
+```
+:::
+## 分页
+
+PageNumber 请求页码 Int 值 默认 1
+
+PageSize 请求条数 Int 值 默认 50 条
+
+通用接口中 PageSize 请求条数最大为 1000,为了避免大量的数据请求占用过多的资源,减少带宽
+
+## 过滤条件
+Filters 中编写过滤条件 例如:
+```metadata json ${2}
+{
+  "Filters": "ProjectId = 'Pj3702020002'; Category = 'FSSN' ",
+  "PageNumber": 1,
+  "PageSize": 50
+}
+```
+分号(;代表 and )还可以使用 and 来查询,例如:
+```metadata json ${2}
+{
+  "Filters": "ProjectId = 'Pj3702020002' and Category = 'FSSN' ",
+  "PageNumber": 1,
+  "PageSize": 50
+}
+
+```
+更多详细查询条件以及操作符使用参考 [ “过滤条件” 操作符介绍](./filters)
+
+## 排序
+Orders 排序,默认升序 asc 可以多字段排序,升序 asc  降序 desc,例如:
+
+```metadata json ${5}
+{
+  "Filters": "ProjectId = 'Pj3702020002' and Category = 'FSSN' ",
+  "PageNumber": 1,
+  "PageSize": 50,
+  "Orders": "EquipName, CreateTime desc"
+}
+```
+多字段排序从前往后依次按照 Orders 中的条件排序返回结果。
+
+## 指定应答属性
+Projection 指定后返回的属性,有些时候并不想把某些对象所有信息点都查出来,只是用几个属性,提高数据交互质量可以指定需要的属性,例如:
+```metadata json ${5-7}
+{
+  "Filters": "ProjectId = 'Pj3702020002' and Category = 'FSSN' ",
+  "PageNumber": 1,
+  "PageSize": 50,
+  "Projection": [
+      "EquipID","EquipName","EquipLocalId","EquipLocalName","Category"
+    ]
+}
+```
+如上面的请求体就会返回 Projection 中指定的属性
+
+## 去重
+数据统计的时候会用到这个功能,比如统计某一个楼层下有多少种设备类型
+``` json ${2}
+{
+  "Distinct": true,
+  "Filters": "ProjectId = 'Pj4101020002';FloorId = 'Fl410102000212f498f8128147a7bfdb853e80bd5596'",
+  "PageNumber": 1,
+  "PageSize": 50,
+  "Projection": [
+    "Category"
+  ]
+}
+```
+返回结果
+```metadata json
+{
+  "Content": [
+    {
+      "Category": "AEOV"
+    },
+    {
+      "Category": "ATFC"
+    }
+  ],
+  "Message": "",
+  "PageNumber": 1,
+  "PageSize": 2,
+  "Result": "success",
+  "Total": 20
+}
+```
+去重是不根据 Projection 指定返回的属性去重的,如果返回的字段中包含id,是无法去重的,因为id通常是唯一的,去重是根据指定返回的字段为一个从整体去重的。
+
+## 级联查询
+级联查询:在查询某一个对象的时候想要知道和这个对象有关系的有哪些对象,可以通过级联查询来操作,例如查询设备,以及所在的业务空间:
+请求体
+```json ${2-6}
+{
+  "Cascade": [
+    {
+      "Name": "zoneSpaceInBase"
+    }
+  ],
+  "Filters": "ProjectId = 'Pj1101020002' and EquipID = 'Eq11010200020321acc7e6f311e88ca4e5a21975b346' ",
+  "PageNumber": 1,
+  "PageSize": 50
+}
+```
+返回结果
+```metadata json
+{
+  "Content": [
+    {
+      "BuildingId": "Bd110102000223fbec0accfb11e8a471b5d1be3b6dfe",
+      "Category": "ATFU",
+      "CreateTime": "2019-06-19 12:57:11",
+      "EquipID": "Eq11010200020321acc7e6f311e88ca4e5a21975b346",
+      "EquipLocalID": "ATFU-TOP-N",
+      "EquipLocalName": "楼顶北新风机组",
+      "EquipName": "新风机组-E5L73",
+      "EquipQRCode": "9ca5b7b0daab49999d602ac4ccdcf105",
+      "LastUpdate": "2020-08-18 15:20:57",
+      "ProjectId": "Pj1101020002",
+      "ZoneSpaceBaseIn": [
+        {
+          "BuildingId": "Bd110102000223fbec0accfb11e8a471b5d1be3b6dfe",
+          "FloorId": "Fl1101020002fbdcd07ed5cb11e88bee4dbb551fd992",
+          "LastUpdate": "2020-07-17 17:17:19",
+          "ObjectType": "GeneralZone",
+          "ProjectId": "Pj1101020002",
+          "RoomFuncType": "311",
+          "RoomID": "Sp11010200024fdbd800e0aa11e88bee13864ca4ba47",
+          "RoomLocalID": "7F-A801-1",
+          "RoomLocalName": "A-801总裁室",
+          "RoomName": "空间-ISRWU",
+          "RoomQRCode": "2012bb68-2c9a-4bcc-a9a4-e0128634bf65"
+        }
+      ]
+    }
+  ],
+  "Message": "",
+  "PageNumber": 1,
+  "PageSize": 50,
+  "Result": "success",
+  "Total": 1
+}
+```
+ZoneSpaceBaseIn 中的数据就是当前设备所在的业务空间
+
+级联的关系数据也支持 Filters 条件查询 Orders 排序 Projection 指定返回的字段,去重 Distinct ,级联出来的空间对象内部还可以继续级联
+```
+{
+  "Cascade": [
+    {
+        "Cascade": [
+             "Name": "generalSystem"
+         ],
+      "Name": "zoneSpaceInBase"
+    }
+  ],
+  "Filters": "ProjectId = 'Pj1101020002' and EquipID = 'Eq11010200020321acc7e6f311e88ca4e5a21975b346' ",
+  "PageNumber": 1,
+  "PageSize": 50
+}
+```
+上面的例子是查询设备 ,设备坐在的业务空间,业务空间和系统的关系,返回结构和上面的类似,在空间的数据中会出现系统的实例数据
+
+## 综合示例
+查询某一楼层下的低压开关柜设备,使用创建时间加设备 ID 排序升序,指定返回字段为 EquipID EquipName Category EquipLocalID EquipLocalName
+返回数量为100条 ,顺便查出来设备所在的默认业务空间,设备下的部件,设备关联的资产,设备和竖井的关系实例,竖井指定返回id和名称,示例如下:
+
+```metadata json
+{
+  "Cascade": [
+    {
+      "Filters": "ObjectType = 'GeneralZone'",
+      "Name": "zoneSpaceInBase"
+    },
+    {
+      "Name": "component"
+    },
+    {
+      "Name": "property"
+    },
+     {
+      "Name": "shaft",
+        "Projection": [
+         "ShaftID", "ShaftName"
+         ]
+     }
+  ],
+  "Filters": "ProjectId = 'Pj4101020002';FloorId = 'Fl410102000212f498f8128147a7bfdb853e80bd5596'; Category = 'TDLS'",
+  "Orders": "CreateTime asc,EquipID asc",
+  "PageNumber": 1,
+  "PageSize": 50,
+  "Projection": [
+    "EquipID", "EquipName", "Category", "EquipLocalID", "EquipLocalName"
+  ]
+}
+```
+返回结果
+
+```metadata json
+{
+    "Content":[
+        {
+            "Category":"TDLS",
+            "EquipID":"Eq11010200020321acc7e6f311e88ca4e5a21975b346",
+            "EquipLocalID":"ATFU-TOP-N",
+            "EquipLocalName":"楼顶北低压开关柜",
+            "EquipName":"低压开关柜-E5L73",
+            "ZoneSpaceBaseIn":[
+                {
+                    "BuildingId":"Bd110102000223fbec0accfb11e8a471b5d1be3b6dfe",
+                    "FloorId":"Fl1101020002fbdcd07ed5cb11e88bee4dbb551fd992",
+                    "ObjectType":"GeneralZone",
+                    "ProjectId":"Pj1101020002",
+                    "RoomFuncType":"311",
+                    "RoomID":"Sp11010200024fdbd800e0aa11e88bee13864ca4ba47",
+                    "RoomLocalID":"7F-A801-1",
+                    "RoomLocalName":"A-801室",
+                    "RoomName":"空间-ISRWU",
+                }
+            ],
+            "component":[
+                {
+                    "Category":"TDLSDW",
+                    "EquipID":"Ec11010200020321acc7e6f311e88ca4e5a21975b303",
+                    "EquipLocalID":"ATFU-TOP-N-0",
+                    "EquipLocalName":"楼顶北低压开关柜抽屉"
+                }
+            ],
+            "property":{
+                "Category":"LSA",
+                "EquipID":"Pe11010200020321acc7e6f311e88ca4e5a21975b340",
+                "EquipLocalID":"ATFU-TOP-N",
+                "EquipLocalName":"楼顶北低压开关柜"
+            },
+            "shaftList":[
+                {
+                    "ShaftID":"Sh11010200020321acc7e6f311e88ca4e5a21975b349",
+                    "ShaftName":"楼梯间"
+                }
+            ]
+        }
+    ],
+    "Message":"",
+    "PageNumber":1,
+    "PageSize":50,
+    "Result":"success",
+    "Total":1
+}
+```
+
+
+