9. 结构管理

9.0 快速上手：5 分钟构建设备层级结构

你有一台「空压机-A01」及其子部件（电机、冷却装置、保护装置），需要在系统中建立设备间的层级关系，供组合点检和维护计划使用。

Step 1：新建结构版本

进入「设备结构编辑器」→ 点击「+ 新建」→ 输入版本名称 空压机结构v1 → 保存。 → 详见 §9.3.2

Step 2：创建根节点

选中刚创建的版本 → 点击「➕ 添加根节点」→ 输入节点名称 空压机-A01 → 关联设备 空压机-A01 → 保存。 → 详见 §9.3.3

Step 3：添加子节点

在结构树中点击根节点选中它 → 点击「➕ 添加子节点」→ 依次创建：

• 电机（关联设备 空压机-A01-电机）
• 冷却装置（关联设备 空压机-A01-冷却装置）
• 保护装置（关联设备 空压机-A01-保护装置） → 详见 §9.3.3

Step 4：拖拽调整层级关系

如需调整节点归属（如将「保护装置」移到「电机」下），直接拖拽节点到目标父节点上即可。 → 详见 §9.3.4

Step 5：发布并设为当前

点击「发布」按钮将版本发布，再点击「设为当前」使其成为系统当前生效版本，供组合点检/组合维护使用。 → 详见 §9.3.2

💡 完成以上步骤后，你已在系统中建立了「空压机-A01 → 电机 / 冷却装置 / 保护装置」的三级设备结构。组合点检和维护计划基于**当前生效版本（Active）**的结构树自动为所有子设备生成工单。如需修改结构，请通过「复制为新版本」创建副本后编辑，已发布版本为只读。

---

9.1 功能概述

本章介绍「结构管理」菜单组下的两个子模块。结构管理是设备运维系统的核心基础模块，定义了设备之间的层级隶属关系（Bill of Equipment, BoE），为组合点检、组合维护、BIM 可视化等上层功能提供数据底座：

模块	定位	核心功能
设备结构编辑器	设备层级结构编辑	版本选择/新建、根节点/子节点 CRUD、拖拽排序、节点关联设备、导入导出（JSON/CSV）、版本对比与回滚、节点 BIM 定位
版本管理	结构版本生命周期管理	版本列表、新建版本（含从已有版本复制）、发布/取消发布、设为当前版本、复制为新版本

结构管理采用版本化设计：每次编辑需要创建新版本，发布后方可被其他模块引用。当前生效版本（Active）为系统运行时使用的结构树。

---

9.2 页面入口

• PC端：左侧菜单「结构管理」（PartitionOutlined 分区树形图标）→ 两个子菜单：「设备结构编辑器」「版本管理」
• 移动端：结构管理为管理员功能，移动端不直接暴露结构编辑入口，但移动端的组合点检/维护工单会使用当前版本的结构树

菜单可见性由权限控制：

子模块	菜单可见条件	新增/编辑/删除权限
设备结构编辑器	equipment:view	equipment:structure:manage（新增/编辑/删除节点、新建版本）
版本管理	equipment:view	equipment:structure:manage（创建/发布/取消发布/设为当前）

---

9.3 PC端 - 设备结构编辑器

9.3.1 页面布局

设备结构编辑器是结构管理的主要操作界面，采用左右分栏布局：

1. 左侧区域 — 控制面板

   • 版本选择区：下拉选择当前编辑版本，显示版本名称和状态标签（已发布/当前），下方有版本操作按钮（新建/发布/取消发布/设为当前）
   • 节点操作区：「添加根节点」按钮（创建顶级节点）、「添加子节点」按钮（在选中节点下创建子节点）、只读提示信息
   • 导入导出区：JSON/CSV 导出按钮、导入按钮
   • 版本对比面板（折叠面板）：选择版本A/版本B进行差异对比，查看新增/删除/移动/修改的节点数和设备映射变化

2. 右侧区域 — 结构树展示

   • 卡片标题显示「设备结构树」+ 节点总数徽标
   • 工具栏按钮：刷新、展开全部、📍 BIM 定位（需先在树中选中节点）
   • 结构树：树形展示所有节点，每行含节点名称、节点ID、关联设备ID
   • 每行操作按钮：编辑（✏️）、BIM定位（📍）、删除（🗑️，确认后删除）

