## 通用查询说明

### 1.数据结构

```
{
    "page": 1,
    "size": 20,
    "onlyCount": false,
    "criteria": {
        "age": {
            "$gt": 21
        }
    },
    "orders": [
        {
            "column": "name",
            "asc": false
        }
    ],
    "withColumns": [ "roles" ]
}
```

返回格式

1.data为数组格式

```json
{
    "result": "success",
    "data": [
        {
            "id": "dev_1",
            "groupCode": "PG",
            "type": "major",
            "name": "专业",
            "description": "Testing",
            "valid": 1,
            "creationTime": 1602434380000,
            "creator": "wdl",
            "modifiedTime": 1602705427000,
            "modifier": "wdl",
            "remark": "Testing"
        }
    ],
    "count": 1
}
```

2.data为对象格式

```json
{
    "result": "success",
    "data":{
            "id": "dev_1",
            "groupCode": "PG",
            "type": "major",
            "name": "专业",
            "description": "Testing",
            "status": 1,
            "creationTime": 1602434380000,
            "creator": "wdl",
            "modifiedTime": 1602705427000,
            "modifier": "wdl",
            "remark": "Testing"
    }
}
```

3.错误返回格式

```
{
    "result": "fail/其他错误码",
    "message":"***"
}
```

参数说明

| 字段        |          | 说明                                 |
| ----------- | -------- | ------------------------------------ |
| page        |          | 分页页码,从 1 开始                   |
| size        |          | 分页大小                             |
| onlyCount   |          | 是否只统计数量,默认 false            |
| criteria    |          | 查询条件                             |
| orders      | object[] | 排序参数,支持多个字段排序            |
|             | column   | 排序字段                             |
|             | asc      | 是否升序,默认 true                   |
| withColumns |          | 额外返回的扩展字段清单               |
| count       |          | **当分页时,该数表示数据总条数**      |
| result      |          | 详情见[错误码列表](/utils/common.md) |

### 2.criteria 说明

#### 符号说明

| 符号                     | 说明                                                         |
| ------------------------ | ------------------------------------------------------------ |
| \$ne                     | 不等于                                                       |
| \$gt, \$gte, \$lt, \$lte | 大于, 大于等于, 小于, 小于等于                               |
| \$in                     | 范围查询                                                     |
| \$like, \$notLike        | 模糊匹配 不匹配                                              |
| \$null                   | 是否为空                                                     |
| relationFrom             | 查询id作为obj_from的对象                                     |
| relationTo               | 查询id作为obj_to的对象                                       |
| $andOr                   | 类似AND (local_id LIKE "%temp%" OR local_name LIKE "%temp%") |
| $likeLeft                | 类似local_id LIKE "%temp"                                    |
| $likeRight               | 类似local_id LIKE "temp%"                                    |



以下实例针对的实体类型 user 如下

| 字段 | 类型   |
| ---- | ------ |
| id   | int    |
| name | string |
| age  | int    |

#### 相等

查询 name 为 zhangsan 的数据

```
{
    "criteria": {
        "name": "zhangsan"
    }
}
```

#### 不等于

查询 name 不等于张三的数据

```
{
    "criteria": {
        "name": {
            "$ne": "zhangsan"
        }
    }
}
```

#### 是否为空

查询 name 不为空的数据

```
{
    "criteria": {
        "name": {
            "$null": false
        }
    }
}
```

#### 比较大小

查询 age 大于 25 小于 35 的数据

```
{
    "criteria": {
        "age": {
            "$gt": 25,
            "$lt": 35
        }
    }
}
```

#### in 查询

查询 name 为 zhangsan、lisi 的数据

```
{
    "criteria": {
        "name": {
            "$in": [ "zhangsan", "lisi" ]
        }
    }
}
```

也可直接写成

```
{
    "criteria": {
        "name": [ "zhangsan", "lisi" ]
    }
}
```

#### 模糊查询

```
// $like
// 查询 name 含有 zh 的数据
{
    "criteria": {
        "name": {
            "$like": "zh"
        }
    }
}
// $likeLeft
// 查询 name 以 zh 结尾的数据
{
    "criteria": {
        "name": {
            "$likeLeft": "zh"
        }
    }
}
//$likeRight
// 查询 name 以 zh 开头的数据
{
    "criteria": {
        "name": {
            "$likeRight": "zh"
        }
    }
}
```

