yudao-ui-admin-vue3/src/views/iot/rule/scene/IotThingModelTSLRespVO数据结构文档.md

// TODO @puhui999：这些后续需要删除哈

IotThingModelTSLRespVO 数据结构文档

概述

IotThingModelTSLRespVO 是IoT产品物模型TSL（Thing Specification Language）的响应数据结构，用于返回完整的产品物模型定义，包括属性、事件和服务的详细信息。TSL是阿里云IoT平台定义的一套物模型描述规范。

主体数据结构

IotThingModelTSLRespVO

interface IotThingModelTSLRespVO {
  productId: number;                    // 产品编号（必填）
  productKey: string;                   // 产品标识（必填）
  properties: ThingModelProperty[];     // 属性列表（必填）
  events: ThingModelEvent[];           // 事件列表（必填）
  services: ThingModelService[];       // 服务列表（必填）
}

字段说明：

• productId: 产品编号，唯一标识一个IoT产品
• productKey: 产品标识符，用于设备连接和识别
• properties: 设备属性列表，描述设备的状态信息
• events: 设备事件列表，描述设备主动上报的事件
• services: 设备服务列表，描述可以调用的设备功能

属性数据结构 (ThingModelProperty)

基本结构

interface ThingModelProperty {
  identifier: string;                   // 属性标识符（必填）
  name: string;                        // 属性名称（必填）
  accessMode: string;                  // 访问模式（必填）
  required?: boolean;                  // 是否必选
  dataType: string;                    // 数据类型（必填）
  dataSpecs?: ThingModelDataSpecs;     // 数据规范（非列表型）
  dataSpecsList?: ThingModelDataSpecs[]; // 数据规范（列表型）
}

字段详细说明

identifier（属性标识符）

• 类型: string
• 必填: 是
• 格式: 正则表达式 ^[a-zA-Z][a-zA-Z0-9_]{0,31}$
• 说明: 只能由字母、数字和下划线组成，必须以字母开头，长度不超过32个字符
• 示例: "temperature", "humidity", "power_status"

name（属性名称）

• 类型: string
• 必填: 是
• 说明: 属性的显示名称，用于界面展示
• 示例: "温度", "湿度", "电源状态"

accessMode（访问模式）

• 类型: string
• 必填: 是
• 枚举值:
  • "r": 只读，设备只能上报，平台不能下发
  • "rw": 读写，设备可以上报，平台也可以下发
• 示例: "r", "rw"

dataType（数据类型）

• 类型: string
• 必填: 是
• 枚举值:
  • "int": 整数型
  • "float": 单精度浮点型
  • "double": 双精度浮点型
  • "enum": 枚举型
  • "bool": 布尔型
  • "text": 文本型
  • "date": 时间型
  • "struct": 结构体型
  • "array": 数组型

事件数据结构 (ThingModelEvent)

基本结构

interface ThingModelEvent {
  identifier: string;                   // 事件标识符（必填）
  name: string;                        // 事件名称（必填）
  required?: boolean;                  // 是否必选
  type: string;                        // 事件类型（必填）
  outputParams?: ThingModelParam[];    // 输出参数
  method?: string;                     // 执行方法
}

字段详细说明

type（事件类型）

• 类型: string
• 必填: 是
• 枚举值:
  • "info": 信息事件
  • "alert": 告警事件
  • "error": 故障事件

outputParams（输出参数）

• 类型: ThingModelParam[]
• 必填: 否
• 说明: 事件触发时返回的参数信息

服务数据结构 (ThingModelService)

基本结构

interface ThingModelService {
  identifier: string;                   // 服务标识符（必填）
  name: string;                        // 服务名称（必填）
  required?: boolean;                  // 是否必选
  callType: string;                    // 调用类型（必填）
  inputParams?: ThingModelParam[];     // 输入参数
  outputParams?: ThingModelParam[];    // 输出参数
  method?: string;                     // 执行方法
}

字段详细说明

callType（调用类型）

• 类型: string
• 必填: 是
• 枚举值:
  • "async": 异步调用
  • "sync": 同步调用

参数数据结构 (ThingModelParam)

基本结构

