开发说明

docs/dev/lib/coding/README.md

@@ -15,7 +15,7 @@
       
 ![开发 dev](./img/dev_003.jpg)
 
-![开发 dev](./img/dev_002.jpg)  
+![开发 dev](./img/dev_002.jpg)
       
 * Json注解（FastJson）
     * 首字母大小不同，不需要加注解。数据字典定义的首字母大写，实体类属性名的首字母小写（按java命名规范），由应用程序统一控制输出的json属性首字母大写；
@@ -35,14 +35,201 @@
 ## 控制类规范
 
 ::: details 查看代码
-<<< @/docs/dev/lib/coding/src/PropertyController
+<<< @/docs/dev/lib/coding/src/PropertyController.kt
 :::
 
+标准的通用接口，增删改查统计
 
+### 控制类注解说明 
+![开发 dev](./img/dev_005.jpg)
 
-#### 控制类 、service 规范
-#### 接口使用方式、调用，函数调用，自定义函数使用
+* 类使用/** */加注释，不可以使用 //。类对象的注释必需添加作者。
+* @Api 在接口文档 swagger 中显示每个对象控制类说明， 并写明当前控制类的作用，代码中书写 @Api 上面代码示例，swagger 显示如下：
 
+![开发 dev](./img/dev_004.jpg)
 