#### relationFrom

> 仅支持/rwd/instance/object/query接口查询

查询 objTo 为Sp5001120003566c821e83b84a84bc17ecf7290d261b的数据

```
// 多个查询
{
    "criteria": {
        "relationFrom": {
            "graphCode": ["MechForArch"],
            "relCode": ["Eq2Sp"],
            "objTo":["Sp5001120003566c821e83b84a84bc17ecf7290d261b"]
        }
    }
}
// 单个查询
{
    "criteria": {
        "relationFrom": {
            "graphCode": "MechForArch",
            "relCode": "Eq2Sp",
            "objTo":"Sp5001120003566c821e83b84a84bc17ecf7290d261b"
        }
    }
}
```

#### relationTo

> 仅支持/rwd/instance/object/query接口查询

查询 objFrom 为Eq5001120003c1192002bf9646c4b64077a6b0f283ab的数据

```
// 多个查询
{
    "criteria": {
        "relationTo": {
            "graphCode": ["MechForArch"],
            "relCode": ["Eq2Sp"],
            "objFrom":["Eq5001120003c1192002bf9646c4b64077a6b0f283ab"]
        }
    }
}
// 单个查询
{
    "criteria": {
        "relationTo": {
            "graphCode": "MechForArch",
            "relCode": "Eq2Sp",
            "objFrom":"Eq5001120003c1192002bf9646c4b64077a6b0f283ab"
        }
    }
}
```

#### $andOr 查询

模糊查询本地名称或本地id为P2的对象

```
{
    "criteria": {
        "$andOr": {
            "localId": {"$like":"P2"},
            "localName": {"$like":"P2"}
        }
    }
}
```





### 3.withColumns 说明

通过 withColumns 可以控制返回的数据内容,可以一定程度上提供服务性能.

withColumns 粒度比较粗,一般由服务提供者决定哪些字段可以通过 withColumns 来控制.

假设数据如下

```
{
    "name": "zhangsan",
    "age": 22,
    "roles": [ "administrator", "manager" ]
}
```

将 roles 设计为可选字段,由 withColumns 来管理,如果查询参数中有 withColumns 并包含 roles,则返回 roles 字段

默认查询和返回的数据内容为

```
{
    "criteria": {
        "name": "zhangsan"
    }
}
```

```
{
    "name": "zhangsan",
    "age": 22
}
```

包含 withColumns 时的查询参数和返回的数据

```
{
    "criteria": {
        "name": "zhangsan"
    },
    "withColumns": [ "roles" ]
}
```

```
{
    "name": "zhangsan",
    "age": 22,
    "roles": [ "administrator", "manager" ]
}
```

### 4.物理世界对象信息点相关查询

#### \$search

特别说明:

```
1.业务含义不可靠,目前除"查询绑定了某个表号功能号的对象"这一个场景外暂时没有合理使用该查询的业务场景
2.性能差!性能差!性能差!
```

```json
{
    "criteria": {
        "$search": "关键字"
    }
}
```

```
1.直接放在criteria下,只能对字符串字段进行查询
2.支持通配符%, 如"%abc%"将返回信息点的值中包含abc的对象
3.固定字段(id,localId,name,localName,classCode...等)无效
4.信息点的值可能是对象,若对象的属性符合条件则该对象也将被返回
```

#### 数组查询 \$contains \$notcontains

特别说明:

```
1.业务含义不可靠,使用该查询之前务必搞清楚自己的目的是什么
2.性能差!性能差!性能差!
```

```json
{
    "criteria": {
        "arr": {
            "$contains": "1"
        },
        "arr2": {
            "$contains": [1, 3, 5]
        }
    }
}
```

```
1.直只能对复数信息点进行查询
2.只要数组包含条件对应的值即查询条件成立,如[1,2,3]对1成立, [1,2,3]对[1,2]成立, [[1,2,3], [4,5,6]]对[1]成立, [[1,2,3], [4,5,6]]对[1,2]成立,[[1,2,3], [4,5,6]]对[1,5]成立
3.固定字段(id,localId,name,localName,classCode...等)无效
4.$notcontains含义与$contains相反,但是首先要求查询字段有值
```



## 错误码列表

