ThinkLink 实践 / 模型与数据
ThinkLink 物模型怎么做：从 payload 解码到可信遥测的五步检查
解码只是物模型的一部分。用字段契约、单位核对、边界样本和版本回归，让 ThinkLink 的遥测数据能够支撑告警、看板和集成。
先定义字段含义与单位，再编写 payload 解析。用正常、边界和异常样本验证输出，并检查显示字段与协议映射；不要把空值、错误码或尚未采样的数据直接转换成正常读数。
先写字段表，避免下游各自猜测
同一个温度值，如果在不同设备上分别叫 temp、T 和 temperature，下游看板与告警就需要反复适配。物模型的价值不仅是把字节转成数字，还在于为数据提供稳定、可理解的含义。
建议先建立字段表：字段名、业务含义、单位、数据类型、正常范围、缺失时如何表达，以及上游协议版本。字段命名可以遵循团队已有约定，不必为了文章示例改动已投入使用的模型。累计量和瞬时量、状态与测量值，应明确区分。
| 字段示例 | 含义约定 | 需要核对 |
|---|---|---|
| temperature | 当前温度，单位 °C | 有符号数、倍率与异常码 |
| humidity | 相对湿度，单位 %RH | 量程、精度与缺失值 |
| water_total | 累计水量，单位 m³ | 是否累计、复位与回绕 |
| sample_time | 该次测量的时间 | 设备时钟或平台接收时间 |
用设备协议决定解析，不凭样本猜格式
取得 AS 中的一条真实业务负载后，先核对端口、报文类型、长度和协议版本，再按设备文档解释字节序、符号位及缩放比例。单个样本碰巧得到合理数值，并不能证明解析方式正确。
ThinkLink 物模型提供解析脚本与测试入口。脚本输出应遵循当前物模型文档的遥测和属性结构；脚本中的辅助方法、运行限制以及可访问的上下文，也要以对应版本为准。把耗时外部请求塞进解码逻辑，会让数据接入依赖难以控制的外部条件。
至少准备三组样本
第一组是正常报文：选择能与参考仪表对照的值，逐字段写出预期结果。第二组是边界报文：包括负温度、最大计数值和状态位组合等协议允许的情况。第三组是异常报文：包括长度不足、未知类型、设备错误码或缺失字段。
异常数据如何处理需要明确约定。可以按协议忽略无效读数或保留诊断信息，但不要把解析失败默认成 0，否则看板可能显示“零能耗”，告警也可能被错误解除。本文的字段表是设计示例，不是任意设备都能直接套用的协议。
解析输出与界面显示一起核对
模型脚本已经返回字段，页面却没有显示，未必是设备没上报。还应检查显示字段、所选模型及当前设备绑定。如果需要把数据输出到 Modbus 或 BACnet，应分别检查对应映射，不能认为有遥测字段就已完成协议输出。
这里还要确认单位呈现。模型内部使用的基础单位与界面展示单位可以不同，但转换位置必须唯一而清晰。例如升与立方米的换算如果在脚本和看板里各执行一次，就会出现数值偏差。
模型更新要能解释，也要能回退
修改解析逻辑时，保留版本说明，记录改动影响哪些型号和报文。先用保存的样本回归，再在少量测试设备上观察新上报，检查历史字段是否仍能被已有看板和告警读取。
如果字段含义发生变化，优先新增明确命名的字段并安排下游迁移，而不是悄悄复用原字段名。回退也要考虑新版本已经写入的数据：恢复旧脚本能停止新的错误，却不会自动修正已经保存的历史。
常见问题
一个物模型可以用于多台设备吗？
可以按适用范围复用，但需要确认协议、固件和字段含义一致。同类设备也应以代表性样本验证，而不是只看型号名称。
解析成功是否代表告警和看板都会自动正确？
不代表。字段显示、模型绑定、阈值单位以及外部协议映射仍要分别核对。
参考资料与延伸阅读
本文依据以下官方资料编写。示意图用于解释方法，具体菜单、字段和能力以目标版本文档为准。