+* @RestController 和 @RequestMapping 是spring 提供的控制类注解，不理解的可以参看 是spring boot注解介绍
+
+![开发 dev](./img/dev_006.jpg)
+
+* 接口函数和类注释一样使用/** */加注释，在注解中一定要写明函数入参的作用，返回的结果
+* 接口注解 @ApiOperation 为配合 swagger 显示接口的描述作用在，@ApiOperation 注解里面有 notes 后面可以书写项目的接口说明以及注意事项
+* 接口注解 @PostMapping 设备接口的请求方式为 post 并映射接口名， 接口使用 @GetMapping 还是 @PostMapping 根据需求 使用 @PostMapping
+
+### 控制类接口
+#### 创建接口
+![开发 dev](./img/dev_006.jpg)
+
+* SCreateRequest 创建请求体基类，所有对象统一创建请求体结构
+
+![开发 dev](./img/dev_008.jpg)
+
+* SCreateResponse 应答体基类，统一返回数据结构，创建接口创建成功会把创建的对象返回
+
+![开发 dev](./img/dev_009.jpg)
+
+#### 删除接口
+![开发 dev](./img/dev_010.jpg)
+
+* idList: ArrayList\<Property\> 请求体对象列表，只需要填写对象 id 即可或填写对象主键
+* SBaseResponse 标准的应答基类，在不需要附带参数的时候使用
+
+![开发 dev](./img/dev_011.jpg)
+
+#### 修改接口
+![开发 dev](./img/dev_012.jpg)
+
+* SUpdateRequest 修改接口请求基类，统一修改对象的请求体 ，修改对象属性可以指定属性来修改，在 projection 指定修改的属性，置空
+
+![开发 dev](./img/dev_013.jpg)
+
+修改接口支持级联修改，例如修改设备信息，同时修改设备所在的业务空间信息，修改业务空间对应的竖井信息，修改设备对那个的部件的部件信息，支持 n 级修改
+
+#### 查询
+![开发 dev](./img/dev_014.jpg)
+
+* SQueryRequest 请求体基类，所有的标准接口都是用相同的基类，分页、去重 、分组、排序、级联查询 、操作符关系符查询，指定返回属性查询，设置请求返回最大数
+::: details 查看代码
+<<< @/docs/dev/lib/coding/src/SQueryRequest.kt
+:::
+
+* SQueryResponse 查询应答基类 返回数据包括 请求页码 请求条数，符合条件的总数量，数据列表 继承自 SBaseResponse 返回成功标志
+
+![开发 dev](./img/dev_015.jpg)
+
+### 统计查询
+
+![开发 dev](./img/dev_016.jpg)
+
+* SCountRequest 统计请求基类，在 filters 中写查询条件
+
+![开发 dev](./img/dev_017.jpg)
+
+* SCountResponse 统计应答基类，只返回统计的数量以及应答装填
+
+![开发 dev](./img/dev_018.jpg)
+
+::: warning 注意 
+控制类中只写基本的接口函数定义，不允许有逻辑代码，控制类只做接口定义以及说明
+:::
+
+
+
+## service 规范
+![开发 dev](./img/dev_007.jpg)
+* 类SObjectService封装了标准的增删改查统计操作，标准操作可以直接使用该类,可以做为接口的标准接口的通用服务类,对于只有标准操作的对象，只需要写好实体类操作类及相关注释即可
+* 这里入参使用Property::class.java是因为泛型在编译时使用，运行时泛型信息将被擦除
+### 扩展标准接口 service 中代码逻辑
+* SObjectService 提供的标准增删改查统计，都可以在执行前或执行后做相应大逻辑操作,定义一个 BuildingService 继承自 SObjectService 然后在 BuildingService 重写对应的函数例如：
+
+![开发 dev](./img/dev_019.jpg)
+
+* 标准接口都会提供对应的 Before 和 Success 的函数可以重写，作相应的逻辑处理
+
+![开发 dev](./img/dev_020.jpg)
+* 自定义方法，然后调用 SObjectService 提供的 select insert replace update delete 
+```metadata json
+fun equipInfo(building: Building){
+        // 插入数据
+        insert(building)
+        // 替换，有则替换，无则创建
+        replace(building)
+        // 更新
+        update(building)
+        // 删除
+        delete(building)
+        // 查询
+        select(SFilter.eq("id","123456")).entity()
+    } // Fun
+```
+#### 扩展接口使用
+* insert 插入，直接传入插入的数据会返回 Boolean 布尔值 false 或 true，传入的对象一定是 BuildingService 注解一致的
+```metadata json
+        // 插入数据
+        val insert = insert(building)
+```
+* replace 替换和插入一样返回布尔值，是否成功传入对象也相同
+* update 同样会返回布尔值，传入的对象一样，也可以输入条件更新，或只更新某一个或某几个属性
+```metadata json
+        // 更新
+        update(building)
+        // 根据条件更新
+        update(building,null, SFilter.eq("projectId","Pj1101060001"))
+        // 指定更新属性
+        update(building, arrayListOf("name"), SFilter.eq("projectId","Pj1101060001"))
+```
+* delete 删除 可以指定条件传出，也可以直接删除某一个对象
+
+```metadata json
+        // 删除
+        delete(building)
+        //指定条件删除
+        delete(SFilter.eq("equipId","Eq110106000145984513212132"))
+        // 多条件删除
+        delete(SFilter.eq("name","大厦"),SFilter.eq("type",1))
+```
+
+* select 查询可以多条件组合，利用下面要介绍的表达式、逻辑表达式、函数。
+```metadata json
+        // 查询 单条件,可以在 BuildingService类外调用 如下
+        BuildingService.select(SFilter.eq("id","123456")).exec()
+        //  entity 代表返回单条数据  exec 返回一个列表
+        // 多条件查询
+        select(SFilter.eq("name","123456"),SFilter.eq("projectId","Pj1101060001")).exec()
+``` 
+ 
+
+
+### 关系表达式
+| 关系 | 后台语法 |
+|:--:|:--:|:--:|
+| 等于 | SFilter.eq(“属性名”, 值) |
+| 不等于 | SFilter.ne(“属性名”, 值) |
+| 大于 | SFilter.gt(“属性名”, 值) |
+| 大于等于 | SFilter.gte(“属性名”, 值) |
+| 小于 | SFilter.lt(“属性名”, 值) |
+| 小于等于 | SFilter.lte(“属性名”, 值) |
+| 包含 | SFilter.contain(“属性名”, 值) |
+| 前缀 | SFilter.startwith(“属性名”, 值) |
+| 后缀 | SFilter.endwith(“属性名”, 值) |
+| 为空 | SFilter.isnull(“属性名”) |
+| 在列表内 | SFilter.inList(“属性名”, arrayList(值1, 值2, ...)) |
+
+* 使用示例：查询 id 为 123456 的 对象
+```metadata json
+BuildingService.select(SFilter.eq("id","123456")).exec()
+```
+
+### 逻辑表达式
+| 逻辑 | 后台语法 |
+|:--:|:--:|
+| 非 | SFilter.not(表达式) |
+| 与 | SFilter.and(表达式1, 表达式2) |
+| 或 | SFilter.or(表达式1, 表达式2) |
+
+* 示例：查询 type 类型为 1 或 2 的对象
+```metadata json
+BuildingService.select(SFilter.or(SFilter.eq("type","1"),SFilter.eq("type","2"))).exec()
+```
+
+### 函数
+| 函数 | 说明 |
+|:--:|:--:|
+| SLeft(属性名, 长度) | 字符串左截取 |
+| SLength(属性名) | 取字符串长度 |
+| SLower(属性名) | 字符串转换为小写 |
+| SLPad(属性名, 长度, 填充字符) | 左填充字符串 |
+| SMid(属性名, 开始位置, 长度) | 从指定位置截取批暄长度字符串 |
+| SReverse(属性名) | 字符串逆序 |
+| SRight(属性名, 长度) | 字符串右截取 |
+| SRPad(属性名, 长度, 填充字符) | 右填充字符串 |
+| SSubstring(属性名, 开始位置, 长度) | 从指定位置截取批暄长度字符串 |
+| SUpper(属性名) | 字符串转换为大写 |
+
+示例 ：查询名称长度等于4个字符
+```
+BuildingService.select(SFilter.eq(SLength("name"),4)).exec()
+```
+#### 自定义函数 
 
 标准化 实体类、接口类 ，减少开发工作量，以及开发代码量

