特性规则创建说明¶

在模型管理中，特性规则 是用于定义模型之间或模型内部数据映射和转换的规则，确保数据能够正确传递和使用。

本文介绍创建特性规则的应用场景、创建原则及示例。

关键概念 ¶

了解以下概念有助于理解特性规则的作用：

设备：能够通过网络传输数据并与物联网平台交互的实体，数据的字段命名和格式由设备厂商决定。
模型：屏蔽设备差异和复杂业务逻辑，在不同场景中可承担不同用途。
继承链：模型间的父子级关系链路，例如：A1 为父模型，A1-1 为其子模型，A1 的祖父模型和 A1-1 的子孙模型都在同一继承链上。
表达式：数据映射的计算逻辑。在跨模型特性规则中，根据数据的传输方向，表达式可分为：
- 上行表达式：用于解析设备上送的数据。定义从映射模型（接入模型）中的特性映射到当前模型（业务模型）中的特性的逻辑。
- 下行表达式：用于处理云端下发的控制命令。定义从当前模型（业务模型）中的特性映射到映射模型（接入模型）中的特性的逻辑。
有关表达式的更多信息，参见特性规则表达式说明。

何时需要创建特性规则¶

特性规则分为两类：

默认规则：模型内的特性规则，用于轻量级计算与字段增强，适用于在同一模型内对原始字段做轻量处理。

示例：通过规则 power_kW = power_W / 1000，可将功率字段 power_W 转换为 power_kW，完成单位换算。
跨模型规则：当不同模型共享同一设备数据时，需要在模型间做字段映射与语义转换。

示例：设备通过模型 A 接入，而终端应用消费模型 B 的数据，此时为模型 A 与模型 B 建立映射，使应用能以模型 B 的语义消费设备数据。

跨模型规则创建原则¶

创建跨模型特性规则时，需遵循以下原则：

父模型先行
- 子模型之间的特性规则，必须建立在其父模型之间已存在特性规则的前提之上。例：先建立 A1 → B1 的规则，才能建立 A1-1 → B1-1 的规则。
- 一旦父模型之间建立了规则，已接入源模型的设备可以加绑目标模型及其子孙模型。例：若 A1 → B1 已建规则，则在接入了 A1 的设备上，可以加绑 B1 或 B1-1，共享测点数据。
单向配置，双向映射
- 在目标模型中配置映射规则，在同一规则中配置上下行表达式，避免双向链路混淆。
  
  例：如需把 A1.temperature 映射到 B1.roomTemp，需进入 B1 的特性规则配置页，选择 A1 为映射模型，新增规则并填写上下行表达式。
避免重复映射
- 一旦某模型已被选为映射模型，其继承链上的其他模型不能再被选为映射模型，避免同一链路出现双重映射与冲突覆盖。
  
  例：已在 B1 中选了 A1 并完成映射，则不再允许同时在 B1 中再选 A1-1 或 A1 的父辈作为映射模型。
字段兼容
- 字段类型、语义需兼容（例如数值型映射到数值型），并符合数据方向（上行/下行）要求。
- 例：设备上报 power(W)，业务模型需 Power(kW)，规则表达式里用 Power = power / 1000 来兼容语义与单位。
来源唯一：一个目标字段只能有一个上游来源，避免二义性与竞争。

跨模型规则中的上行与下行表达式¶

在跨模型规则中，需要分别配置上行表达式和下行表达式，以支持设备数据的完整交互流程。

上行表达式¶

用途：解析设备上送的数据。

定义：从映射模型（接入模型）中的特性映射到当前模型（业务模型）中的特性的转换逻辑。当设备通过接入模型接入数据时，上行表达式将接入模型中的特性值映射到当前模型的特性中，使业务应用可以获得期望语义和格式的数据。

应用场景：设备接入时使用接入模型，业务需要加绑或换绑到业务模型以获取特定格式或语义的数据。例如，设备以功率(W)形式接入，业务模型需要功率(kW)的格式。

配置方式：

