# 物模块

统一定义物管理相关接口以及相应的默认实现。

名称解释:

1. 物类型(`ThingType`): 对一系列业务上可能需要的功能的定义,例如: 设备,建筑,楼层,车间.都可以定义为物。
2. 物模版(`ThingsTemplate`): 对一类物的统一定义,用于统一配置物模型等通用配置。
3. 物模型(`ThingMetadata`): 对物的描述,主要由`属性`,`功能`,`事件`组成。
4. 物实例(`Thing`): 具体的某一个物,通常与现实中的一个物体对应。
5. 物注册中心(`ThingsRegistry`): 统一管理物模版和物实例配置等信息。
6. 物消息(`ThingMessage`): 物消息的统一定义，如: 属性上报,读写属性,调用功能等。
7. 连接器(`ThingsConnector`),用于提供对物消息的支持, 通过不同的连接器来实现自定义的消息来源,例如: 从另外的物中订阅实时属性,并经过计算后作为新消息,消息最终会以
   事件驱动的方式传递到内部的事件总线,通过事件总线可以灵活的处理这些消息。
8. 消息转换器(`ThingMessageConverter`),用于对连接器返回的数据或者对将要下发对指令进行转换,例如:
   定义消息模版,在消息中可以使用表达式来获取上游的变量来实现动态指令参数.
9. RPC支持(`ThingRpcSupport`),用于提供物RPC的支持,例如: 读写属性,调用功能.

## 最佳实践

物是一个虚拟的概念,在实际应用时,应该明确定义物类型,在使用时,建议基于对应的物类型进行相应的业务功能实现. 例如: 平台根据实际场景,定义好固定的物类型，如: 设备(`平台默认已内置了此类型`),建筑物,楼层,房间.
并声明这些物类型所需要的配置信息,标签定义,这些定义可以由前端写死,也可以由后端动态维护，前端根据配置动态 渲染对应的页面. 最终调用平台统一的物管理接口来实现管理.

## 内置连接器

此模版内置常用的连接器,自定义连接器请实现接口`ThingsConnectorProvider`

### 物属性

用于连接物的属性，通常用于将其他物的属性作为当前物的属性值. 实现类`ThingPropertiesMessageConnector`

支持的物模型类型: `属性` 将指定的物的属性转为新的物属性消息(`ThingReportPropertyMessage`)

配置格式:

```json5
{
  "provider": "thing-property",
  "configuration": {
    "thingType": "物类型ID",
    "templateId": "模版ID",
    "thingId": "物实例ID",
    "properties": [
      "属性ID"
    ],
     "converter": {
        "provider": "",
        "configuration": {
           //见消息转换器说明
        }
     },
    "filter": [
      {
        //列字段,与ThingEventMessage一致,data表示事件数据.
        "column": "properties.temp",
        //条件类型
        "termType": "gt",
         //条件值
        "value": "10"
      }
    ]
  }
}
```

### 物事件

用于连接物的属性，通常用于将其他物的事件作为当前物的事件值. 实现类`ThingEventMessageConnector`

支持的物模型类型: `事件` 将指定的物的事件转为新的物事件消息(`ThingEventMessage`)

支持条件过滤:  条件类型见 `ReactorUtils.TermTypeSupport`

配置格式:

```json5
{
  "provider": "thing-event",
  "configuration": {
    "thingType": "物类型ID",
    "templateId": "模版ID",
    "thingId": "物实例ID",
    "event": "事件物模型ID",
    "converter": {
       //见消息转换器说明
    },
    "filter": [
      {
        //列字段,与ThingEventMessage一致,data表示事件数据.
        "column": "data.temp",
        //条件类型
        "termType": "gt",
        //条件值
        "value": "10"
      }
    ]
  }
}
```

### 规则计算

指定源`连接器`,使用规则计算后的值作为新的物消息. 实现类`ComputeThingsConnector`.

支持的物模型类型:

1. `属性` 将规则计算后的值转为属性消息(`ThingReportPropertyMessage`)
2. `事件` 将规则计算后的值转为事件消息(`ThingEventMessage`)

配置格式:

```json
{
  "provider": "compute",
  "configuration": {
    "source": {
      "provider": "连接器ID,可以使用任意其他连接器作为源",
      "configuration": {
      }
    },
    "rule": {
      "windowType": "值为time或num ;当使用窗口时设置",
      "window": {
        "span": "数字值,窗口大小",
        "every": "数字值,窗口间隔"
      },
      "script": "groovy脚本",
      "aggType": "聚合类型,当使用窗口时不能为空,值为:count, sum, avg, max, min, first, last, range, median, geometricMean, mean, variance, dev, slope"
    }
  }
}
```

### 组合连接器

指定多个`连接器`,将这些连接器连接在一起. 实现类`CompositeThingsConnector`.

配置格式:

```json
{
  "provider": "composite",
  "configuration": {
    "connectors": [
      {
        "provider": "连接器ID,可以使用任意其他连接器作为源",
        "configuration": {
        }
      }
    ]
  }
}
```

### RPC

使用RPC作为连接器,通常用于功能调用时.

配置格式:

```json
{
  "provider": "rpc",
  "configuration": {
    "provider": "RPC Provider ID,见内置RPC支持说明",
    "configuration": {
    }
  }
}
```

## 内置RPC支持

用于自定义对物功能调用时的操作. 自定义RPC支持请实现接口`ThingsRpcSupportProvider`

### 物RPC

调用其他物的RPC操作,如果: 读取其他物的属性

配置格式:

```json
{
  "provider": "thing",
  "configuration": {
    "thingType": "物类型",
    "thingId": "物实例ID",
    "message": {
      "messageType": "INVOKE_FUNCTION 不同的类型消息格式不同",
      "inputs": [
        {
          "name": "arg0",
          "value": "test可以使用表达式,比如: ${value},表达式的变量来自调用功能时传入的参数."
        }
      ]
    }
  }
}

```

### 组合RPC

组合执行多个RPC操作

配置格式:

```json5
{
  "provider": "composite",
  "configuration": {
    //是否并行执行
    "parallel": true,
    //某个rpc执行失败时是否中断执行
    "interruptOnError": false,
    "actions": [
      {
        "provider": "thing",
        "configuration": {
          "thingType": "device",
          "thingId": "xxxx",
          "message": {
            "messageType": "READ_PROPERTY",
            "properties": [
              "xxx,串行执行时,这里可以使用上一个rpc执行结果的返回值作为变量"
            ]
          }
        }
      }
    ],
    "converter": {
      "provider": "结果转换方式,见消息转换器说明",
      "configuration": {
      }
    }
  }
}
```

## 内置消息转换器

用于对物消息进行转换,自定义转换器请实现接口: `ThingMessageConverterProvider`

### 映射转换器

使用映射表对消息进行字段转换,支持消息类型: `属性相关消息`,`事件消息`,`功能调用相关消息`.

配置格式:

```json

{
  "provider": "mapping",
  "configuration": {
    "mappings": [
      {
        "source": "来源字段,支持表达式"
      },
      {
        "target": "转换为新的字段,支持表达式"
      }
    ]
  }
}

```

### 模版转换器

使用消息模版转换为固定的消息,支持消息类型: `属性相关消息`,`事件消息`,`功能调用相关消息`.

配置格式:

```json

{
  "provider": "template",
  "configuration": {
    "messageType": "INVOKE_FUNCTION",
    "inputs": [
      {
        "name": "arg0",
        "value": "1"
      }
    ]
  }
}

```