docs/dev/lib/coding/src/SQueryRequest.kt

@@ -0,0 +1,67 @@
+
+import com.persagy.database.SGroup
+import com.persagy.service.models.SCascadeQuery
+import io.swagger.annotations.ApiModel
+import io.swagger.annotations.ApiModelProperty
+
+/**
+ * 查询请求对象基类
+ *
+ * @author  庞利祥 <sybotan@126.com>
+ */
+@ApiModel(description = "查询请求对象基类")
+open class SQueryRequest {
+    companion object {
+        /** 设置接口一次可取得的最大记录数 */
+        var maxRow = 1000
+    } // Companion object
+
+    /** 第几页 */
+    @ApiModelProperty(value = "第几页(从1开始)", example = "1")
+    var pageNumber: Int = 1
+        set(value) {            // 限定pageNumber不能小于1
+            field = value
+            if (value < 1) {
+                field = 1
+            }
+        }
+
+    /** 每页记录数 */
+    @ApiModelProperty(value = "每页记录数(0 < 记录数 < 1000)", example = "50")
+    var pageSize: Int = 50
+        set(value) {            // 限定pageSize不能小于1且不能大于maxRow
+            field = value
+            if (value < 1 ) {
+                field = 1
+            }
+            if (value > maxRow) {
+                field = maxRow
+            }
+            // maxRow一次设置有效，之后将自动设备为1000
+            maxRow = 1000
+        }
+
+    /** 查询条件 */
+    @ApiModelProperty(value = "查询条件")
+    var filters: String? = null
+
+    /** 排序条件 */
+    @ApiModelProperty(value = "排序条件", example = "name asc, createTime desc")
+    var orders: String? = null
+
+    /** 去除重复记录 */
+    @ApiModelProperty(value = "去除重复记录")
+    var distinct: Boolean? = null
+
+    /** 字段影射，空为查询所有字段 */
+    @ApiModelProperty(value = "字段影射，空为查询所有字段")
+    var projection: ArrayList<String>? = null
+
+    /** 级联对象列表 */
+    @ApiModelProperty(value = "级联对象列表")
+    var cascade: ArrayList<SCascadeQuery>? = null
+
+    /** 分组统计 */
+    @ApiModelProperty(value = "分组")
+    var group: SGroup? = null
+} // Class SQueryRequest

docs/dev/lib/coding/src/build.gradle

