技术实现

Web 管理后台 IoT 功能的关键技术实现方案，涵盖 WebSocket 客户端、ECharts 图表、权限化 UI 渲染和固件上传。作为 02.界面与交互设计 的技术落地文档。

---

1. WebSocket 客户端

1.1 连接管理

• 使用 Socket.IO 客户端（socket.io-client），与后端 @nestjs/websockets 配套
• 连接时机： 用户登录后（有 Token），在 Vue Router 全局守卫或 App.vue 中初始化
• 连接参数： io('wss://host', { auth: { token: 'xxx' }, transports: ['websocket'] })
• 断线重连： Socket.IO 内置重连机制（指数退避），无需手动实现

1.2 消息处理

统一监听器注册到 Pinia store 中：

事件	处理
device.status	更新 deviceStore 中设备的 online 字段 + 设备列表页状态标签实时刷新
device.shadow	更新设备详情页的影子数据展示
ota.progress	更新升级任务详情页的进度条和状态

消息处理在 store actions 中完成，组件通过 computed 自动响应。

---

2. ECharts 图表

2.1 图表组件封装

封装 <iot-chart> 通用组件：

prop	类型	说明
data	Array	时序数据数组
properties	string[]	要展示的属性名列表
timeRange	[string, string]	时间范围

组件内部用 echarts.init() 初始化，watch 监听 props 变化后调用 setOption() 更新图表。

2.2 数据转换

• API 返回的遥测数据格式：[{time, relay_1, temperature}, ...]
• 转换为 ECharts dataset 格式：time 作 x 轴，每个属性一条 series（不同颜色）
• 颜色方案：预设调色板，最多支持 8 条属性曲线

2.3 交互

功能	实现
dataZoom	支持时间范围缩放和拖拽
tooltip	悬浮显示时间 + 数值，多条曲线同时展示
响应式	图表随窗口大小自适应（resize 事件）

---

3. 权限化 UI 渲染

3.1 按钮/操作列显隐

• 使用 v-permission 自定义指令：v-permission="'device:control'" → 无权限时不渲染该元素
• 操作列的显隐规则：

角色	可见操作
admin	全部可见（创建/编辑/删除/控制/升级）
user / operator	仅可见查看类操作（详情/列表），控制按钮置灰 + 提示"无操作权限"

3.2 路由权限

• IoT 页面路由在 meta 中标记所需角色：meta: { roles: ['admin', 'operator'] }
• 路由守卫 beforeEach 检查用户角色是否匹配，不匹配则跳转 403 页面

---

4. 固件上传

4.1 上传组件

• 使用 Element Plus <el-upload> 组件，配置 drag 拖拽上传、accept=".bin" 文件类型限制
• before-upload 钩子校验文件扩展名和大小（最大 4MB），不通过则 Message 提示并阻止上传

4.2 上传流程

选择文件 → 前端校验（扩展名+大小）
  → POST /api/v1/firmware/upload（FormData）
    → 显示进度条（on-progress 回调）
      → 成功：刷新固件列表 + Message 提示
      → 失败：显示后端返回的错误信息

4.3 版本号校验

• 版本号输入框做前端格式校验（/^\d+\.\d+\.\d+$/），不通过时红色提示"格式应为 x.y.z"

---

5. 数据看板技术要点

技术点	实现
时间范围选择	Element Plus <el-date-picker type="datetimerange">
快捷选项	近 1 小时、近 6 小时、近 24 小时、近 7 天、近 30 天
属性多选	<el-checkbox-group>，从物模型属性列表动态生成（GET /api/v1/products/:id/thing-model → 提取 properties 列表）
大数据量	时间范围 > 7 天时前端提示"建议缩小时间范围以获得更好体验"