SA 空间控制面板设计 (Space Console Panel v1.0)

版本: v1.0 日期: 2026-05-28 状态: 初始设计版目标: 定义基于"数据类型驱动 + 特例白名单"的空间级统一控制面板架构，替代原有的"预设模板"模式，彻底解决扩展性问题。

0. 设计原则

0.1 纯数据类型驱动

面板渲染器仅依赖标准语义的 data_type 决定 UI 组件，不预置任何业务语义的布局假设：

数据类型	一级面板交互	二级面板组件
`bool`	switch 开关，直接切换	不进二级面板
`enum`	显示当前值 + `>` 箭头	选项列表
`number`	显示当前值 + `>` 箭头	数值调节组件
*`ro` 只读	显示实时值（无齿轮）	不进二级面板

0.2 纯数据类型驱动（无特例白名单）

M3 阶段不引入特例白名单。所有标准语义无论 key 是什么，统一按 data_type 渲染对应通用组件。

P2 演进预留：当需要增强特定语义的交互体验（如 hvac_target_temp 的温控环），可通过白名单机制注册专用 UX 组件，详见 §8.2。

0.3 整备链路与面板渲染彻底解耦

智能整备 Agent：负责触发判定 + 消息推送，不关心面板内容
空间逻辑映射：面板唯一数据源，零额外配置
面板渲染引擎：纯数据驱动，不感知业务语义

1. 架构分层

┌─────────────────────────────────────────────────┐
│                   用户触点                        │
│  (Chatbot / 模板消息 / 小程序)                    │
└──────────────────────┬──────────────────────────┘
                       │ 唤起（room_id + 空间映射语义列表）
                       ▼
┌─────────────────────────────────────────────────┐
│          一级面板：空间控制面板列表                │
│  按数据类型逐行渲染（bool/enum/number/ro）        │
│  数据来自：空间逻辑映射的语义列表                  │
└──────┬──────────────────────────────────────────┘
       │ 点击 boo / number / enum 行
       ▼
┌─────────────────────────────────────────────────┐
│          二级面板：语义详情交互                    │
│                                                   │
│  ┌─ 通用 number ───┐                              │
│  │  [====●=====]   │                              │
│  │  24°C           │                              │
│  └─────────────────┘                              │
│  ┌─ 通用 enum ────┐                               │
│  │ ○ 制冷  ● 制热  │                               │
│  │ ○ 送风         │                               │
│  └─────────────────┘                              │
└───────────────────────────────────────────────────┘

1.1 面板数据链路

面板渲染所需数据全部取自空间逻辑映射，取数链路如下：

空间逻辑映射（每条映射记录）
  │
  ├─ semantic_key ──→ 关联标准语义库 ──→ icon、name
  │
  ├─ data_type ──→ 决定渲染组件（bool/enum/number）
  │                   bool → switch 开关，不进二级面板
  │                   enum → 选项列表
  │                   number → 滑块
  │
  ├─ role ──→ 分组归类
  │             RW → "可操作能力"
  │             RO → "环境感知"（仅展示）
  │
  ├─ value ──→ 当前实时值（自控平台同步）
  │
  ├─ range/step ──→ number 量程与步长（自控平台逻辑点位）
  │
  ├─ options ──→ enum 可选列表（自控平台枚举定义）
  │
  └─ unit ──→ 数值单位（如 ℃、%、ppm），P2 接入自控平台 unit 字段

bool 显示映射：true → ● 开（switch ON），false → ○ 关（switch OFF），直接切换不进二级面板。

number 单位显示：优先使用 unit 字段，M3 按 semantic_key 约定兜底（temp 类 → °C，humi 类 → %，co2 类 → ppm）。

icon 取数：通过 mapping.semantic_key 关联标准语义库的 icon 字段。未配置 icon 的语义不展示图标。

2. 一级面板：极简列表

2.1 原型

text

+---------------------------------------------------+
| [ < 返回 ]  A-101 空间控制                  [ × ] |
+---------------------------------------------------+
|                                                    |
|  ===== 可操作能力 =====                            |
|                                                    |
|  空调开关                                  ● 开  > |
|  运行模式                                  制冷  > |
|  设定温度                                  24°C > |
|  灯光开关                                  ● 开  > |
|  灯光亮度                                  80%  > |
|  窗帘位置                                  50%  > |
|                                                    |
|  ===== 环境感知 =====                              |
|                                                    |
|  室内温度                                  28°C    |
|  室内湿度                                  65%     |
|  二氧化碳                                  450ppm  |
|                                                    |
+---------------------------------------------------+
|                                            [ 关闭 ] |
+---------------------------------------------------+

