# 工业级物联网设备管理平台 UI 架构重构设计

日期：2026-04-27

## 1. 背景

当前后台已经从“程序接口直出”进化到了可用的管理界面，但整体交互仍然存在明显的信息架构问题：

- 一级菜单按“已有页面”拼接，而不是按“用户任务”和“核心对象”组织。
- `设备` 菜单同时承担总览、列表、详情、部分控制入口，职责过重。
- `配置管理` 实际是单设备运维工作台，却被放在一级导航，导致不得不补一个“先选设备”的页面，逻辑牵强。
- `识别配置` 与设备侧配置下发、批量任务之间关系不清晰，用户难以建立稳定心智模型。
- 页面之间存在较多交叉引用和绕行入口，容易让用户迷失在“从哪里来、到哪里去”的问题里。

本次设计目标不是继续修补现有页面，而是参考工业级 IoT / 边缘设备管理平台的常见组织方式，重新确立整套后台的主线、对象边界和导航关系。

## 2. 设计目标

本次重构只解决“多台边缘视觉设备的统一管理和监控”这一核心问题，不追求通用平台化扩张。

目标如下：

1. 一级导航只保留清晰、稳定、低歧义的主对象。
2. 单设备运维从一级导航下沉为设备详情工作台的一部分。
3. `识别配置` 明确为资产库，不再承担单设备入口。
4. `任务` 独立承载批量执行、执行历史和回滚链路。
5. `诊断` 独立承载日志、系统状态和审计。
6. 页面之间避免无意义交叉跳转，导航层级始终可理解。

## 3. 用户心智模型

本系统的核心对象只有五类：

1. **全局态势**：我当前管了多少设备，在线率如何，有没有异常。
2. **设备 fleet**：有哪些设备，它们按什么状态、地点、分组分布。
3. **单台设备**：某一台设备现在是什么状态，运行了什么服务，应用了什么配置。
4. **识别配置资产**：有哪些模板、业务配置、叠加项可供设备使用。
5. **执行与诊断结果**：批量动作做了什么，是否成功，失败在哪，系统是否健康。

因此一级导航应围绕这五类对象展开，而不是围绕“已有接口”或“临时动作入口”展开。

## 4. 新的一级导航

一级导航调整为以下五项：

### 4.1 总览

用途：只看全局运行状态。

包含内容：

- 全局 KPI
- 在线率 / 离线率
- 告警数 / 异常设备数
- 最近任务
- 异常设备列表

明确不包含：

- 完整设备清单
- 单设备配置表单
- 识别配置编辑

### 4.2 设备

用途：设备 fleet 管理主入口。

包含内容：

- 设备列表
- 搜索、筛选、分组
- 批量选择
- 批量操作入口
- 进入单设备详情

点击设备后进入“设备详情工作台”，而不是跳转到零散页面。

### 4.3 识别配置

用途：识别相关资产库。

包含内容：

- 模板
- 业务配置
- 叠加项
- 预览

它是“配置资产”的维护域，不承担单设备入口，也不直接负责设备服务控制。

### 4.4 任务

用途：承载批量动作和执行历史。

包含内容：

- 批量下发
- 批量重启
- 批量回滚
- 执行历史
- 任务详情

任务的意义是“面向一组设备执行动作”，而不是替代设备页本身。

### 4.5 诊断

用途：面向运行排障和平台自检。

包含内容：

- 设备日志
- 系统状态
- 审计记录

它不承担日常设备管理入口，只服务于排障、追踪和系统可观测性。

## 5. 设备详情工作台

单设备相关能力不再作为一级菜单存在，而是统一沉入设备详情。

设备详情采用一个稳定的二级工作台结构，建议拆为以下标签：

1. **概览**
   - 设备身份信息
   - 在线状态
   - 管理地址
   - 当前版本
   - 最近心跳
   - 当前应用的识别配置摘要

2. **运行与服务**
   - 服务状态
   - 启动 / 停止 / 重启操作
   - 运行时摘要

3. **设备配置**
   - 设备本地配置查看
   - 配置修改入口
   - 配置上传 / 应用
   - 配置回滚

4. **模型与资源**
   - 模型上传
   - 模型版本
   - 人脸库 / 资源摘要

5. **日志与指标**
   - 诊断日志
   - 运行指标
   - 进入高级调试

这个页面的目标是：用户在“设备”域内进入某台设备后，不需要再借道其他一级菜单才能完成单设备运维。

## 6. 模块边界与跳转原则

### 6.1 允许的跳转

- `总览 -> 设备详情`
- `总览 -> 任务详情`
- `总览 -> 诊断`
- `设备 -> 设备详情`
- `设备 -> 批量任务创建`
- `识别配置 -> 预览`
- `识别配置 -> 任务（以某资产为基础创建下发任务）`
- `任务 -> 任务详情`
- `任务详情 -> 相关设备`
- `诊断 -> 相关设备日志 / 审计详情`