@@ -1,42 +0,0 @@
-
-group 'cn.sagacloud.server'
-version '2.0.0'
-
-buildscript {
-    repositories {
-        maven{url MAVEN_REPO_PUBLIC_URL}
-        maven{ url "http://maven.aliyun.com/nexus/content/groups/public/"}
-        mavenCentral()
-        jcenter()
-    }
-    dependencies {
-        classpath group: 'org.springframework.boot', name: 'spring-boot-gradle-plugin', version: SPRING_BOOT_VERSION
-        classpath group: 'org.jetbrains.kotlin', name: 'kotlin-gradle-plugin', version: KOTLIN_VERSION
-        classpath group: 'org.jetbrains.dokka', name: 'dokka-gradle-plugin', version: DOKKA_VERSION
-        classpath group: 'com.google.protobuf', name: 'protobuf-gradle-plugin', version: PROTOBUF_GRADLE_VERSION
-        // ssh插件, 用于部署
-        classpath 'org.hidetake:gradle-ssh-plugin:2.10.1'
-    }
-}
-
-allprojects {
-    repositories {
-        maven{ url "http://maven.aliyun.com/nexus/content/groups/public/"}
-        maven{
-            url MAVEN_REPO_PUBLIC_URL
-            credentials {
-                username = NEXUS_USERNAME
-                password = NEXUS_PASSWORD
-            }
-        }
-        maven { url "https://repo.spring.io/milestone" }
-        mavenCentral()
-        jcenter()
-    }
-    tasks.withType(Javadoc) {
-        options{ encoding "UTF-8"
-            charSet "UTF-8"
-            links "http://docs.oracle.com/javase/8/docs/api"
-        }
-    }
-}

docs/dev/lib/coding/src/propertycontroller.kt

@@ -1,23 +1,3 @@
-/*
- * ********************************************************************************************************************
- *
- *                     :*$@@%$*:                         ;:                ;;    ;;
- *                   :@@%!  :!@@%:                       %!             ;%%@@%$ =@@@@@@@%;     @%@@@%%%%@@@@@
- *                  :@%;       :$=                       %%$$$%$$         ;$$  ;$@=   !@$
- *                  =@!                                  %!              @ $=;%   !@@@%:      !$$$$$$$$$$$$$$=
- *                  =@*                                  %!              @ $= % %@=   =%@!      %=
- *             *$%%! @@=        ;=$%%%$*:                %!              @ $= % =%%%%%%@$      *%:         =%
- *           %@@!:    !@@@%=$@@@@%!  :*@@$:              %!              @ $= % $*     ;@      @*          :%*
- *         ;@@!          ;!!!;:         ;@%:      =======@%========*     @ $$ % $%*****$@     :@$=*********=@$
- *         $@*   ;@@@%=!:                *@*
- *         =@$    ;;;!=%@@@@=!           =@!
- *          %@$:      =@%: :*@@@*       %@=                    Copyright (c) 2016-2019.  北京上格云技术有限公司
- *           ;%@@$=$@@%*       *@@@$=%@@%;
- *              ::;::             ::;::                                              All rights reserved.
- *
- * ********************************************************************************************************************
- */
-
 package cn.sagacloud.server.datacenter.controllers
 
 import cn.sagacloud.server.datacenter.models.entities.Property