在当前模型（业务模型）中新建跨模型规则，选择映射模型（接入模型）。
为业务模型中的目标特性编写上行表达式，表达式中应包含来自接入模型中一个或多个特性。
表达式格式：目标特性 = <包含映射模型特性的表达式>，例如 "power_kW" = "接入模型.power_W" / 1000。

校验规则（属性和测点均支持）：

表达式中可包含映射模型的一个或多个特性，也可包含当前模型的一个或多个特性（用于辅助计算）。
表达式中可使用属性、测点、常数和函数。
如果目标特性是属性，表达式中的所有特性都必须是属性。
如果目标特性是测点，表达式中的特性可以是测点或属性的混合。
不支持循环依赖（例如 A = B, B = C, C = A 的情况）。

下行表达式¶

用途：处理云端下发的控制命令。

定义：从当前模型（业务模型）中的特性映射到映射模型（接入模型）中的特性的转换逻辑。当应用通过业务模型下发控制命令时，下行表达式将业务模型中的特性值映射到接入模型的对应特性，向设备发送正确的控制指令。

应用场景：通过业务模型下发的控制命令需要正确转换格式和语义后，才能被接入模型及其关联设备正确处理。例如，应用下发功率设定值(kW)，设备需要接收功率设定值(W)的格式。

配置方式：

在当前模型（业务模型）中新建跨模型规则，选择映射模型（接入模型）。
为业务模型中的目标特性编写下行表达式，表达式中必须包含当前模型中的该特性。
下行表达式后需指定映射模型中的目标特性。
表达式格式：<包含当前模型特性的表达式> => 映射模型.目标特性，例如 "powerSetpoint_kW" * 1000 => "接入模型.P_set_W"。

校验规则（仅测点支持）：

下行表达式仅支持为测点配置，不支持为属性配置。
表达式中必须包含当前模型中的目标特性本身。
表达式中可使用当前模型的特性、常数和函数，不支持直接引用映射模型的特性。
不支持循环依赖。

示例¶

默认规则示例¶

设备字段：
- voltage（电压，单位 V）
- current（电流，单位 A）
模型 A 字段：
- voltage：与设备一致
- current：与设备一致
- power_W（功率，单位 W）

此时在模型 A 中配置默认特性规则，表达式为：

power_W = voltage * current

跨模型规则示例¶

设备端字段：
- voltage（电压，单位 V）
- current（电流，单位 A）
- P_set（设定功率，单位 W，支持写入）
模型 A 字段：
- voltage：与设备一致
- current：与设备一致
- P_set_W：与设备一致
- power_W（功率，单位 W）：默认规则 power_W = voltage * current
模型 B 字段：
- power_KW（功率，单位 kW）
- powerSetpoint_kW（设定功率，单位 kW）

此时在模型 B 中创建跨模型特性规则：

上行表达式：power_kW = A.power_W / 1000
下行表达式：A.P_set_W = B.powerSetpoint_kW * 1000

创建后，数据将按照特性规则传递：

上行：

设备上送数据：voltage = 500 V, current = 10 A

↓

模型 A：power_W = 500 * 10 = 5000 W（模型内规则）

↓

模型 B：power_kW = 5000 / 1000 = 5 kW（跨模型上行表达式）

下行：

模型 B：powerSetpoint_kW = 6（应用下发控制命令）

↓

模型 A：A.P_set_W = 6 * 1000 = 6000 W（跨模型下行表达式）

↓

设备接收控制：P_set = 6000 W

通过以上配置，设备上送 voltage 与 current 时，系统与应用即可获得 power_kW；当应用下发 powerSetpoint_kW 时，设备能收到对应的 P_set。上行与下行均在同一条规则中得到维护。

特性规则的导入导出¶

特性规则支持导入导出功能，便于规则的备份、迁移和批量管理。

文件格式：导入导出使用 CSV 或 Excel 格式，其中跨模型规则包含以下字段：

expressionRead：上行表达式
expressionWrite：下行表达式
其他元数据字段：映射模型、目标特性、特性类型等

对于旧版本模板文件中的 expression 字段，系统将自动视其为 expressionRead 字段处理。