2.2 行类型明细

类型	左显示	值来源	右组件	点击行为
`bool` (RW)	icon + 名称	`value`（true/false）	switch 开关	直接切换，不进二级面板
`enum` (RW)	icon + 名称	`value`（当前选项）	选项文字 + `>`	进入二级面板
`number` (RW)	icon + 名称	`value` + `unit`	数值 + 单位 + `>`	进入二级面板
`ro`	icon + 名称	自控平台实时上报	数值 + 单位	仅展示，不可点击

2.3 视觉规范

行前缀 Icon：Font Awesome 图标 14px、#64748B。无 icon 配置时不展示
行名：icon + 空格 + 语义名称，14px（#1E293B），font-weight 500
数值显示：
- number：数值 + 单位（如 24°C、80%），14px（#8F959E）
- bool：switch 组件，ON 态 #3370FF，OFF 态 #E4E6EB
- enum：当前选项文字，14px（#8F959E）
- ro：数值 + 单位，14px（#8F959E）
> 箭头：#CBD5E1，18px
行高：48px，分割线 0.5px #F2F3F5
分组标题：可操作能力 / 环境感知（RW → 可操作，RO → 环境感知），12px font-weight 600 #8F959E

3. 二级面板：语义详情交互

3.1 通用 `number` 组件（纯滑块）

text

+---------------------------------------------------+
| [ < 返回 ]  设定温度                        [ × ] |
+---------------------------------------------------+

              目标温度 (滑动调节)

    ───────────────●────────────────    24°C
         16                          30

+---------------------------------------------------+
|              [ 保存应用到现场 ]                     |
+---------------------------------------------------+

量程 range 和步长 step 继承自空间逻辑映射
用户滑动实时显示数值
点击「保存应用」→ 下发指令 + 对话反馈
无快捷预设标签

3.2 通用 `enum` 组件（选项列表）

text

+---------------------------------------------------+
| [ < 返回 ]  运行模式                        [ × ] |
+---------------------------------------------------+

              当前: 制冷

  ○ 自动
  ● 制冷
  ○ 制热
  ○ 送风

+---------------------------------------------------+
|              [ 保存应用到现场 ]                     |
+---------------------------------------------------+

选项列表从空间逻辑映射中获取
选中态：左侧实心圆 + 高亮行
点击某选项即时更新，点击「保存应用」下发

| [ < 返回 ] 设定温度 [ × ] | +---------------------------------------------------+

          /---------\
         |    24℃    |
          \---------/

       目标温度 (滑动调节)

───────────────●────────────────
     16                          30

[ 16℃ 强劲 ]  [ 24℃ 舒适 ]  [ 26℃ 节能 ]

+---------------------------------------------------+ | [ 保存应用到现场 ] | +---------------------------------------------------+


**快捷预设数据来源**：

面板唤起 → 判断 payload 是否含 quickOptions → 有 → 渲染传入的快捷按钮（整备链路） → 无 → 查 temp-presets.json 按当前月份自算（主动唤出链路）


**快捷预设组件参数**（由 `SPECIAL_UX` 注册表定义）：

