导航与界面布局
EcoCtrl 提供两个前端入口——Admin 管理后台和 Web 3D 驾驶舱——它们的导航逻辑和页面布局各有不同。本文将系统性地介绍这两个入口的界面结构，帮助你快速找到所需功能。
Admin 导航架构
Admin 管理后台采用 左侧可折叠侧边栏 + 内容区 的两栏布局。侧边栏是主要的导航工具，所有顶级功能模块都在这里以 Tab 形式列出。
侧边栏布局
侧边栏有两种状态：
| 状态 | 宽度 | 说明 |
|---|---|---|
| 展开 | 240px | 显示图标 + 文字标签，适合大屏幕操作 |
| 折叠 | 64px | 仅显示图标，鼠标悬停时弹出文字提示（Tooltip） |
侧边栏底部有一个折叠/展开切换按钮：
- 展开状态下，按钮显示为向左箭头（
ChevronLeft），点击后折叠。 - 折叠状态下，按钮显示为向右箭头（
ChevronRight），悬停在底部区域时浮现，点击后展开。也可直接点击顶部品牌区域展开。
侧边栏折叠状态会自动保存，刷新页面后保持之前的折叠/展开设置。
顶级导航 Tab
侧边栏共列出 11 个顶级 Tab，按功能领域组织如下（列出顺序即侧边栏显示顺序）：
| Tab | 图标 | 说明 |
|---|---|---|
| 管理总览 | LayoutDashboard | 平台核心仪表盘，展示关键指标和实时状态 |
| 账户控制 | Users | 用户管理、角色权限、OAuth 绑定配置 |
| 数据模型 | Server | 管理数据模型（Schema）、业务对象和点位信息 |
| 大屏模型 | Box | 配置 3D 大屏的热点区域和标签（全屏沉浸模式） |
| 逻辑控制 | Workflow | 可视化工作流编辑器与执行记录 |
| 报表管理 | FileBox | 报表模板、生成与导出管理 |
| 维保管理 | Wrench | 设备维保计划、工单与历史记录 |
| 故障管理 | AlertTriangle | 实时故障列表与故障统计分析 |
| 能耗管理 | Zap | 分区能耗概览、详细数据、统计报表与碳排放因子配置 |
| 高级管理 | Shield | 高级平台管理功能 |
| 系统配置 | Settings | 系统全局设置入口，内部包含个人信息与偏好设置子页面 |
当前 Tab 高亮
侧边栏中当前激活的 Tab 会有明显的视觉区分：
- 左侧显示一条彩色竖条指示线。
- 背景和文字颜色变化（半透明主色背景加主色文字）。
- 图标略微放大，线条加粗。
- 切换 Tab 时，指示线会以平滑动画过渡到新的位置。
状态持久化
当前激活的 Tab 通过全局状态管理（Zustand）持久化到浏览器的 localStorage，刷新页面或关闭浏览器后重新打开，都会停留在上次访问的 Tab 上，无需重新定位。
页面内子 Tab 切换
部分功能模块内部包含多个子页面。Admin 后台通过 子 Tab 栏 实现页面内的切换，子 Tab 栏位于页面顶部、面包屑/标题的右侧。
子 Tab 示例
| 父模块 | 子 Tab |
|---|---|
| 能耗管理 | 分区总览 / 详细数据 / 统计报表 / 碳排放因子 |
| 逻辑控制 | 工作流 / 执行记录 |
| 故障管理 | 实时故障列表 / 故障统计分析 |
| 数据模型 | 数据模型 / 业务对象 / 点位信息 |
| 大屏模型 | 热点区域配置 / 标签配置 |
子 Tab 的持久化
每个模块的子 Tab 状态独立存储、互不干扰。切换模块后，子 Tab 的选择会被记住，再次回到该模块时，会自动定位到最后一次查看的子页面。例如：
- 在「能耗管理」中切换到「详细数据」子页。
- 切换到「故障管理」查看故障列表。
- 点击「能耗管理」返回，页面直接显示「详细数据」而不是默认的「分区总览」。
这种持久化同样通过 Zustand 存储到 localStorage，刷新或关闭浏览器后仍然保持。
界面布局特性
面包屑导航
页面顶部的面包屑组件显示当前所在的位置层级。以「个人信息」页面为例：
首页 / 系统配置 / 个人信息面包屑的特性：
- 每个分段（除「首页」外）如果存在同级页面，会显示为下拉菜单，点击可快速跳转到同级页面。
- 左侧扁平布局（手机等小屏幕）时，面包屑隐藏，改用页面标题展示。
- 面包屑的显示/隐藏可以在「偏好设置」中切换。
页面头部
每个功能页面的头部区域包含：
- 左侧：面包屑导航（大屏幕）或当前页面标题（小屏幕）。
- 中侧：子 Tab 切换栏（如该模块有子页面）。
- 右侧：全局搜索、主题切换（浅色/深色/跟随系统）、通知铃铛、用户头像与下拉菜单。
用户头像下拉菜单提供三个入口：
- 个人信息：修改头像、用户名、邮箱等资料。
- 偏好设置：调整主题、布局密度、字体大小、通知方式等。
- 退出登录：清除当前会话。
全屏沉浸式页面
以下三个页面采用 全屏沉浸式布局，进入后会隐藏侧边栏和页面头部，独占整个浏览器视口，以获得最大的操作空间：
| 页面 | 入口位置 | 说明 |
|---|---|---|
| 大屏模型 | 侧边栏「大屏模型」Tab | 全屏配置 3D 热点区域和标签，预览大屏效果 |
| 工作流画布 | 逻辑控制 > 工作流详情 | 可视化 DAG 工作流编辑器的全屏操作界面 |
| 日志查看器 | 逻辑控制 > 执行记录 > 详情 | 全屏查看工作流执行日志，支持日志流式滚动 |
在沉浸式页面的右上角通常有「退出全屏」或「返回」按钮，点击后恢复侧边栏和头部。
系统配置嵌套页面
「系统配置」不包含子 Tab，而是在其下以 独立页面 的方式管理两个子页面：
- 个人信息（
/profile）：修改用户头像、用户名、邮箱等账户资料。 - 偏好设置（
/preferences）：调整界面主题（浅色/深色/跟随系统）、布局密度（舒适/紧凑）、字体大小、桌面通知、告警音效、邮箱通知、侧边栏默认折叠状态、面包屑显示开关。
这两个页面不出现在侧边栏中，而是通过用户头像下拉菜单或系统配置内的链接跳转到达。
内容区布局分类
Admin 后台的内容区根据页面类型有两种布局方式：
| 布局模式 | 适用的页面 | 说明 |
|---|---|---|
| 居中定宽 | 管理总览、账户控制、报表管理、维保管理 | 内容在 1440px 最大宽度内居中显示，两侧留白，适合阅读型页面 |
| 全宽流动 | 系统配置、偏好设置、个人信息、逻辑控制、数据模型、故障管理、能耗管理、高级管理 | 内容区域填满屏幕宽度，适合数据密集和操作密集型页面 |
Web 3D 驾驶舱界面
Web 门户（/）以 3D 建筑场景为核心，提供沉浸式的可视化体验，界面构成与 Admin 后台有较大差异。
整体页面结构
Web 驾驶舱是一个 单页面应用，页面由三个视觉层级叠加构成：
- 全屏背景层：Babylon.js 3D 建筑场景，占据整个视口
- 覆盖层：Bento Grid 仪表盘组件（统计卡片、图表、列表等），悬浮在 3D 场景之上
- 浮动控件：导航栏（顶部 SSE 状态 + 时间）、相机控制按钮（右下侧浮动）、区域标签（3D 场景中悬浮）
顶部导航栏
导航栏固定在页面顶部（高度 56px），包含三个区域：
左侧：Logo 按钮。包含 EcoCtrl 品牌图标和文字，点击后跳转到 /settings 设置页。
中央：状态胶囊。显示以下信息：
- SSE 连接状态指示器：一个彩色圆点，绿色（已连接）/ 琥珀色（重连中）/ 红色（已断开），旁边显示实时的连接状态。
- 场地标识文字（如 "ECCTRL LOCATION"）及 "MONITORING" 标签。
右侧：当前时间。24 小时制时间显示，下方配日期，每秒自动更新。
3D 场景与浮动相机控制
3D 建筑场景以全屏背景方式渲染（Babylon.js 引擎），覆盖整个浏览器视口。
场景上方浮动一组相机控制按钮，位于页面右下侧，纵向排列：
- 全屏切换（最大化/最小化图标）：进入或退出沉浸式全屏模式。
- 放大（
+）：推近相机，拉近视角。 - 缩小（
-）：拉远相机，扩大视野。 - 复位：将相机恢复到默认位置和角度，同时清除选中的热点标签、退出全屏模式。
点击 3D 场景中的热点标签时，相机自动聚焦到该区域，左侧弹出 照明控制面板（宽度 320px），用于调整该区域的照明组状态。此时仪表盘组件自动淡出，相机控制按钮隐藏。
Bento Grid 仪表盘覆盖层
3D 场景之上覆盖有一层 Bento Grid 布局的仪表盘，以 16 列 x 8 行的 CSS 网格排列。每个网格单元放置一个数据可视化组件（能耗趋势图、设备状态、告警列表等）。
查看模式：组件按预设位置排列，鼠标悬停可查看详情。
编辑模式：点击页面底部的编辑工具栏可进入布局编辑：
- 每个组件左上角出现拖拽手柄，可以自由拖动到其他位置。
- 组件右下角可调整尺寸（宽度/高度）。
- 点击组件上的眼睛图标可隐藏该组件，隐藏后的组件在编辑模式下显示为占位符。
- 将组件拖到其他组件上方可交换二者位置。
- 编辑完成后点击「完成」保存布局，或点击「取消」回退到之前的状态。
布局编辑支持自动保存到后端，每次修改会以去抖方式同步到服务端。
设置页
点击顶部导航栏的 Logo 或使用底部导航 Pill 中的「设置」按钮，可进入全屏设置页面（/settings），覆盖在 3D 场景之上。
设置页左侧是导航选项卡，右侧是滚动内容区，使用 Scroll Spy 技术自动高亮当前浏览的章节：
| 选项卡 | 配置项 |
|---|---|
| General | 语言、减少动效、加载动画开关、Screen Pet 主题、语音配置 |
| Appearance | 自动旋转、热点标签显示、辉光效果、环境预设、相机设置 |
| Layout | Bento Grid 编辑入口、编辑超时自动退出延迟 |
| Data | 数据刷新间隔、导航隐藏延迟、同步去抖间隔 |
| Account | 登录/注销、用户信息展示 |
设置页右上角有「保存」和「重置」按钮，修改内容以去抖方式自动同步到服务端。
浮动 AI 助手
Screen Pet 是一个可拖拽的浮动角色，在所有页面或场景中都可见。点击它可以展开对话气泡，通过自然语言与平台 AI 交互，查询能耗数据、设备状态或执行简单的控制操作。
常见问题
问：侧边栏折叠后找不到某个功能？
鼠标悬停到对应的图标上，会弹出文字提示显示功能名称。如果仍不确定，可以点击底部的展开按钮将侧边栏恢复为完整显示。
问：子 Tab 的位置为什么会记住？
子 Tab 的选择会自动保存到浏览器本地存储。这是为了方便多模块之间的频繁切换，不需要每次进入模块后重新选择子页面。如需重置，清除浏览器站点数据即可。
问：为什么大屏模型页面没有侧边栏？
大屏模型、工作流画布和日志查看器是全屏沉浸式页面，为了最大化操作空间会自动隐藏侧边栏和顶部导航。使用页面内的返回按钮即可退出沉浸模式。
问：Web 驾驶舱可以匿名访问吗？
可以。Web 3D 驾驶舱支持匿名访问，公开仪表盘无需登录即可查看。如需使用更多功能或查看详细数据，可在设置页登录账户。
问：Bento Grid 布局能恢复默认吗？
可以。在编辑模式下点击「重置」按钮，即可将布局恢复到系统默认配置。
问：Web 驾驶舱的 SSE 连接断开怎么办？
当 SSE 连接断开时，顶部导航栏的状态指示器会变为红色。系统会自动尝试重连，状态指示器会变为琥珀色（重连中）。连接恢复后自动转为绿色。如长时间无法连接，请检查网络或联系管理员确认服务端状态。