[Device][M2] 按统一规范拆分 SZLab 带传感器堆栈设备

[TablewareBox]

上游控制面

• 功能目录：Core #134
• Device/Deck/Warehouse：Core #142
• 传感器堆栈规范：Core #143
• OS 消费合同：Core #140、Core #145
• OS M2 consumer/projector：OS #7
• FE M2 consumer：FE #12
• 参考实现：Xuwznln/device_package_u 的 kaimisiterui/eit_consumables_rack

目标

把 SZLab 现有集中在 szlab_poly_plc 的多组 Site→OPC 变量与自定义 stack_status 聚合，拆成遵守统一合同的“带传感器堆栈设备”。每个物理堆栈是独立设备，直接拥有一个 Warehouse，并使用自己的 OPC client；通用 PLC 设备不再作为所有堆栈占用事实的聚合 Authority。

交付范围

1. 设备与 Warehouse 归属

• 每个物理传感器堆栈定义一个独立 device class/instance，直接持有且只持有一个 Warehouse 子 Resource/Material。
• 每个堆栈建立独立 OPC client 生命周期、连接/重连和通用 heartbeat/status；即使共用同一 PLC endpoint，也不得共享会造成跨堆栈故障/状态耦合的隐式 client singleton。
• S3、S11 等一个物理 Warehouse 内包含多种行/物料类型时，仍以物理堆栈/Warehouse 为设备边界，不按物料角色伪拆两个 Warehouse Authority。
• 文档列出最终“设备 class → Warehouse resource → Site.sort_order → 物理传感器位置/地址”的完整映射。

2. __init__() 直接参数与默认值

不使用 opaque profile 字典承载本合同字段；设备类在 __init__() 直接展开并提供包内默认值：

occupancy_sensor_array_address: str
observation_poll_interval_s: float = 1.0
observation_freshness_ttl_s: float = 3.0
observation_debounce_count: int = 2

• 设备/OPC endpoint 与认证等既有连接参数同样保持显式初始化参数。
• 校验 TTL 严格大于 poll interval、debounce count >= 1。
• @topic_config 的实际 period 绑定实例最终 poll 值，不保留另一份 decorator 常量。

3. 单数组 occupancy topic

• 从 occupancy_sensor_array_address 读取一个整仓数组，并通过一个 @topic_config 状态发布裸数组：

["empty", "occupied", "unknown"]

• 硬件 bool/0/1/null 在设备 Adapter 规范化为 empty|occupied|unknown；不发布 Material UUID，不把 Site name 或复杂索引字符串泄漏为运行期 identity。
• 读取失败发布 correct-length unknown 数组；不能仅抛异常后静默停更。
• 硬件返回长度错误时不 pad/truncate，原样交给 OS fail-closed。
• 旧 PLC 若只能暴露多组标量地址，可在包内 Adapter 聚合为该单一逻辑数组；公开 device/topic 合同保持不变。

4. 顺序与生命周期

• topic 数组顺序与 Warehouse 直接 Sites 的持久 sort_order 升序一致；设备包资源声明生成唯一、非负的初始 sort order。
• device/provider reconnect、地址变化或映射 revision 时触发 OS 可识别的通用生命周期重置；不得把缓存有效 occupancy 当新 epoch Authority。
• 设备只发布原始规范化 observation。freshness、对称 debounce、logical occupancy 比对与 admission gate 由 OS projector 负责。

参考 EIT 写法时保留/修改的边界

• 可复用 eit_consumables_rack 的 driver/controller/runtime 分层、配置校验、整架查询和测试结构。
• 不复制其“按 resource_type 自行查找可用槽位”的业务分配职责；最终 Material/Site 选择属于 OS Authority。
• 不把 YAML 的 layer/position/resource_type 或当前 SZLab site_key 当稳定 Site identity；OS wire identity 始终是 Site UUID，数组仅按冻结 sort order 对齐。

明确不做

• Material/Site 分配、Reservation/Claim 或 logical occupancy 写入；
• Inventory 扣减；
• reconciliation/人工恢复；
• 多 Warehouse 自动路由；
• provider timestamp/sequence/epoch envelope（本版 payload 固定为裸数组）。

验收门

• 每个堆栈包提供单元测试：数组规范化、read failure、错误 shape、独立 client、init 校验和 Warehouse/Site order。
• 使用 mock OPC/recording 验证两个堆栈并行运行时 client 与故障隔离。
• 与真实 OS projector 联调：empty/occupied、unknown、TTL、对称 debounce、shape mismatch、reconnect cold-start 均有可重复证据。
• 提供新的设备包位置与完整文件树，并回链 exact SHA、测试日志和 FE E2E 截图到 Core #143/验收票。

[TablewareBox]

Wayfinder delivery decomposition

本票保留为 SZLab sensor-stack umbrella：

1. #3 公共 device contract 与测试夹具
2. #4 按物理 Warehouse 拆分堆栈与 OPC client
3. #5 occupancy 数组与 OS live 联调

执行顺序为 #3 → #4 → #5；若 #4 经物理堆栈清单确认后仍超过一个 merge/review gate，再按堆栈设备继续向下拆，当前不提前制造每堆栈空票。