```json
{
  "semantic_key": "hvac_target_temp",
  "component": "TempRingDetail",
  "params": {
    "quick_presets_source": "temp-presets.json"
  }
}

4. 特例白名单机制（架构预留）

M3 阶段白名单为空，所有语义按 data_type 渲染通用组件。架构上预占白名单注册表，供后续扩展：

const SPECIAL_UX = {
  // M3: 空 — 无特例
  // P2 示例:
  // 'hvac_target_temp': { component: 'TempRingDetail', params: { quick_presets: true } }
}

4.1 渲染决策流

取到一行的 semantic_key
  → 在 SPECIAL_UX 中查找
    → 命中 → 使用注册的专用组件
    → 未命中 → 按 data_type 使用通用组件（M3 全量走此分支）

4.2 P2 演进方向：后台 UX 组件管理页

在管理后台新增"UX 组件管理"页面，功能：

查看所有已注册的标准语义与对应 UX 组件
支持将标准语义绑定到不同的 UX 组件
暴露组件可配置参数## 5. 快捷预设（暂不涉及）

M3 阶段不引入快捷预设。所有 number 类型语义仅展示纯滑块，无快捷标签。

P2 演进：当特例白名单启用后，hvac_target_temp 可由整备 Agent 携带 quickOptions 入参，或通过 temp-presets.json 内置策略表自算，详见 §8.2。

6. 与 device-control.html（设备级控制）的边界

维度	空间控制面板（本文档）	device-control.html
作用对象	空间级逻辑映射（SSOT）	物理设备实例
语义隔离	屏蔽设备数量与位置	精确到"左侧空调"
入口	整备卡片 / 主动唤出	用户精确指令
渲染依据	空间逻辑映射语义列表	设备能力透视 mappings
呈现形式	极简列表 + 二级面板	设备清单卡片

7. 状态与异常处理

7.1 加载态

面板拉起时，先显示骨架屏（灰色 placeholder 行），待空间逻辑映射数据返回后替换为实际内容。

7.2 空态

若空间逻辑映射中未配置任何语义，面板显示：

text

┌─────────────────────────────────────┐
│ 该空间暂无可用控制能力               │
│ 请联系管理员在"空间逻辑映射"中配置   │
└─────────────────────────────────────┘

7.3 错误态

数据加载失败时，显示通用错误提示 + [重试] 按钮。

7.4 指令执行反馈

成功：Toast 提示"指令已下发到现场设备"
失败：Toast 提示"指令下发失败" + 保留当前面板状态，允许用户重试
超时：Toast 提示"设备响应超时，请稍后重试"

8. 附录

8.1 执行计划

阶段	范围	交付物
M3 短期	一级面板（列表）+ 通用二级面板（number/enum）	面板渲染引擎（纯数据类型驱动）
P2 长期	特例白名单 + 温控仪表盘聚合视图（选项 B）	白名单注册 + 组件参数暴露；hvac_target_temp 专用组件 + temp-presets.json

8.2 演进预留：温控仪表盘 (P2)

当空间逻辑映射同时包含 hvac_power + hvac_target_temp + hvac_mode + env_indoor_temp 四个温控黄金语义时，一级面板可将温度相关行合并为一个聚合入口：

text

一级面板（聚合模式）
┌─────────────────────────────┐
│ …                           │
│ 🌡️ 温度控制          24°C > │ ← 聚合入口
│ …                           │
└─────────────────────────────┘

点击进入温控仪表盘：

text

┌─────────────────────────────┐
│    /---------\              │
│   |    24℃    |             │
│    \---------/              │
│  ●开  ❄️ 制冷  室内 28°C     │
│                             │
│ ═══════●══════════          │
│ 16                     30   │
│ [16°C][24°C][26°C]          │
│                             │
│       [ 保存应用 ]           │
└─────────────────────────────┘

设计约束：仪表盘内 hvac_power、hvac_mode、env_indoor_temp 仅为只读上下文，用户不能在此面板中修改它们。单行入口仍各自独立存在于一级面板，互不冲突。

SA 空间控制面板设计 (Space Console Panel v1.0) ​

0. 设计原则 ​

0.1 纯数据类型驱动 ​

0.2 纯数据类型驱动（无特例白名单） ​

0.3 整备链路与面板渲染彻底解耦 ​

1. 架构分层 ​

1.1 面板数据链路 ​

2. 一级面板：极简列表 ​

2.1 原型 ​

2.2 行类型明细 ​

2.3 视觉规范 ​

3. 二级面板：语义详情交互 ​

3.1 通用 number 组件（纯滑块） ​

3.2 通用 enum 组件（选项列表） ​

4. 特例白名单机制（架构预留） ​

4.1 渲染决策流 ​

4.2 P2 演进方向：后台 UX 组件管理页 ​

6. 与 device-control.html（设备级控制）的边界 ​

7. 状态与异常处理 ​

7.1 加载态 ​

7.2 空态 ​

7.3 错误态 ​

7.4 指令执行反馈 ​

8. 附录 ​

8.1 执行计划 ​

8.2 演进预留：温控仪表盘 (P2) ​

SA 空间控制面板设计 (Space Console Panel v1.0)

0. 设计原则

0.1 纯数据类型驱动

0.2 纯数据类型驱动（无特例白名单）

0.3 整备链路与面板渲染彻底解耦

1. 架构分层

1.1 面板数据链路

2. 一级面板：极简列表

2.1 原型

2.2 行类型明细

2.3 视觉规范

3. 二级面板：语义详情交互

3.1 通用 `number` 组件（纯滑块）

3.2 通用 `enum` 组件（选项列表）

4. 特例白名单机制（架构预留）

4.1 渲染决策流

4.2 P2 演进方向：后台 UX 组件管理页

6. 与 device-control.html（设备级控制）的边界

7. 状态与异常处理

7.1 加载态

7.2 空态

7.3 错误态

7.4 指令执行反馈

8. 附录

8.1 执行计划

8.2 演进预留：温控仪表盘 (P2)