版本选择后自动加载该版本的节点树，节点树默认全部展开。展开/折叠状态可手动控制。

9.3.2 版本操作

9.3.2.1 新建版本

点击版本选择器旁的「+ 新建」按钮，打开创建新版本弹窗：

字段	说明	必填
版本名称	版本描述名称，如「2025年设备布局v2」	是
版本ID	版本唯一标识，留空自动生成（如 VER-1746000000000）	否
复制自版本	从已有版本复制节点数据（下拉选择），不选则为空版本	否
立即发布	开关，创建后是否立即发布	否

9.3.2.2 发布 / 取消发布 / 设为当前

版本操作按钮位于版本选择器下方：

• 发布：将当前版本标记为已发布。已发布的版本为只读，不可编辑节点，但可被其他模块引用。

  💡 发布接口支持 set_active 参数，可在发布的同时直接设为当前生效版本（一步完成发布+激活，当前前端界面暂未暴露此选项）。

• 取消发布：将已发布的版本恢复为草稿状态。需要确保系统中至少存在一个其他已发布版本。
• 设为当前：将已发布版本设为当前生效版本（Active）。系统中只有一个 Active 版本，设置时弹出确认对话框。设为当前后，组合点检/维护计划将使用此版本的结构树。

版本生命周期：草稿（编辑中）→ 发布（已发布/只读）→ 设为当前（成为运行时使用的版本）。如需修改已发布版本，请通过「版本管理」页面的「复制为新版本」创建副本后编辑。

9.3.3 节点操作

9.3.3.1 添加根节点

点击「➕ 添加根节点」按钮，打开新建节点弹窗：

字段	说明	必填
节点名称	节点的显示名称，如「空压机-A01」「1号车间」	是
节点ID	节点唯一标识，留空自动生成（格式 NODE-{时间戳}，如 NODE-1746000000000）	否
父节点	根节点操作时预置为空，可切换为其他节点	否
关联设备	从设备列表中搜索选择关联的设备（可选）	否
排序号	节点同级排序权重，默认 0，拖拽排序时自动维护，也可手动设置	否

关联设备在模块初始化时预加载全部设备到本地（每页 200 条），打开下拉框时补充增量加载，支持按设备名称本地搜索过滤。

9.3.3.2 添加子节点

在结构树中点击选中一个节点，然后点击「➕ 添加子节点」按钮：

• 弹窗与根节点弹窗相同，但「父节点」字段自动填充为当前选中的节点ID
• 父节点下拉框支持搜索过滤，可切换到其他节点作为父节点

9.3.3.3 编辑节点

在结构树中点击节点行右侧的「✏️」编辑按钮，打开编辑节点弹窗。弹窗内容与新建弹窗相同，但：

• 弹窗标题显示为「编辑节点」（新建模式下标题为「创建节点」）
• 节点ID在编辑模式下为只读（灰色禁用）

9.3.3.4 删除节点

点击节点行右侧的「🗑️」删除按钮，弹出确认提示：「确定删除这个节点吗？」，确认后删除该节点。

⚠️ 删除操作仅删除当前节点，不级联删除其子节点。如需删除子树，请从叶子节点开始逐级向上删除。

⚠️ 注意：当前版本删除操作暂未对已发布版本做只读拦截，请在删除前确认版本状态，避免误删已发布版本中的节点。

9.3.4 拖拽排序

结构树支持拖拽调整节点层级关系：

1. 拖拽到节点间隙：将节点移动为同级节点（与目标节点同级，通过拖拽位置决定前后顺序）
2. 拖拽到节点内部：将节点移动为目标节点的子节点

拖拽完成后，系统自动重新计算并持久化排序号（sort_order）。拖拽使用乐观并发控制（version hash），冲突时自动刷新。

❗ 拖拽操作仅在草稿状态版本可用，已发布版本不允许拖拽修改。

9.3.5 导入导出

9.3.5.1 导出

点击「JSON」或「CSV」按钮导出当前版本的节点数据：

• JSON 导出：下载格式化的 JSON 文件，包含完整的节点结构数据
• CSV 导出：下载 CSV 文件（带 BOM 解决 Excel 中文乱码），支持 Excel 打开编辑

9.3.5.2 导入

点击「导入」按钮，打开导入弹窗：