interface ThingModelParam {
  identifier: string;                   // 参数标识符（必填）
  name: string;                        // 参数名称（必填）
  direction: string;                   // 参数方向（必填）
  paraOrder?: number;                  // 参数序号
  dataType: string;                    // 数据类型（必填）
  dataSpecs?: ThingModelDataSpecs;     // 数据规范（非列表型）
  dataSpecsList?: ThingModelDataSpecs[]; // 数据规范（列表型）
}

字段详细说明

direction（参数方向）

• 类型: string
• 必填: 是
• 枚举值:
  • "input": 输入参数
  • "output": 输出参数

数据规范结构 (ThingModelDataSpecs)

数据规范是一个抽象基类，根据不同的数据类型有不同的具体实现：

1. 数值型数据规范 (ThingModelNumericDataSpec)

适用于 int、float、double 类型：

interface ThingModelNumericDataSpec {
  dataType: "int" | "float" | "double";
  max: string;                         // 最大值（必填）
  min: string;                         // 最小值（必填）
  step: string;                        // 步长（必填）
  precise?: string;                    // 精度（float/double可选）
  defaultValue?: string;               // 默认值
  unit?: string;                       // 单位符号
  unitName?: string;                   // 单位名称
}

2. 布尔/枚举型数据规范 (ThingModelBoolOrEnumDataSpecs)

适用于 bool、enum 类型：

interface ThingModelBoolOrEnumDataSpecs {
  dataType: "bool" | "enum";
  name: string;                        // 枚举项名称（必填）
  value: number;                       // 枚举值（必填）
}

3. 文本/时间型数据规范 (ThingModelDateOrTextDataSpecs)

适用于 text、date 类型：

interface ThingModelDateOrTextDataSpecs {
  dataType: "text" | "date";
  length?: number;                     // 数据长度（text类型需要，最大2048）
  defaultValue?: string;               // 默认值
}

4. 数组型数据规范 (ThingModelArrayDataSpecs)

适用于 array 类型：

interface ThingModelArrayDataSpecs {
  dataType: "array";
  size: number;                        // 数组元素个数（必填）
  childDataType: string;               // 数组元素数据类型（必填）
  dataSpecsList?: ThingModelDataSpecs[]; // 子元素数据规范（struct类型时）
}

childDataType 枚举值:

• "struct": 结构体
• "int": 整数
• "float": 单精度浮点
• "double": 双精度浮点
• "text": 文本

5. 结构体型数据规范 (ThingModelStructDataSpecs)

适用于 struct 类型：

interface ThingModelStructDataSpecs {
  dataType: "struct";
  identifier: string;                  // 属性标识符（必填）
  name: string;                        // 属性名称（必填）
  accessMode: string;                  // 操作类型（必填）
  required?: boolean;                  // 是否必选
  childDataType: string;               // 子数据类型（必填）
  dataSpecs?: ThingModelDataSpecs;     // 数据规范（非列表型）
  dataSpecsList?: ThingModelDataSpecs[]; // 数据规范（列表型）
}

childDataType 枚举值:

• "int": 整数
• "float": 单精度浮点
• "double": 双精度浮点
• "text": 文本
• "date": 时间
• "enum": 枚举
• "bool": 布尔

数据类型映射关系

dataSpecs vs dataSpecsList

• dataSpecs: 用于非列表型数据类型（int、float、double、text、date、array）
• dataSpecsList: 用于列表型数据类型（enum、bool、struct）

JSON多态序列化

数据规范使用Jackson的@JsonTypeInfo和@JsonSubTypes注解实现多态序列化：

{
  "dataType": "int",
  "max": "100",
  "min": "0",
  "step": "1",
  "unit": "°C",
  "unitName": "摄氏度"
}

完整示例

温度传感器物模型示例

