2026 AI 空间智能体 - 产品语义管理 PRD (v1.1)

版本: v1.1 日期: 2026-06-02 状态: 原型已实现目标: 构建统一的"产品语义管理"页面，实现物理设备产品的点位映射配置从设备实例级上移至产品级，消除重复配置，减轻 LLM 上下文负担。

1. 核心设计理念

1.1 职责再定义

层级	职责	对应页面
🧬 标准语义管理	定义 Key 是什么 + 品类级自动对账建议	`iot-semantics.html`（已有）
📦 产品语义管理	定义 Key 具体怎么用：label/range/step/AI指引	`iot-products.html`（新增）
💡 设备语义管理	引用产品映射 + 别名 + 生效开关	`iot-devices.html`（精简）

1.2 数据继承链路

标准语义库 (Key 定义)
  │
  └─ 产品品类 (category_id) ← 品类级 default_props（自动对账建议）
       │
       └─ 产品 (Product) ← 产品级映射配置（label/range/step/AI指引）← 本页面
            │
            └─ 设备实例 (Device) ← 继承产品映射（只读）

1.3 核心术语

术语	说明
产品分组	自控平台的组织树，平层结构（冷热源、照明等），纯用户偏好，无业务含义
产品品类	标准语义关联的品类分类（照明、暖通空调、环境感知等），用于 default_props 匹配
点位 (Signal)	自控平台的产品逻辑信号，导入时自动同步。包含 signal_name（标识符）和 signal_label（中文名称）

1.4 核心流程

Step 1: 导入产品
  └─ 从自控平台同步该产品的所有信号点位
  └─ 各点位的 values/label/min/max/step/unit 直接带入自控默认值
  └─ 通过 category_id + signal_name 匹配标准语义 default_props，自动填入 semantic_key

Step 2: 点位筛选与配置
  └─ 列表中展示全部点位，switch 滑块控制启用/禁用
  └─ 为启用的点位选择标准语义（按 data_type + access 强制过滤）
  └─ 齿轮展开配置详情：label（bool/enum）、min/max/step（number）、AI指引

Step 3: 保存生效
  └─ 校验已启用点位：semantic_key 必填、label 必填、min/max/step 必填
  └─ 仅 enabled=true 的点位进入 LLM 上下文

2. 界面布局与导航

2.1 入口位置

在系统主导航栏新增 📦 产品管理 入口，位于 🧬 标准语义 和 🏢 空间管理 之间。

2.2 三栏式架构

复用空间/设备管理的三栏布局：

左一栏 (App Nav)：导航图标
左二栏 (产品分组树)：自控平台的产品分组，平层结构
右侧主工作区：产品列表 + 搜索/导入

3. 交互原型

3.1 主列表页面

+----------------+--------------------------+-------------------------------------------------------------+
| [APP NAV]      | [ 产品分组树(自控)      ] |  首页 / 产品管理 / 全部产品                                   |
+----------------+--------------------------+-------------------------------------------------------------+
|                |                          |                                                             |
|  [🧬] 语义标准 |  . 全部产品               |  筛选: [ 全部产品分组 v ]   搜索: [ 产品名称或标识符...  ]     |
|                |  . 冷热源                 |  [ + 导入产品 ]                                              |
|  [📦] 产品管理 |  . 环境监测               |  +---------------------------------------------------------+ |
|  (Active)      |  . 照明                   |  | 产品分组 | 产品品类名称 | 产品名称 | 产品标识符 | 总点位 | 已启用 | 操作 | |
|                |  . 文体中心               |  |----------|--------------|----------|------------|--------|--------|------| |
|  [🏢] 空间管理 |  . 测试                   |  | 照明     | 照明         | 灯产品   | prod_light | 4     | 2      | 编辑 | |
|                |  . 产品分组               |  | 照明     | 照明         | 灯带产品 | prod_strip | 2     | 1      | 编辑 | |
|  [💡] 设备管理 |                          |  | 冷热源   | 暖通空调     | 大金空调 | prod_daikin| 5     | 3      | 编辑 | |
|                |                          |  | 冷热源   | 暖通空调     | 美的空调 | prod_midea | 4     | 3      | 编辑 | |
|                |                          |  +---------------------------------------------------------+ |
+----------------+--------------------------+-------------------------------------------------------------+

3.1.1 关键交互说明

左侧产品分组树：数据源来自自控平台的产品分组，支持多级树形结构（冷热源、环境监测、照明等）。与标准语义库的品类不是同一概念。选中任一分组，右侧列表过滤该分组及其子分组下的产品。分组仅做只读展示，不提供增删改操作。
产品品类名称列：标准语义品类分类（照明、暖通空调等），用于标识该产品关联的标准语义域。
总点位列：该产品从自控同步过来的总信号点位数量。
已启用列：已开启给 AI 使用的点位数量（enabled=true）。
操作列：仅提供 [编辑] 按钮，点击打开配置详情抽屉。