选项	说明
导入模式	「替换现有数据」（清空后导入）或「合并数据」（保留已有、新增/更新）
选择文件	上传 CSV 文件（.csv），下方提供模板下载链接（仅支持 CSV 文件上传；JSON 格式仅支持粘贴，不支持文件上传）
数据内容	可直接粘贴 JSON 格式的结构数据

导入支持 CSV（文件上传）和 JSON（文本粘贴）两种格式。导入前会进行数据校验（节点ID唯一性、无循环引用、深度不超过限制），校验失败会显示详细错误列表（错误行号+字段+原因）。已发布版本不允许导入（导入按钮在已发布版本下不会被禁用，但导入函数内部会拦截并提示）。

9.3.6 版本对比

点击左侧「版本对比」折叠面板展开对比功能：

1. 选择版本A和版本B（两个下拉框）
2. 点击「对比」按钮
3. 显示差异摘要：
   • 🌳 节点变化：新增节点数（绿色标签）、删除节点数（红色标签）、移动节点数（蓝色标签）、修改节点数（橙色标签）
   • 🔗 设备映射变化：新增映射数 / 移除映射数
   • 无差异时显示「✅ 两个版本完全相同，无差异」
   • 有差异时显示新增/删除节点的前 5 个标识（以设备ID为主键对齐，格式为 EQ::{equipment_id} 或 NM::{name}::ID::{node_id}）

9.3.7 回滚

回滚功能支持从历史版本创建新版本，底层通过 POST /api/v1/equipment-structure/versions/{new_version_id}/rollback 接口实现：系统从源版本复制所有节点数据到新版本（自动发布），并可选择将新版本设为当前 Active。前端 JS 逻辑已在 w1_structure.js 的 rollbackToNewVersion() 方法中完整实现，包含以下参数：

字段	说明	必填
来源版本（from_version_id）	要回滚的源版本	是
新版本ID（new_version_id）	回滚后新版本的ID（默认自动建议 VER-{Date.now()}）	是
新版本名称（name）	默认 Rollback of {来源版本ID}	否
创建后设为当前（set_active）	勾选后回滚完成自动设为 Active	否

💡 回滚的后端接口与前端 JS 逻辑已就绪，但 PC 端操作界面（表单+按钮）尚未集成到当前版本。如需恢复历史结构，请使用版本管理页面的「复制为新版本」功能——选择源版本复制到新版本后编辑发布。

9.3.8 BIM 定位

点击节点行右侧的「📍」按钮或工具栏中的「📍 BIM」按钮，系统自动在 BIM 模型中聚焦该节点关联的设备：

1. 查询节点的 equipment_id，调用 BIM 模块的 handleEquipmentFilterChange 按设备过滤并聚焦
2. 回退到后端 /viewer/focus 接口，按 nodeId + structureVersionId 查询设备映射关系
3. 后端返回聚焦类型：component（构件级，含 elementId 则调用 focusByElementId，失败回退 previewService.selectElement）或 mainDevice（主设备级，调用 focusOnEquipment；异常时进入通用回退链依次尝试 focusByMapping 或 focusOnEquipment）

BIM 定位需要系统中已上传 BIM 模型并完成设备映射配置。

---

9.4 PC端 - 版本管理

9.4.1 页面布局

版本管理页面以列表形式展示所有结构版本，并提供版本生命周期管理功能：

• 顶部工具栏：「刷新版本」按钮、「切换到结构编辑器」按钮
• 版本列表：每行显示版本名称、版本ID、状态标签（已发布）、创建时间。注意：版本管理列表仅显示"已发布"状态标签，当前生效版本（Active）标签仅在结构编辑器的版本选择器中可见
• 行操作按钮：
  • 编辑结构：切换到结构编辑器并加载该版本的节点
  • 复制为新版本：打开新建版本弹窗，自动填充「复制自版本」字段
  • 发布：将草稿版本发布（已发布版本此按钮不可用）
  • 取消发布：取消发布（草稿版本不显示此按钮）
  • 设为当前：将已发布版本设为当前生效版本（已是当前版本不可用）

9.4.2 复制为新版本

点击版本行中的「复制为新版本」按钮，系统自动打开新建版本弹窗，并将「复制自版本」字段设置为当前选中的版本。提交后系统将：

1. 创建新版本记录（POST /api/v1/equipment-structure/versions）
2. 调用版本复制接口，从源版本拷贝所有节点数据和设备映射到新版本（POST /api/v1/equipment-structure/versions/{new_id}/copy）

