一、写给谁、解决什么困惑
适合做 设备接入、网关、物模型、App 状态同步 的人读。
典型现象：双路插座、多键开关 在硬件上能独立控制，但软件里只有一个开关、两路显示总跟一路走，或状态偶发乱跳。
本文把 根因 说成清楚话，并区分两种常见的 设备心智（mental model）：桥接器下的子设备 与 单节点上的多个端点，避免团队嘴上说的「一个设备」和协议里说的「一个设备」不是一回事。
二、先拆两件事：能力 vs 状态
能力（capability） 回答：这台设备在模型里 允许哪些类型的操作和属性（偏静态）。常用于发现后的档案、决定 UI 上摆哪些控件、规则引擎判断是否可下发某类指令。
状态（state） 回答：当前 各受控对象的具体取值（偏动态），来自轮询、上报或下发后的回读。
很多人一上来查 「类型映射 / 能力名对不对」，若那一层 根本不承载分路的实时 on/off，就会 查错层：真正丢信息的往往是 状态被合并进单一字段 的那一步，而不是能力列表那一行字。
三、协议里常见的一层关系：节点、端点、簇（抽象说法）
不必绑定具体协议栈名字，大意是：
- 节点（node）：一次配网、一个网络侧身份，常被视为「一颗逻辑设备根」。
- 端点（endpoint）：节点下的寻址单元；不同端点上可以各有 一套同类功能（例如两路各自一套「开关」语义）。
- 簇 / 属性：在某个端点上读写具体值。
双路插座在协议侧往往是：一个节点，多个端点，每路一套开关类数据；在用户侧却是：一个五金件，两个开关。若产品模型写成 「一个用户可见设备 = 一个全局 on 字段」，维度和物理世界 不一致，后面一定会出事。
四、根因：扁平合并与「后写覆盖」
很常见的一种实现思路是：遍历该节点下 所有端点，把读到的开关类属性 不断写入同一个应用层状态对象的同一个字段。
只要 多个端点写同一槽位，在顺序处理下就等价于：
最后被处理到的端点的值，成为该字段的唯一结果——与业务上「更重视哪一路」无关，是 数据结构 决定的。若遍历顺序还不稳定，甚至会看到 间歇性错乱。
UI 若只绑定 这一个字段，或两个开关都读 同一变量，就会表现为 永远一路 或 两路假同步。
同类问题不限于 on/off：凡是 每个端点各有一份、却被压进全局单字段 的量，都会 互相覆盖。
一句话：物理上是二维（至少「节点 × 端点」），应用层却用一维标量表示，就会丢维。
五、正确方向：给「端点」这一维显式留位置
- 状态分桶：用端点标识做索引，每路状态各写各的桶，避免多路 on/off 抢一个字段。
- 上报与下发带作用域：事件和指令最好能表达 作用在哪个端点；若上游暂时不能区分，要有 写进文档的默认策略（并标明是兼容手段），避免 静默猜错。
- UI 与数据对齐：一路控件对应一路数据源；设备列表里 一行到底代表「整个节点」还是「一路」 要在产品和技术上约定一致。
- 「主端点 / 默认视图」：可以给旧界面只做 一路摘要，但要明确那是 兼容视图，不是多端点设备的完整权威模型。
六、桥接器 + 子设备 vs 单节点多端点（两种心智对比）
行业里常有两套 听起来都像「一个网关下面挂好多东西」 的结构，但 寻址和状态归属 不同，混用容易用错接口。
6.1 桥接器 + 子设备（bridge + child device）
用户侧常表现为 多台独立子设备：各自名称、房间、自动化；系统里往往 每个子设备有自己的主键。物理上可能经桥接器入网，但产品层倾向把 子设备当一等公民。
状态上 通常自然倾向 「一个展示单元对应一份状态」，较少出现「两个子设备共写一个 on」——除非接入层实现写错。
风险点 更多在：子设备与桥接器之间的发现、映射、寻址 是否一致，避免把「桥」当成普通受控端去操作。
6.2 单节点多端点（single node, multiple endpoints）
用户可能只经历 一次配网，看到 一个设备；协议上却是 同一节点下多个端点，每路独立簇/属性。
状态上 若仍用 扁平整设备状态，极易出现本文的 后写覆盖；必须按端点分桶（或等价结构）。
控制上 必须能表达 对哪一端点生效，不能长期只靠「猜默认路」。
6.3 对照表（给团队对齐用语）
| 维度 | 桥接器 + 子设备 | 单节点多端点 |
|---|---|---|
| 用户可见粒度 | 常为 多台子设备 | 常为 一台设备、多路输出 |
| 主键习惯 | 每子设备一个 ID 很常见 | 节点 ID + 端点号 很常见 |
| 状态风险 | 映射/发现 乱 | 扁平合并、多路抢一个字段 |
| 典型翻车 | 子设备与桥 对应关系 不清 | UI 绑同一标量、合并无端点维 |
6.4 最别扭的一种混法
产品上把 双路插座 做成 两个卡片（看起来像两个子设备），底层却仍是 一个节点 + 一个扁平状态对象——外观是「两台」，数据是「一个槽位」，问题会反复出现。
反过来，真·多子设备 若被当成 同一节点的多端点 去 合并状态，也可能把 本该独立 的两台 揉成一团。
建议在架构说明里写死一句话：用户可见的某一个「设备」，在协议上到底是 一条子设备记录 还是 某节点上的一个端点；缓存、路由、UI 都按同一种定义实现。
七、收束
能力 管「能干什么」，状态 管「现在怎样」；双路只显示一路，多数是 状态合并维度不够，不是能力名字写错。
再叠一层：桥接子设备 与 单节点多端点 是两种不同心智——外观可以像两种都做「多卡片」，但 状态到底按子设备分还是按端点分 必须和协议真实结构一致，否则会在错误层长期救火。
核心一句：先给状态加上 端点（或等价）这一维，再谈映射与界面；否则多端点设备永远会在扁平字段里 自己覆盖自己。