### 6.2 不允许的跳转

- 在设备详情里放“进入配置管理”这类跨一级菜单暗示按钮。
- 在 `识别配置` 中塞入单设备配置管理入口。
- 在 `诊断` 中承担日常设备运维动作。
- 在一级菜单之间互相做“兜底式导航”，例如通过一个页面去弥补另一个页面职责不清的问题。

原则是：页面只完成自己领域内的事情，跳转只发生在真实的上下游关系之间。

## 7. 关键主流程

### 7.1 查看单设备状态

`总览 / 设备列表 -> 点击设备 -> 设备详情 -> 概览 / 运行与服务 / 日志与指标`

### 7.2 修改单设备配置

`设备列表 -> 点击设备 -> 设备详情 -> 设备配置 -> 查看 / 修改 / 上传 / 回滚`

### 7.3 批量下发识别配置

`识别配置 -> 选择模板或业务配置 -> 发起下发 -> 任务页确认目标设备 -> 创建任务 -> 任务详情查看结果`

也允许从 `设备` 列表中批量选中设备后发起动作，但最终都应落到 `任务` 域中查看执行结果。

### 7.4 诊断异常设备

`总览异常设备 / 设备列表异常筛选 -> 设备详情 -> 日志与指标`

若需要平台级排查，则进入 `诊断` 域查看系统状态与审计记录。

## 8. 对现有页面的重组建议

### 8.1 保留并重定位

- `dashboard`：保留，但弱化设备列表内容，强化 KPI / 告警 / 最近任务 / 异常设备。
- `devices`：保留，作为设备 fleet 主页。
- `device`：升级为设备详情工作台主页面。
- `asset_templates / asset_profiles / asset_overlays`：保留并继续作为资产库内部页面。
- `tasks / task`：保留并前置为一级模块。
- `system / audit / logs / diagnostics`：整合进 `诊断` 域。

### 8.2 下沉或移除

- `device-config`：不再作为一级模块；其能力并入设备详情的“设备配置”标签。
- `device_control`：改造成设备详情工作台的一个子区，而不是独立导航页。
- `recognition`：若只是旧入口，应并入 `识别配置` 资产域。
- `api`：保留为高级调试页，但收纳于 `诊断` 域，不参与主业务导航。

### 8.3 过渡期兼容

为避免立即打断现有链接，旧 URL 可以先保留，但应全部做以下处理之一：

- 301 / 302 到新位置
- 继续可访问，但使用新的页面骨架和导航文案

要求用户在视觉上始终感知到自己位于新的信息架构中。

## 9. 视觉与布局原则

这次不是单纯换皮，但布局要服务于新结构。

原则如下：

- 一级菜单名称简短、稳定、无歧义。
- 每个页面首屏只解决一个主要问题。
- 同一页面内优先使用“列表 + 详情工作区”或“列表 + 编辑区”的结构。
- 避免全页大表格里塞满按钮和表单。
- 批量动作先选对象，再确认动作，再进入任务结果；不要在列表页直接堆所有操作。
- 单设备详情应呈现为工作台，而不是一组相互无关的卡片。

## 10. 测试与验收

本次重构至少需要以下验证：

1. 一级导航只出现：`总览 / 设备 / 识别配置 / 任务 / 诊断`
2. 不再存在一级菜单 `配置管理`
3. 从 `设备` 进入单设备后，可在设备详情内完成单设备查看与配置相关操作
4. `识别配置` 不出现单设备管理入口
5. `任务` 成为批量动作和历史的唯一主域
6. `诊断` 页面覆盖日志、系统状态、审计三类入口
7. 旧链接访问时不会把用户带回旧的信息架构

建议在 `internal/web/ui_test.go` 中补充信息架构级测试，而不只是页面文案测试。

## 11. 本次实施范围

本轮实施仅处理 UI 信息架构和页面职责重组，不新增后端业务能力。

具体包括：

- 一级导航重组
- 现有页面合并、迁移、重命名
- 设备详情升级为单设备工作台
- 任务和诊断域的导航与入口整理
- 旧入口兼容跳转
- 相关测试更新

明确不包括：

- 新的设备分组后端能力
- 新的告警引擎
- 新的权限系统
- 新的 API 设计

## 12. 推荐实施顺序

1. 先重组一级导航和路由映射
2. 再把单设备配置与服务控制并入设备详情工作台
3. 再独立整理 `任务` 域
4. 最后收口 `诊断` 域和旧入口兼容

这样可以在保持现有功能可用的前提下，逐步把用户心智迁移到新的主结构。