这是修改已发布版本的正确方式：复制为新版本 → 在新版本中编辑 → 发布新版本 → 设为当前。

---

9.5 常见问题

Q：结构版本和工单/点检是什么关系？ A：结构版本定义了设备间的层级关系。组合点检、组合维护等功能基于当前 Active 版本的结构树，选择根设备后自动为所有子设备生成对应工单。修改结构后需要发布并设为当前，新生成的工单才会使用新结构。

Q：已发布的版本为什么不能编辑？ A：这是防止结构变更影响正在执行的点检/维护计划。如需修改，请通过「复制为新版本」创建副本，在副本中编辑后发布。

Q：一个设备可以关联多个结构节点吗？ A：系统当前未对设备与节点的关联做唯一性强制约束，同一设备ID可以关联到多个结构节点。但建议尽量避免此情况以保证结构树的清晰可维护性。如需在同一结构树中多次引用同一设备，请审视业务场景是否合理。

Q：拖拽排序失败怎么办？ A：拖拽使用乐观并发控制，如果提示「版本冲突」，说明有其他用户同时修改了结构。系统会自动刷新节点列表，请重试拖拽操作。

Q：导入 CSV 时应该使用什么格式？ A：导入对话框中有「下载CSV模板」链接，下载模板后按模板格式填写。CSV 包含的列：id（节点ID）、parent_id（父节点ID）、equipment_id（关联设备ID）、name（节点名称）、sort_order（排序号）、attributes_json（扩展属性 JSON 字符串）。导出的 CSV 还额外包含 path 列（节点名称路径，如 产线/主机/电机）。同时支持粘贴 JSON 格式数据。

Q：版本对比可以看到哪些差异？ A：版本对比显示两个版本之间的节点变化（新增/删除/移动/修改）和设备映射变化（新增/移除）。差异摘要以标签形式显示各类变化的数量，并列出前 5 个新增/删除的标识（以设备ID为主键对齐）。

Q：回滚和复制为新版本有什么区别？ A：「复制为新版本」（版本管理页面）创建新版本后，通过 /copy 接口从源版本拷贝节点数据；「回滚」（/rollback 接口）则是一次性操作，创建新版本、拷贝节点数据并自动发布，还可选设为当前。回滚适合需要恢复到历史结构的场景。

Q：结构管理的版本数据存储在哪里？ A：结构版本存储在 equipment_structure_versions 表，节点数据存储在 equipment_structure_nodes 表。每个节点关联一个版本ID，节点间通过 parent_id 建立层级关系。系统还保留下层的 equipment_structures 表以兼容旧数据。

Q：移动端可以使用结构管理吗？ A：移动端不提供结构编辑入口。结构管理是管理员功能，需要在 PC 端操作。但移动端的组合点检/组合维护工单会自动使用当前 Active 版本的结构树。

Q：删除版本会怎样？ A：当前版本管理不提供删除版本功能。不需要的版本可以保留在列表中（草稿状态），不影响系统运行。实际上只有发布的版本会出现在其他模块的版本选择中。

---

9.6 相关权限

结构管理模块涉及的权限列表：

权限	中文名称	说明
equipment:view	查看设备	结构管理菜单入口权限，查看结构版本列表和结构编辑器
equipment:structure:manage	管理设备结构	创建版本、发布/取消发布版本、设为当前版本、添加/编辑/删除节点、拖拽排序、导入
equipment:export	导出设备	导出结构版本节点数据（CSV/JSON），结构导出依赖此权限

角色默认权限分配：

角色	结构管理相关权限
超级管理员	equipment:view、equipment:structure:manage、equipment:export
租户管理员	equipment:view、equipment:structure:manage、equipment:export
设备主管	equipment:view、equipment:structure:manage、equipment:export
技术员	equipment:view（仅查看，不可编辑）
操作员	equipment:view（仅查看，不可编辑）
仓库管理员	equipment:view（仅查看，不可编辑）
只读用户	equipment:view（仅查看，不可编辑）

技术员、操作员、仓库管理员和只读用户拥有 equipment:view 权限，可以进入结构管理菜单查看结构版本和节点树，但无 equipment:structure:manage 和 equipment:export 权限，无法执行新增/编辑/删除/拖拽/导入/导出等操作。