微信小程序 - SA 设备控制交互设计 PRD (v2.4 规范统一版)
文档状态：草案 / 待评审 (对齐 Enum 场景与选择器规范) 主要编写人：Antigravity (AI Architect / PM Assistant)
1. 交互规范统一 (Interaction Standards)
1.1 选择器规范 (Selector Standard)
- 统一组件：采用 Checkbox (多选框) 逻辑，方型圆角外观。
- 数量判定 (Conditional UI)：
- 唯一设备 (Count = 1)：隐藏选择列表。直接在信息区展示设备全名。
- 多个设备 (Count > 1)：展示 Checkbox 列表。
- 全选联动 (Master-Slave)：
- 首项为“全场同步”，作为 Master Checkbox。
- 勾选“全场同步”则全选下方设备；取消则全不选。
- 手动勾选全部子设备时，“全场同步”自动点亮。
1.2 颜色与视觉 (Visuals)
- 主色调：深蓝 (
#184073) 用于动作、滑块及主按钮。 - 状态色：开关状态（开启-绿/关闭-灰）、温度数值。
2. 核心场景交互设计 (Scenario Design)
场景 A：枚举型控制 (Enum - Multi-device)
触发条件：指令命中了多个具备模式/枚举属性的设备。
(User) "空调调到制热" (空间内有2台空调)
(Agent)
+-------------------------------------------+
| [Icon] **请确认调节方案** |
| --------------------------------------- |
| 执行动作：设定为 **制热** |
| |
| 受控设备： |
| [x] **全场同步** (2台设备) |
| ------------------------- |
| [x] 305-AC-01 (当前-自动) |
| [x] 305-AC-02 (当前-制冷) |
| --------------------------------------- |
| [ 取消 ] [ 确认执行 ] |
+-------------------------------------------+"制热" 取自 设备管理-枚举语义化定义
场景 B：布尔型控制 (Bool - Single vs Multi)
B1. 唯一匹配 (Single)
(User) "打开 305 主灯"
(Agent)
+-------------------------------------------+
| [Icon] **确认开启设备** |
| --------------------------------------- |
| 执行动作：设定为 **开启** |
| 受控范围：**305 主灯** |
| --------------------------------------- |
| [ 取消 ] [ 确认执行 ] |
+-------------------------------------------+"开启" 取自 设备管理-BOOL语义化定义
B2. 模糊歧义 (Multi)
(User) "关掉 305 的灯"
+-------------------------------------------+
| [Icon] **确认关闭操作** |
| --------------------------------------- |
| 执行动作：设定为 **关闭** |
| |
| 受控范围： |
| (x) **全部灯光** |
| ( ) 305-主灯 |
| ( ) 305-筒灯 |
| --------------------------------------- |
| [ 取消 ] [ 确认执行 ] |
+-------------------------------------------+场景 C：数值型控制 (Float - Single AC)
设计逻辑：单设备时，卡片更聚焦数值。
(User) "空调调到 26 度" (唯一设备)
(Agent)
+-------------------------------------------+
| [Icon] **请确认调节方案** |
| --------------------------------------- |
| 执行目标：设定温度 **26.0℃** |
| [ - ] —————⬤————— [ + ] |
| |
| 受控范围：305 变频空调 |
| --------------------------------------- |
| [ 取消 ] [ 确认执行 ] |
+-------------------------------------------+3. 取数逻辑说明
3.1 确认卡片取数逻辑
当用户说"打开305会议室的灯"时，确认卡片所需数据按以下方式获取：
卡片 Header 标题：取当前操作对应的标准语义名称（来自"标准语义管理"库，如 light_power → "灯具开关"），前面拼接动词（布尔型→"控制"，枚举型→"切换"，数值型→"调节"），形成如"控制 灯具开关"的标题。
卡片 Header 图标：按以下优先级取数：
- 优先使用标准语义库中配置的
icon字段（如light_power→fa-lightbulb、hvac_target_temp→fa-temperature-high） - 若标准语义未配置 icon，兜底使用固定图标
fa-sliders - icon 通过
semanticKey参数传入renderSAControl，由SemanticUtils.findItem(semanticKey).icon获取
受控设备列表：利用 Agent 解析得出的空间路径（305会议室）和标准语义 Key（light_power），从"设备语义管理"库中查出该空间下所有具备 light_power 语义映射的设备，同时取出每台设备的别名。
设备当前状态：每台设备的当前实时值通过已映射的逻辑信号查询 IoT 平台获取。显示格式根据语义数据类型决定：
- 布尔型：将原始值（0/1）通过设备映射中定义的"值→意图"翻译表转为"开启/关闭"等中文
- 枚举型：将原始枚举值通过映射表转为中文字段标签（如 auto→"自动"、cool→"制冷"）
- 数值型：原始数值直接加上单位后缀（如"27.5℃"）
判定多设备还是单设备：若查询结果只有 1 台设备，隐藏选择列表直接展示设备名称；若多台，展示选择列表，首项为"全场同步" Master 复选框。
3.2 多设备"全场同步"匹配逻辑
当用户指令命中多个设备时，系统从以下三个维度确定受影响设备：
- 空间路径锁定的范围：从用户话语中提取空间归属（如"305会议室"），遍历该空间及下级所有子空间
- 语义能力匹配：在上述空间范围内，筛选出所有已在"设备语义管理"中配置了当前语义 Key（如
light_power）映射的设备 - 上下文消歧：若用户明确指定了设备别名（如"主灯"），在上述结果中进一步过滤别名匹配的设备；若未指定，则命中全部
3.3 数值边界与多设备交集算法
适用于温度、亮度等数值调节场景：
单设备场景：滑块的 min/max/step 直接取自该设备在"设备语义管理"中配置的物理量程（range）和步长（step）。量程不可由管理员在空间侧修改，统一以 IoT 设备上报的物理边界为准。
多设备场景：滑块的 min/max/step 取所有受控设备的共享交集区间——min 取各设备 range 最小值中的最大值，max 取各设备 range 最大值中的最小值，step 取各设备的最小步长。例如设备 A 的量程为 14~28℃、设备 B 为 16~30℃，则交集为 16~28℃。
边界拦截逻辑：当用户设定的目标值超出交集范围时，不强停拒绝，而是由系统自动修正为目标值最近的合法边界值（低于下限则取下限，高于上限则取上限），同时在确认卡片的执行动作行追加提示文案告知用户做了修正。
4. 异常与回执
| 响应时机 | 反馈逻辑 |
|---|---|
| 执行中 | 按钮文字变为“执行中... (1/2)”，显示设备颗粒度的反馈。 |
| 边界拦截 | 不直接强停，而是基于 共享区间 (Shared Range) 自动修正指令，并推送带文案提示的调节卡片。卡片滑块的 min/max 物理边界 必须动态调整为所有受控设备的 交集区间 (Intersection)。例如：A 为 14-24，B 为 16-28，则滑块范围强制限定在 16-24。 |
| 设备重名 | 若空间内有两个同名设备（Admin 配置错误），显示设备序列号后缀。 |