3.2 产品导入弹窗

+-----------------------------------------------------------------------------------+
|  从自控平台导入产品                                                       [ X ]   |
+-----------------------------------------------------------------------------------+
|  💡 温馨提示：导入后自动同步该产品所有信号点位，点位默认禁用。需在详情中启用并配置。   |
+-----------------------------------------------------------------------------------+
|  产品品类: [ 照明 v ]             产品名称: [ 灯产品                    ]  [搜索]   |
+-----------------------------------------------------------------------------------+
|  [ ] | 所在分组 | 产品品类 | 产品名称 | 产品标识符                                  |
|  ----|----------|----------|----------|-------------                                  |
|  [ ] | 照明     | 照明     | 灯产品   | prod_light                               |
|  [ ] | 照明     | 照明     | 筒灯产品 | prod_bulb_02                                |
|  [ ] | 冷热源   | 暖通空调 | 大金空调 | prod_daikin                              |
+-----------------------------------------------------------------------------------+
|  ⚠️ 已导入产品不展示，不可重复导入                                                  |
+-----------------------------------------------------------------------------------+
|                                              [ 取消 ]   [ 确认导入 (N) ]           |
+-----------------------------------------------------------------------------------+

3.2.1 导入逻辑细节

查询条件：支持按"产品品类"（标准语义品类）下拉筛选 + "产品名称"模糊搜索。
防重机制：已导入 AI 系统的产品在列表中不展示（名称级别去重），防止重复导入。
确认导入：点击导入后，系统从自控平台拉取该产品的所有信号点位，写入 mappings[] 数组，所有点位 enabled=false。
点位自动对账：导入时通过 category_id + signal_name 匹配标准语义 default_props，自动填入 semantic_key。无法匹配的留空待手动选择。
初始值：自控点位定义的 signal_label、values、min/max/step、unit 直接作为默认值写入。

3.3 产品配置详情抽屉

+---------------------------------------------------------------+
|  产品配置详情: 灯产品                                   [ X ] |
+---------------------------------------------------------------+
|                                                               |
|  == 基础信息 ==                                                |
|  产品品类:  照明                    产品名称:  灯产品            |
|  产品标识符: prod_light         产品分组:  照明              |
|                                                               |
|  == 点位映射配置 (Point Mapping Config) ==                      |
|                                                               |
|  筛选: [ 全部点位 v ]   搜索: [ 搜索点位名称...  ]  [🔄 重新同步]|
|  总点位: 4   已启用: 2   未启用: 2                              |
|                                                               |
|  +-------------------------------------------------------------+ |
|  | [switch]  照明开关 (LightSwitch)        语义: [灯具开关 v][⚙️]| |
|  |           [布尔(Bool)][读写(RW)] 0→关闭, 1→开启         | |
|  |  ─── 展开详情 (AI 语义配置) ───                             | |
|  |  * false (0) → [关闭]   * true (1) → [开启]                | |
|  |  AI 指引: [控制灯具开关...]                                  | |
|  +-------------------------------------------------------------+ |
|                                                               |
|  +-------------------------------------------------------------+ |
|  | [switch]  亮度调节 (LightBrightness)    语义: [亮度调节 v][⚙️]| |
|  |           [数值(Num)][读写(RW)] min=0,max=100,step=1   | |
|  |  ─── 展开详情 (AI 语义配置) ───                             | |
|  |  * 步长: [1]  范围: [0] — [100]  单位: [%]                 | |
|  |  AI 指引: [数值越大越亮...]                                  | |
|  +-------------------------------------------------------------+ |
|                                                               |
|  +-------------------------------------------------------------+ |
|  | [switch]  色温调节 (LightColorTemp)    语义: [色温调节 v][⚙️]| |
|  |           [数值(Num)][读写(RW)] min=2700,max=6500,...   | |
|  |  已禁用                                                      | |
|  +-------------------------------------------------------------+ |
|                                                               |
+---------------------------------------------------------------+
|                                      [ 取消 ]   [ 保存生效 ]  |
+---------------------------------------------------------------+

3.3.1 基础信息

3.3.2 点位映射卡片

每条点位映射为一张紧凑卡片，核心布局：

┌──────────────────────────────────────────────────────────────────┐
│ [switch]  点位名称 (signal_name)          语义: [标准语义下拉 v][⚙️]│
│           [类型标签][角色标签] 摘要信息  单位: xxx  (状态提示)    │
└──────────────────────────────────────────────────────────────────┘

交互说明：

