3588AdminBackend/docs/superpowers/specs/2026-04-27-iot-platform-ui-architecture-redesign.md

工业级物联网设备管理平台 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. 最后收口 诊断 域和旧入口兼容

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