|错误码|中文描述|补充说明|
| ---- | ---- | ---- |
|success|一切ok| 00000      |
|fail|失败| 10000      |
|A0001|用户端错误||
|A0100|用户注册错误||
|A0101|用户未同意隐私协议||
|A0102|注册国家或地区受限||
|A0110|用户名校验失败||
|A0111|用户名已存在||
|A0112|用户名包含敏感词||
|A0113|用户名包含特殊字符||
|A0120|密码校验失败||
|A0121|密码长度不够||
|A0122|密码强度不够||
|A0130|校验码输入错误||
|A0131|短信校验码输入错误||
|A0132|邮件校验码输入错误||
|A0133|语音校验码输入错误||
|A0135|Method Not Allowed||
|A0136|Unsupported Media Type||
|A0137|Not Acceptable||
|A0140|用户证件异常||
|A0141|用户证件类型未选择||
|A0142|大陆身份证编号校验非法||
|A0143|护照编号校验非法||
|A0144|军官证编号校验非法||
|A0150|用户基本信息校验失败||
|A0151|手机格式校验失败||
|A0152|地址格式校验失败||
|A0153|邮箱格式校验失败||
|A0154|账号名称重复||
|A0155|员工编号重复||
|A0156|手机号重复||
|A0157|邮箱重复||
|A0200|用户登录异常||
|A0201|用户账户不存在||
|A0202|用户账户被冻结||
|A0203|用户账户已作废||
|A0210|用户/密码错误||
|A0211|用户输入密码错误次数超限||
|A0220|用户身份校验失败||
|A0221|用户指纹识别失败||
|A0222|用户面容识别失败||
|A0223|用户未获得第三方登录授权||
|A0230|用户登录已过期||
|A0240|用户验证码错误||
|A0241|用户验证码尝试次数超限||
|A0300| 访问权限异常二级宏观错误码| |
|A0301|访问未授权||
|A0302|正在授权中||
|A0303|用户授权申请被拒绝||
|A0310|因访问对象隐私设置被拦截||
|A0311|授权已过期||
|A0312| 无权限使用API| |
|A0320|用户访问被拦截||
|A0321|黑名单用户||
|A0322|账号被冻结||
|A0323| 非法 IP地址| |
|A0324|网关访问受限||
|A0325|地域黑名单||
|A0330|服务已欠费||
|A0340|用户签名异常||
|A0341|RSA签名错误||
|A0400|用户请求参数错误||
|A0401|包含非法恶意跳转链接||
|A0402|无效的用户输入||
|A0410|请求必填参数为空||
|A0411|用户订单号为空||
|A0412|订购数量为空||
|A0413|缺少时间戳参数||
|A0414|非法的时间戳参数||
|A0420|请求参数值超出允许的范围||
|A0421|参数格式不匹配||
|A0422|地址不在服务范围||
|A0423|时间不在服务范围||
|A0424|金额超出限制||
|A0425|数量超出限制||
|A0426|请求批量处理总个数超出限制||
|A0427|请求JSON解析失败||
|A0430|用户输入内容非法||
|A0431|包含违禁敏感词||
|A0432|图片包含违禁信息||
|A0433|文件侵犯版权||
|A0440|用户操作异常||
|A0441|用户支付超时||
|A0442|确认订单超时||
|A0443|订单已关闭||
|A0500|用户请求服务异常||
|A0501|请求次数超出限制||
|A0502|请求并发数超出限制||
|A0503|用户操作请等待||
|A0504|WebSocket连接异常||
|A0505|WebSocket连接断开||
|A0506|用户重复请求||
|A0600|用户资源异常||
|A0601|账户余额不足||
|A0602|用户磁盘空间不足||
|A0603|用户内存空间不足||
|A0604|用户OSS容量不足||
|A0605|用户配额已用光||
|A0700|用户上传文件异常||
|A0701|用户上传文件类型不匹配||
|A0702|用户上传文件太大||
|A0703|用户上传图片太大||
|A0704|用户上传视频太大||
|A0705|用户上传压缩文件太大||
|A0800|用户当前版本异常||
|A0801|用户安装版本与系统不匹配||
|A0802|用户安装版本过低||
|A0803|用户安装版本过高||
|A0804|用户安装版本已过期||
|A0805|用户API请求版本不匹配||
|A0806|用户API请求版本过高||
|A0807|用户API请求版本过低||
|A0900|用户隐私未授权||
|A0901|用户隐私未签署||
|A0902|用户摄像头未授权||
|A0903|用户相机未授权||
|A0904|用户图片库未授权||
|A0905|用户文件未授权||
|A0906|用户位置信息未授权||
|A0907|用户通讯录未授权||
|A1000|用户设备异常||
|A1001|用户相机异常||
|A1002|用户麦克风异常||
|A1003|用户听筒异常||
|A1004|用户扬声器异常||
|A1005|用户GPS定位异常||
|B0001|系统执行出错||
|B0100|系统执行超时||
|B0101|系统订单处理超时||
|B0200|系统容灾功能被触发||
|B0210|系统限流||
|B0220|系统功能降级||
|B0300|系统资源异常||
|B0310|系统资源耗尽||
|B0311|系统磁盘空间耗尽||
|B0312|系统内存耗尽||
|B0313|文件句柄耗尽||
|B0314|系统连接池耗尽||
|B0315|系统线程池耗尽||
|B0320|系统资源访问异常||
|B0321|系统读取磁盘文件失败||
|C0001|调用第三方服务出错||
|C0100|中间件服务出错||
|C0110|RPC服务出错||
|C0111|RPC服务未找到||
|C0112|RPC服务未注册||
|C0113|接口不存在||
|C0120|消息服务出错||
|C0121|消息投递出错||
|C0122|消息消费出错||
|C0123|消息订阅出错||
|C0124|消息分组未查到||
|C0130|缓存服务出错||
|C0131|key长度超过限制||
|C0132|value长度超过限制||
|C0133|存储容量已满||
|C0134|不支持的数据格式||
|C0140|配置服务出错||
|C0150|网络资源服务出错||
|C0151|VPN服务出错||
|C0152|CDN服务出错||
|C0153|域名解析服务出错||
|C0154|网关服务出错||
|C0200|第三方系统执行超时||
|C0210|RPC执行超时||
|C0220|消息投递超时||
|C0230|缓存服务超时||
|C0240|配置服务超时||
|C0250|数据库服务超时||
|C0300|数据库服务出错||
|C0311|表不存在||
|C0312|列不存在||
|C0320|数据不存在||
|C0321|多表关联中存在多个相同名称的列||
|C0331|数据库死锁||
|C0341|主键冲突||
|C0400|第三方容灾系统被触发||
|C0401|第三方系统限流||
|C0402|第三方功能降级||
|C0500|通知服务出错||
|C0501|短信提醒服务失败||
|C0502|语音提醒服务失败||
|C0503|邮件提醒服务失败||
|Z9999|系统繁忙|兜底错误码|