区域	功能
switch 滑块	控制点位启用/禁用。禁用后卡片半透明，底部显示"已禁用"状态
点位名称	显示 `signal_label (signal_name)`，如"照明开关 (LightSwitch)"
标准语义下拉	关联的标准语义 Key。已匹配显示绿色边框+对勾，未匹配显示橙色+警告
齿轮 ⚙️	展开/收起详情配置面板

标准语义下拉过滤规则（重要）：

标准语义下拉列表按以下两条规则强制过滤，仅显示兼容的选项：

产品点位条件	可选的语义条件
`data_type=bool` → 仅显示 `type=Boolean` 的语义	`data_type=enum` → 仅显示 `type=Enum` 的语义
`data_type=number` → 仅显示 `type=Number` 的语义	`access=rw` → 仅显示 `role=rw` 的语义
`access=ro` → 仅显示 `role=ro` 的语义

初始值自动带入：产品导入时，如果该产品所属的品类已在标准语义管理中配置了 default_props（品类→逻辑标识符映射），则系统按 category_id + signal_name 自动匹配并填入 semantic_key 作为下拉初始值。匹配失败则留空，需管理员手动选择。

快捷新建标准语义：当语义下拉列表中没有匹配兼容选项时，管理员可选择列表最底部的 +新建标准语义 选项，直接在弹窗中创建新的标准语义项，无需跳转至标准语义管理 iot-semantics.html 页面。

+---------------------------------------------------------------+
|  新建标准语义                                          [ X ]  |
+---------------------------------------------------------------+
|                                                               |
|  == 核心定义 (Metadata) ==                                     |
|                                                               |
|  所在业务分类: [ 照明系统 v ]  ← 对齐语义页面的业务分类目录       |
|                                                               |
|  标准 Key: [ light_brightness_custom    ]  ← 唯一标识           |
|                                                               |
|  语义友好名称: [ 自定义亮度调节          ]                      |
|                                                               |
|  数据类型: [ Boolean(布尔) v ]  [disabled]    ║               |
|  业务角色: [ RW(读写)   v ]  [disabled]    ║ ← 点位自动推导|
|                                                               |
|  == MCP / LLM 推理增强描述 ==    [LLM REASONING]               |
|  ┌─ 该描述将通过 MCP... ──────────────────────────────────────┐ |
|  │ 该描述将通过 MCP 工具元数据直接喂给 Agent，用于辅助意图识别。  │ |
|  │                                                             │ |
|  │ [ 输入面向 AI 的操作描述...                      ]          │ |
|  └─────────────────────────────────────────────────────────────┘ |
|                                                               |
+---------------------------------------------------------------+
|                                    [ 取消 ]   [ 创建并选中 ]  |
+---------------------------------------------------------------+

交互说明：

区域	说明
数据类型 / 业务角色	从当前点位 `data_type` + `access` 自动推导，置灰不可编辑。显示布尔/读写等标签
所在业务分类	下拉选择器，选项对齐 `iot-semantics.html` 侧边栏"业务分类目录"：暖通空调、照明系统、遮阳与幕布、环境感知
标准 Key	必填。系统内唯一标识符，输入后通过 `SemanticUtils.findItem()` 校验重复
语义友好名称	必填。语义的中文友好名称
LLM 推理增强描述	推荐填写。该描述将通过 MCP 工具元数据喂给 Agent，用于辅助意图识别
创建并选中	校验通过后写入 `StandardSemantics[品类].items`，下拉自动选中新建项（绿色边框）
取消	关闭弹窗，下拉恢复到之前的值

3.3.3 齿轮详情配置面板

数据类型	配置区内容	必填项
Boolean	`false (0) → [关闭]`、`true (1) → [开启]`、AI指引	label 必填
Enum	各枚举值 label 输入框、AI指引	label 必填
Number	步长输入框、最小/最大值输入框、单位、AI指引	min/max/step 必填

AI 指引为非必填，不校验。

3.3.4 重新同步

点击 [🔄 重新同步] 按钮，重新从自控平台拉取该产品的最新信号点位列表：

新增点位：追加到列表末尾，enabled=false
已删除点位：保留在列表中但标记为 [💀 点位已失效]，不可再启用，需手动移除
存量点位：保持其 enabled 状态不变

3.3.5 保存与校验

点击 [保存生效] 时执行以下校验流程：

1. 收集数据：遍历所有点位的展开详情面板，更新 values/label/min/max/step/unit/AI指引
2. 校验已启用的点位：
   ├── semantic_key 不可为空 → 报错："[点位名] 标准语义未选择"
   ├── Boolean/Enum 各 value 的 label 不可为空 → 报错："[点位名] 值 x 的 label 未填写"
   └── Number 的 min/max/step 不可为空 → 报错："[点位名] 最小值/最大值/步长未填写"
