界面与交互设计
Web 管理后台 IoT 业务页面的界面与交互设计文档。需求定义见功能需求（第 7 节 WEB-001~WEB-009），API 接口见 API 接口规范（产品、设备、固件接口组）。
1. 导航结构
侧边栏
在现有系统管理菜单组下方新增 IoT 管理 菜单组：
IoT 管理
├── Dashboard
├── 产品管理
│ ├── 产品列表
│ └── 物模型编辑（隐藏路由）
├── 设备管理
│ ├── 设备列表
│ └── 设备详情 /:id（隐藏路由）
├── 数据看板
└── 固件升级
├── 版本管理
└── 升级任务 / 任务详情 /:id（隐藏路由）2. 页面设计
2.1 Dashboard IoT 概览
定位： 在现有 Dashboard 基础上新增 IoT 概览数据卡片。
┌──────────────────────────────────────────────────────┐
│ Dashboard │
├──────────┬──────────┬──────────┬────────────────────┤
│ 📱设备总数│ 🟢在线设备│ 🔔今日告警│ 📦活跃产品 │
│ 1,234 │ 1,156 │ 12 │ 8 │
│ ↑12% │ 93.6% │ ↓3 │ │
├──────────┴──────────┴──────────┴────────────────────┤
│ 最近告警 设备在线率趋势 (近7天) │
│ ┌────────────────────┐ ┌──────────────────────┐ │
│ │时间 │类型 │设备 │ │ 100% ┤ ╱╲ │ │
│ │10:30 │过温 │客厅 │ │ 90% ┤ ╲ ╱╲ ╱ ╲│ │
│ │09:15 │离线 │卧室 │ │ 80% ┤ ╲╱ ╲╱ │ │
│ │08:00 │过流 │车间 │ │ └──┬──┬──┬──┬──│ │
│ └────────────────────┘ │ 一 二 三 四 五 六 日│ │
│ └──────────────────────┘ │
└──────────────────────────────────────────────────────┘新增卡片行（4 个统计卡片）：
| 卡片 | 内容 |
|---|---|
| 设备总数 | 大号数字 + 环比变化百分比（绿色↑/红色↓） |
| 在线设备数 | 在线数量 + 在线率百分比 |
| 今日告警数 | 告警数量 + 较昨日变化 |
| 活跃产品数 | 有在线设备的产品数量 |
卡片下方（左右两栏）：
| 区域 | 内容 |
|---|---|
| 左侧（60%） | 最近 5 条告警列表（表格），点击跳转告警详情 |
| 右侧（40%） | 设备在线率趋势（小型 ECharts 折线图，近 7 天） |
2.2 产品列表
定位： 管理产品定义和物模型。
┌──────────────────────────────────────────────────────┐
│ 产品管理 │
├──────────────────────────────────────────────────────┤
│ [🔍 搜索产品...] [分类 ▼] [+ 创建产品] │
├──────────────────────────────────────────────────────┤
│ │ ID │ 名称 │ 设备数 │ 版本 │ 时间 │ 操作│
│ │ p_relay │ 四路继电器│ 520 │ v1.0 │ 05-12│ ✏🗑│
│ │ p_switch │ 智能开关 │ 310 │ v1.0 │ 05-10│ ✏🗑│
│ │ p_sensor │ 温湿度传感器│ 189 │ v1.0 │ 05-08│ ✏🗑│
│ │ p_plug │ 智能插座 │ 45 │ v1.0 │ 05-05│ ✏🗑│
│ [◀ 1 2 3 ... 5 ▶] │
└──────────────────────────────────────────────────────┘| 区域 | 内容 |
|---|---|
| 顶部操作栏 | 搜索框（按产品 ID/名称） + 产品分类下拉筛选 + "创建产品"按钮 |
| 主体 | 产品表格（列：产品 ID / 名称 / 设备数 / 物模型版本 / 创建时间 / 操作） |
| 分页 | 底部分页器，默认 20 条/页 |
操作列：
| 操作 | 说明 |
|---|---|
| 编辑 | 弹窗编辑产品名称、描述、分类 |
| 物模型 | 跳转物模型编辑页 |
| 删除 | Popconfirm "删除后设备将无法注册，确认删除？" |
物模型编辑页： 左侧属性/事件/服务 Tab 切换，右侧 Monaco Editor JSON 编辑器，底部"保存"+"版本历史"按钮。
状态变化：
| 状态 | 表现 |
|---|---|
| 加载中 | 表格 skeleton 占位 |
| 空状态 | "暂无产品，点击创建" |
| 保存成功 | Toast 提示 + 刷新列表 |
2.3 设备列表
定位： 查看和管理所有设备。
┌──────────────────────────────────────────────────────┐
│ 设备管理 │
├──────────────────────────────────────────────────────┤
│ [🔍 搜索设备...] [产品 ▼] [状态 ▼] [+ 注册设备] │
│ [☐ 批量删除] [☐ 批量升级] │
├──────────────────────────────────────────────────────┤
│ │☐│ 名称 │ 产品 │ 物理ID │状态│版本 │时间│操作│
│ │☐│客厅继电器│四路继电器│A1:B2:C3│🟢在线│v1.0│10:30│📋🎮🗑│
│ │☐│卧室开关 │智能开关 │D4:E5:F6│🟢在线│v1.0│10:28│📋🎮🗑│
│ │☐│车间传感器│温湿度传感器│G7:H8:I9│⚫离线│v1.0│09:15│📋🎮🗑│
│ │☐│办公室插座│智能插座 │J0:K1:L2│🟢在线│v1.0│08:00│📋🎮🗑│
│ [◀ 1 2 3 ... 10 ▶] │
└──────────────────────────────────────────────────────┘| 区域 | 内容 |
|---|---|
| 顶部筛选栏 | 搜索框（设备名称/ID） + 产品下拉 + 在线状态下拉（全部/在线/离线） + "注册设备"按钮 |
| 主体 | 设备表格 + 顶部分页器 |
| 批量操作 | 勾选多行后显示批量操作栏（批量删除/批量升级） |
表格列：
| 列 | 说明 |
|---|---|
| 复选框 | 批量选择 |
| 设备名称 | 可点击跳转详情 |
| 产品 | 设备所属产品名称 |
| 物理 ID | MAC 地址（灰色小字） |
| 在线状态 | 绿色圆点 + "在线" / 灰色圆点 + "离线" |
| 固件版本 | 当前版本号 |
| 最近上线时间 | 时间戳 |
| 操作 | 详情、控制、删除 |
WebSocket 实时更新： 在线状态列收到 device.status 推送后自动更新，不刷新整页。
状态变化：
| 状态 | 表现 |
|---|---|
| 加载中 | 表格 skeleton |
| 空状态 | "暂无设备" |
| 搜索无结果 | "未找到匹配的设备" |
2.4 设备详情
定位： 查看设备影子和控制设备。
控制面板 Tab：
┌──────────────────────────────────────────────────────┐
│ ← 设备详情 │
├──────────────────────────────────────────────────────┤
│ 客厅继电器 │ 产品: 四路继电器 │ 🟢 在线 │
│ ID: d1a2.. │ 物理ID: A1:B2:C3 │ 固件: v1.0.0 │
├──────────────────────────────────────────────────────┤
│ [设备影子] [控制面板] [设备日志] │
├──────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 继电器 1 │ │ 继电器 2 │ │
│ │ ╭──────╮ │ │ ╭──────╮ │ │
│ │ │ ON │ │ │ │ OFF │ │ │
│ │ ╰──────╯ │ │ ╰──────╯ │ │
│ └─────────────────┘ └─────────────────┘ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 继电器 3 │ │ 继电器 4 │ │
│ │ ╭──────╮ │ │ ╭──────╮ │ │
│ │ │ OFF │ │ │ │ ON │ │ │
│ │ ╰──────╯ │ │ ╰──────╯ │ │
│ └─────────────────┘ └─────────────────┘ │
│ ┌─────────────────────────────┐ │
│ │ 芯片温度: 45.2 °C │ │
│ └─────────────────────────────┘ │
└──────────────────────────────────────────────────────┘| 区域 | 内容 |
|---|---|
| 顶部卡片 | 设备名称 + 产品 + 物理 ID + 在线状态标签 + 固件版本 + 最近上线时间 |
| 主体 | Tab 切换：设备影子 / 控制面板 / 设备日志 |
设备影子 Tab：
- JSON 编辑器只读展示当前影子数据（desired + reported）
- 右上角刷新按钮手动更新
- 底部显示"最后更新时间"
控制面板 Tab：
- 根据物模型
ui.component渲染控制组件（与小程序 2.2 节映射规则相同） - 指令下发后按钮显示 loading，收到 set_reply 后更新状态
- 超时 5 秒 Toast 提示"指令超时"
- 设备离线时所有控制组件置灰
设备日志 Tab：
- 时间轴列表，最新 50 条
- 每条显示：时间 / 事件类型标签（online=绿, offline=灰, report=蓝, control=橙, ota=紫） / 内容摘要
- 顶部事件类型筛选下拉
2.5 数据看板
定位： 查看设备遥测数据的时序曲线。
┌──────────────────────────────────────────────────────┐
│ 数据看板 │
├──────────────────────────────────────────────────────┤
│ 时间范围: [近1h] [近6h] [近24h] [近7d] [近30d] 自定义│
│ ┌─ 2026-05-20 ─── 至 ─── 2026-05-27 ─┐ [导出CSV] │
├──────────┬───────────────────────────────────────────┤
│ ☑ 温度 │ 温度/°C 湿度/% │
│ ☑ 湿度 │ 30 ┤ ╱╲ ╱╲ │
│ ☐ 继电器1│ 25 ┤ ╱ ╲ ╱╲ ╱ ╲ 80 ┤ ╲ ╱╲ │
│ ☐ 继电器2│ 20 ┤╱ ╲╱ ╲╱ ╲ 60 ┤ ╲╱ ╲╱ │
│ ☐ 继电器3│ └───────────────── └────────────── │
│ ☐ 继电器4│ 时间 → 时间 → │
│ │ ← 可拖拽缩放 → │
└──────────┴───────────────────────────────────────────┘| 区域 | 内容 |
|---|---|
| 顶部 | 时间范围选择器（日期时间区间 + 快捷选择：近 1h / 6h / 24h / 7d / 30d） |
| 左侧面板（15%） | 属性选择（Checkbox 多选，从物模型属性列表加载） |
| 主体（85%） | ECharts 时序曲线图（多属性叠加，不同颜色） |
| 右上角 | "导出 CSV"按钮 |
交互：
- 切换时间范围或属性 → 图表 loading 蒙层 → 重新加载
- 图表支持缩放（dataZoom）和拖拽平移
- 鼠标悬浮显示数据点详情气泡（时间 + 数值 + 单位）
- 导出：点击"导出 CSV"→ 弹窗确认导出范围 → 下载
- 加载失败：图表区域显示"加载失败，点击重试"
2.6 固件版本管理
定位： 管理产品固件版本。
┌──────────────────────────────────────────────────────┐
│ 固件版本管理 │
├──────────────────────────────────────────────────────┤
│ [产品 ▼] [+ 上传固件] │
├──────────────────────────────────────────────────────┤
│ │ 产品 │ 版本 │ 大小 │ MD5 │ 时间 │操作│
│ │四路继电器│ 1.1.0 │ 1.2MB │ a1b2.. │05-27│ 🗑 │
│ │四路继电器│ 1.0.0 │ 1.1MB │ c3d4.. │05-12│ 🗑 │
│ │智能开关 │ 1.0.1 │ 0.9MB │ e5f6.. │05-10│ 🗑 │
│ [◀ 1 2 3 ▶] │
└──────────────────────────────────────────────────────┘| 区域 | 内容 |
|---|---|
| 顶部 | 产品筛选下拉 + "上传固件"按钮 |
| 主体 | 固件版本表格（列：产品 / 版本号 / 文件大小 / MD5 / 上传时间 / 操作） |
上传固件弹窗：
| 字段 | 说明 |
|---|---|
| 选择产品 | 下拉选择 |
| 版本号 | 输入框，格式校验（如 1.0.0） |
| 更新日志 | textarea |
| 固件文件 | 拖拽上传区域 + 文件选择，仅支持 .bin |
| 进度条 | 上传进度 |
操作列： 删除（Popconfirm，检查是否有进行中的关联升级任务）。
状态变化：
| 状态 | 表现 |
|---|---|
| 空状态 | "暂无固件版本，点击上传" |
| 上传中 | 弹窗显示进度条，不可关闭 |
| 版本号重复 | 红色提示"A0302：固件版本已存在" |
2.7 升级任务
定位： 管理 OTA 固件升级任务。
┌──────────────────────────────────────────────────────┐
│ 升级任务 │
├──────────────────────────────────────────────────────┤
│ [+ 创建升级任务] │
├──────────────────────────────────────────────────────┤
│ │ 任务ID │ 目标固件 │ 总数│成│败│中│状态 │时间│操作│
│ │ ota_001│ v1.1.0 │ 100│85│3 │12│🟡进行│05-27│ 📋│
│ │ ota_002│ v1.0.1 │ 50│50│0 │0 │🟢完成│05-25│ 📋│
│ │ ota_003│ v1.1.0 │ 30│20│10│0 │🔴失败│05-20│ 📋│
│ [◀ 1 2 3 ▶] │
└──────────────────────────────────────────────────────┘任务列表页：
| 区域 | 内容 |
|---|---|
| 顶部 | "创建升级任务"按钮 |
| 主体 | 任务表格（列：任务 ID / 目标固件 / 总设备 / 成功 / 失败 / 进行中 / 状态 / 创建时间 / 操作） |
状态标签颜色： 进行中（蓝色）、已完成（绿色）、失败（红色）、已取消（灰色）
创建任务弹窗：
- 选择固件版本（下拉，列出所有产品固件）
- 选择目标设备：按产品全量 / 手动勾选设备（表格 + 搜索 + 分页）
- 确认创建 → 创建后自动跳转任务详情
┌──────────────────────────────────────────────────────┐
│ ← 任务详情: ota_001 │
├──────────────────────────────────────────────────────┤
│ 目标固件: v1.1.0 │ 总设备: 100 │
│ ████████████░░░ 85% │ 🟢成功:85 🔴失败:3 🟡进行:12 │
├──────────────────────────────────────────────────────┤
│ │ 设备 │ 当前版本│ 目标版本│ 进度 │ 状态│耗时 │
│ │客厅继电器 │ v1.0.0 │ v1.1.0 │███░85%│下载中│30s │
│ │卧室开关 │ v1.0.0 │ v1.1.0 │█████100%│安装中│45s│
│ │车间传感器 │ v1.0.0 │ v1.1.0 │█████████│✅成功│52s│
│ │办公室插座 │ v1.0.0 │ v1.1.0 │░░░ 0% │⏳等待│ - │
│ │厨房开关 │ v1.0.0 │ v1.1.0 │██░░ 30%│❌失败│18s│
│ [◀ 1 2 3 ... 20 ▶] │
└──────────────────────────────────────────────────────┘任务详情页：
| 区域 | 内容 |
|---|---|
| 顶部概览 | 总设备数 / 成功 / 失败 / 进行中 / 等待中 + 进度条百分比 |
| 主体 | 设备列表（每台设备：名称 / 当前版本 / 目标版本 / 状态标签 / 进度条 / 耗时） |
WebSocket 实时更新：收到 otaTask.progress 推送后更新对应设备的进度条和状态。
3. 全局交互规范
| 规范 | 说明 |
|---|---|
| 表格 | 所有表格支持分页（默认 20 条/页）、排序（点击列头）、列宽拖拽 |
| 弹窗表单 | 统一 Modal + Form，提交按钮 loading 防重复，校验失败红字提示 |
| 删除操作 | 全部使用 Popconfirm 二次确认，文案说明删除影响 |
| 实时更新 | 设备列表在线状态、升级任务进度通过 WebSocket 推送 |
| 权限控制 | admin 角色可见所有操作按钮，普通用户仅可查看（按钮置灰或隐藏） |
| 响应式 | 侧边栏可折叠，表格区域自适应宽度 |