## 码表类型(知识库类型)

| 编码(code,接口中使用的typeCode) | 类型说明           |
| ------------------------------- | ------------------ |
| geography                       | 省市信息           |
| equipment_all                   | 设备类型           |
| equipment_family                | 种族类型           |
| climate                         | 气候区             |
| develop                         | 发展水平           |
| weather                         | 天气状态           |
| wind                            | 空气风力等级       |
| direction                       | 方位信息           |
| building                        | 建筑功能类型       |
| space                           | 空间功能类型       |
| rental                          | 租赁业态           |
| dustproof                       | 防尘等级           |
| waterproof                      | 防水等级           |
| explosionproof_equipment        | 防爆设备类型       |
| explosionproof_type             | 防爆类型           |
| danger                          | 危险区域等级       |
| gas_temperature                 | 气体类型和温度类型 |
| pollution_level                 | 污染等级           |
| contamination_level             | 污秽等级           |
| standard_energy_item            | 标准分项           |
| seismic_precautionary_intensity | 抗震设防烈度       |
| virtual_object                  | 虚拟对象类型       |
| calendar_tag                    | 日历标签           |
| calendar_interval               | 日历时间段         |
| consumable_all                  | 耗材编码           |
| tool_all                        | 工具编码           |



## 对象类型(对应objType字段)

| 编码      | 说明     |
| --------- | -------- |
| project   | 项目     |
| building  | 楼       |
| floor     | 楼层     |
| space     | 空间     |
| system    | 系统     |
| equipment | 设备     |
| shaft     | 竖井     |
| component | 部件     |
| virtual   | 虚拟对象 |
| tool      | 工具     |
| material  | 耗材     |