3. 任意校验不通过 → 弹出 Toast 错误提示（最多显示前 3 项）→ 阻止保存
4. 全部通过 → 关闭抽屉 → 刷新列表 → Toast 成功提示

4. 与上下游的关系

4.1 与标准语义管理的关系

标准语义的 default_props（品类→逻辑标识符映射）作为产品点位导入时的自动对账依据
产品点位导入时，按 category_id + signal_name 在 default_props 中查找匹配的 semantic_key
匹配成功则自动填入，失败则留空待手动选择

4.2 与设备语义管理的关系

产品管理是设备管理的"上游"
设备实例引入后自动关联其 product_id，点位映射直接继承产品级配置
设备抽屉中不再包含点位映射编辑，仅展示从产品继承的只读信息

4.3 与空间逻辑映射的关系

空间逻辑映射中"设备升维"行的映射配置继承自产品映射，空间侧只读
如需修改设备升维的 label/AI指引 → 请到本页面的对应产品中修改

5. 数据模型 (`ai_product_mappings`)

5.1 产品表

字段	类型	说明
`id`	UUID	主键
`name`	String	产品名称
`group_id`	String	自控产品分组 ID（用于左侧树过滤）
`category_id`	String	产品品类 ID（关联标准语义品类，用于 default_props 匹配）
`category_name`	String	产品品类名称
`identifier`	String	自控平台产品唯一标识符
`mappings`	JSON	点位映射配置数组

5.2 mappings[] 详细 Schema

字段	类型	必填	说明
`signal_name`	String	Yes	自控平台逻辑信号标识符（只读）
`signal_label`	String	No	自控平台逻辑信号中文名称（只读）
`data_type`	Enum	Yes	`bool` / `enum` / `number`（只读）
`access`	Enum	Yes	`rw` / `ro`（只读）
`enabled`	Boolean	Yes	是否启用给 AI 使用（默认 false）
`semantic_key`	String	No	关联的标准语义 Key
`values`	JSON	No	Bool/Enum label 映射表，如 `{"0":"关闭","1":"开启"}`
`min`	Float	No	Number 最小值
`max`	Float	No	Number 最大值
`step`	Float	No	Number 步长
`unit`	String	No	单位（可自定义编辑）
`ai_instruction`	Text	No	AI 指引说明

6. 与现有标准语义管理的关系说明

标准语义管理（iot-semantics.html）保持不变，继续负责：

定义标准 Key、名称、数据类型、业务角色
管理品类分类（HVAC、照明等）
维护 default_props（品类→逻辑标识符映射）

产品管理页面的左侧分组树数据源来自自控平台的产品分组体系，与标准语义管理的品类分类无关。

7. 产品分组映射关系

自控分组	产品示例	品类	标准语义域
照明	灯产品、灯带产品、筒灯产品	照明 (LIGHT)	light_power, light_brightness
冷热源	大金空调、美的空调	暖通空调 (HVAC)	hvac_power, hvac_mode, hvac_target_temp
环境监测	温湿度传感器	环境感知 (SENSE)	env_indoor_temp, env_humidity

8. 文件清单

新增文件

文件	说明
`iot-products.html`	产品管理页面
`js/products/store.js`	产品数据 mock + state
`js/products/main.js`	列表渲染 + 导入逻辑
`js/products/drawer-view.js`	配置抽屉渲染
`js/products/drawer.js`	抽屉业务逻辑

文档终

2026 AI 空间智能体 - 产品语义管理 PRD (v1.1) ​

1. 核心设计理念 ​

1.1 职责再定义 ​

1.2 数据继承链路 ​

1.3 核心术语 ​

1.4 核心流程 ​

2. 界面布局与导航 ​

2.1 入口位置 ​

2.2 三栏式架构 ​

3. 交互原型 ​

3.1 主列表页面 ​

3.1.1 关键交互说明 ​

3.2 产品导入弹窗 ​

3.2.1 导入逻辑细节 ​

3.3 产品配置详情抽屉 ​

3.3.1 基础信息 ​

3.3.2 点位映射卡片 ​

3.3.3 齿轮详情配置面板 ​

3.3.4 重新同步 ​

3.3.5 保存与校验 ​

4. 与上下游的关系 ​

4.1 与标准语义管理的关系 ​

4.2 与设备语义管理的关系 ​

4.3 与空间逻辑映射的关系 ​

5. 数据模型 (ai_product_mappings) ​

5.1 产品表 ​

5.2 mappings[] 详细 Schema ​

6. 与现有标准语义管理的关系说明 ​

7. 产品分组映射关系 ​

8. 文件清单 ​

新增文件 ​