物联网物模型与设备影子

1. 两个概念的职责

**物模型（Thing Model）**描述某一产品“能做什么”，是设备能力的版本化契约；**设备影子（Device Shadow）**描述某一具体设备“现在/期望是什么状态”，是云端的当前态缓存。物模型属于产品，影子属于设备。

2. 智能开关物模型示例

{
  "productKey": "SWITCH-1CH",
  "version": "1.0.0",
  "properties": [
    { "key": "power", "name": "电源", "type": "boolean", "access": "readWrite", "required": true },
    { "key": "voltage", "name": "电压", "type": "float", "unit": "V", "min": 0, "max": 260, "access": "readOnly" },
    { "key": "current", "name": "电流", "type": "float", "unit": "A", "min": 0, "max": 20, "access": "readOnly" }
  ],
  "services": [
    { "key": "reboot", "name": "重启", "input": [], "output": [{ "key": "accepted", "type": "boolean" }] }
  ],
  "events": [
    { "key": "overload", "name": "过载", "level": "warning", "output": [{ "key": "current", "type": "float", "unit": "A" }] }
  ]
}

3. 设备影子示例

{
  "deviceId": "d-switch-001",
  "desired": { "power": false },
  "reported": { "power": true, "voltage": 220.3, "current": 0.18 },
  "delta": { "power": false },
  "desiredVersion": 8,
  "reportedVersion": 7,
  "updatedAt": "2026-09-12T12:00:00+08:00"
}

当用户发出“关闭”时，云端先把 desired.power 写为 false 并递增版本。设备收到指令并执行后上报 reported.power=false；两侧一致时 delta 清空。离线设备恢复连接后可以拉取较新的 desired 版本，但必须结合指令有效期和业务规则决定是否补执行。

4. 版本与兼容

• 物模型采用语义化版本。增加可选字段为次版本，删除字段或改变数据类型为主版本。
• 已发布版本不可原地修改；设备注册时记录兼容的模型版本。
• 服务端先按消息声明版本校验，再转换成内部规范结构。
• 前端根据元数据渲染只是增强能力，关键控制仍需产品化交互和权限确认。

5. 与遥测、配置、数字孪生的区别

• 遥测是按时间追加的事实序列，适合趋势和统计；影子是可覆盖的当前快照。
• 设备配置是期望状态的一种来源，可进入 desired；配置模板本身属于产品/设备组策略。
• 数字孪生还包含关系、行为仿真和生命周期，范围大于物模型加影子。

6. 当前实现

MVP 以设备 properties 字段保存简化的 reported 快照，遥测保存于 telemetry 集合，指令参数在成功后合并到 properties。生产化按 5-1系统设计-一些细节.md 拆分 desired/reported/delta 和版本，并接入时序数据库。