{
  "productId": 1024,
  "productKey": "temperature_sensor",
  "properties": [
    {
      "identifier": "temperature",
      "name": "温度",
      "accessMode": "r",
      "required": true,
      "dataType": "float",
      "dataSpecs": {
        "dataType": "float",
        "max": "100.0",
        "min": "-40.0",
        "step": "0.1",
        "precise": "1",
        "unit": "°C",
        "unitName": "摄氏度"
      }
    },
    {
      "identifier": "power_switch",
      "name": "电源开关",
      "accessMode": "rw",
      "required": false,
      "dataType": "bool",
      "dataSpecsList": [
        {
          "dataType": "bool",
          "name": "关闭",
          "value": 0
        },
        {
          "dataType": "bool",
          "name": "开启",
          "value": 1
        }
      ]
    }
  ],
  "events": [
    {
      "identifier": "high_temperature_alert",
      "name": "高温告警",
      "required": false,
      "type": "alert",
      "outputParams": [
        {
          "identifier": "current_temp",
          "name": "当前温度",
          "direction": "output",
          "dataType": "float",
          "dataSpecs": {
            "dataType": "float",
            "max": "100.0",
            "min": "-40.0",
            "step": "0.1"
          }
        }
      ]
    }
  ],
  "services": [
    {
      "identifier": "reset_device",
      "name": "重置设备",
      "required": false,
      "callType": "async",
      "inputParams": [
        {
          "identifier": "reset_type",
          "name": "重置类型",
          "direction": "input",
          "dataType": "enum",
          "dataSpecsList": [
            {
              "dataType": "enum",
              "name": "软重置",
              "value": 1
            },
            {
              "dataType": "enum",
              "name": "硬重置",
              "value": 2
            }
          ]
        }
      ],
      "outputParams": [
        {
          "identifier": "result",
          "name": "执行结果",
          "direction": "output",
          "dataType": "bool",
          "dataSpecsList": [
            {
              "dataType": "bool",
              "name": "失败",
              "value": 0
            },
            {
              "dataType": "bool",
              "name": "成功",
              "value": 1
            }
          ]
        }
      ]
    }
  ]
}

前端使用建议

1. TypeScript类型定义

建议在前端项目中定义完整的TypeScript接口，确保类型安全：

// 定义完整的类型接口
export interface IotThingModelTSLRespVO {
  productId: number;
  productKey: string;
  properties: ThingModelProperty[];
  events: ThingModelEvent[];
  services: ThingModelService[];
}

// 使用联合类型处理数据规范的多态性
export type ThingModelDataSpecs = 
  | ThingModelNumericDataSpec
  | ThingModelBoolOrEnumDataSpecs
  | ThingModelDateOrTextDataSpecs
  | ThingModelArrayDataSpecs
  | ThingModelStructDataSpecs;

2. 数据验证

// 验证数据类型和数据规范的一致性
function validateDataSpecs(dataType: string, dataSpecs: any): boolean {
  switch (dataType) {
    case 'int':
    case 'float':
    case 'double':
      return dataSpecs.dataType === dataType && 
             dataSpecs.max !== undefined && 
             dataSpecs.min !== undefined;
    case 'bool':
    case 'enum':
      return Array.isArray(dataSpecs) && 
             dataSpecs.every(spec => spec.name && spec.value !== undefined);
    // ... 其他类型验证
    default:
      return false;
  }
}

3. 数据转换工具

// 将后端数据转换为前端展示格式
function formatPropertyValue(property: ThingModelProperty, value: any): string {
  if (property.dataType === 'enum' || property.dataType === 'bool') {
    const spec = property.dataSpecsList?.find(s => s.value === value);
    return spec?.name || String(value);
  }
  
  if (property.dataType === 'float' || property.dataType === 'double') {
    const unit = property.dataSpecs?.unit || '';
    return `${value}${unit}`;
  }
  
  return String(value);
}

注意事项

1. 数据规范选择: 根据dataType选择使用dataSpecs还是dataSpecsList
2. 标识符唯一性: 在同一产品下，所有功能的identifier必须唯一
3. 数据类型一致性: 参数的dataType必须与其dataSpecs的dataType保持一致
4. 枚举值处理: 布尔型和枚举型数据使用dataSpecsList数组存储可选值
5. 嵌套结构: 结构体和数组类型可能包含嵌套的数据规范定义
6. 版本兼容: 物模型结构可能随版本演进，前端需要做好兼容性处理

这个数据结构为IoT设备的完整功能描述提供了标准化的格式，支持复杂的数据类型和嵌套结构，能够满足各种IoT设备的建模需求。