@@ -50,10 +30,6 @@ import org.springframework.web.bind.annotation.RestController
 @RestController
 @RequestMapping("/object/property")
 open class propertycontroller {
-    companion object {
-        /** 日志 */
-        private val logger = LoggerFactory.getLogger(PropertyController2::class.java)
-    } // Companion object
 
     /**
      * 创建资产

docs/dev/lib/index.js

@@ -1,7 +1,7 @@
 const content = [
     {
         title: "系统架构介绍",
-        path: "/dev/lib/coding/"
+        path: "/dev/lib/system/"
     },
     {
         title: "web接口",

docs/dev/lib/system/README.md

@@ -0,0 +1,40 @@
+# 系统架构
+## 主要问题
+* 接口标准化，各对象支持标准的增删改查。查询支持过滤、排序、映射、分页等标准操作；
+* 标准化的代码不需要重复开发。框架支持以最少的代码完成增删改查，只需要写好实体类与controller接口类即可。实现描述型开发
+
+## 有什么内容
+* 数据库、jdbc驱动、Mybatis
+* kotlin/java、Javacc
+* 注解、泛型、反射
+
+* 接口层
+定义与App之间的接口。定义功能与功能的访问地址，入参，返回值；
+* 服务层
+在该层将启动事物支持，
+* 数据访问层
+
+## 数据结构中使用json
+* 支持json是为了解决设备、部件、资产时信息点不同问题的；
+* 横表存储，一般对象（字段固定）的存储采用的是横表；
+    * 优点：数据库标准支持，查询速度快；
+    * 缺点：动态改字段
+* 竖表存储
+    * 优点：采用字段/值的方式存储，增删字段没任何压力；
+    * 缺点：值类型受限，不利于做复杂的查询。对null支持不好；
+* Json存储
+    * MySQL、PostgreSQL、Oracle、SQLServer都支持Json存储了；
+    * 可以使用SQL语句直接对Json字段中的内容进行增删改查；
+    * 属性可以分组，做成树型结构。符合数据字典的定义格式；
+
+## 映射
+* 在具体的页面，查询数据时大多数时间不需要对象的所有属性；
+* 使用Projection可以指定请求的属性列表。例如只取id与名称，则“Projection”：[“id”，“name”];
+* 映射不支持json；
+
+
+
+
+
+
+

docs/dev/lib/web/README.md

@@ -31,6 +31,15 @@
 * 查询条件灵活的多样的
 * 专为应用服务的后台，比如数据中心就是围绕着物理世界或中台的壳，面向应用友好，主要针对应用和APP的需求，解决物理世界或中台对应用适配的问题
 
+## Web接口注意事项
+* 属性名不加引号且属性名不区分大小写；name与NAME代表相同的属性。
+* 属性名指的是实体类的属性名，不是指数据库的字段名（框架在操作数据库时，会自动将属性名转换为字段名）。
+* 数值型值、布尔型值，在写表达式时不需要写引号；
+* 字符串型值、日期型值，在写表达式时要写上单引号；
+* 表达式“包含”，“前缀”，“后缀”只用于字符串型属性；
+* 在“列表内”表达式，列表内的每个值的类型必须一致，否则会抛出异常；
+
+
 
 
 

docs/dev/lib/web/count.md

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

docs/dev/lib/web/create.md

@@ -1,5 +1,6 @@
 # 创建
 ### 创建实体对象
+![web dev](./img/web-swager_007.jpg)
 例如创建设备实体对象：
 ```metadata json
 {
@@ -20,7 +21,6 @@
   "EntityList": [
     {
       "Category": "TDLS",
-      "CodeType": 1,
       "EquipID": "Eq1102290001e2a2b859d59347af99649f7d234384d0",
       "EquipLocalID": "ATFU-TOP-N-003",
       "EquipLocalName": "低压开关柜-A03",

docs/dev/lib/web/delete.md

@@ -1,6 +1,7 @@
 # 删除
 ## 删除数据
-例如删除某一个设备
+![web dev](./img/web-swager_007.jpg)
+例如删除设备
 ```
 [
     {

docs/dev/lib/web/filters.md

@@ -98,13 +98,15 @@
 ```
 
 #### 前缀
-* 字符串类型，例如设备 id 是以 Eq 开头，空间id是以 Sp 开头，区分设备和空间就需要根据前缀来获取
+只适用于字符串类型
+例如设备 id 是以 Eq 开头，空间id是以 Sp 开头，区分设备和空间就需要根据前缀来获取
 ```metadata json
 "Filters":" Id startwith 'Eq'"
 ```
 
 #### 后缀
-* 字符串类型，例如楼层的 FloorMap 信息点是存储底图 key 值的，可能是 jsonz 压缩数据的 key ,也可能是 png 、jpg，查询后缀为 jsonz 的楼层数据
+只适用于字符串类型
+例如楼层的 FloorMap 信息点是存储底图 key 值的，可能是 jsonz 压缩数据的 key ,也可能是 png 、jpg，查询后缀为 jsonz 的楼层数据
 ```metadata json
 "Filters":" floorMap endwith 'jsonz'"
 ```
@@ -116,8 +118,8 @@
 ```
 
 #### 在...内
-通常查询的时候会根据同一条件的多个值来获取数据。
-* 字符串类型 例如有一组设备的id列表，查询值这个把列表中的所有设备 ['id1','id2','id3','id4','id5']
+通常查询的时候会根据同一条件的多个值来获取数据,只适用于字符串类型
+例如有一组设备的id列表，查询值这个把列表中的所有设备 ['id1','id2','id3','id4','id5']
 ```metadata json
 "Filters":" EquipID in ['id1','id2','id3','id4','id5'] "
 ```

docs/dev/lib/web/query.md

@@ -1,5 +1,6 @@
 # 查询
 ## 请求体 json
+![web dev](./img/web-swager_009.jpg)
 ::: details 查看代码
 ```
 {

docs/dev/lib/web/update.md

@@ -1,6 +1,8 @@
 # 修改
 
 ## 修改信息
+
+![web dev](./img/web-swager_010.jpg)
 修改数据信息支持整体数据覆盖，或只更新某几个或一个字段，或某几个或一个字段置空 例如修改设备数据
 ```metadata json
 {