Doni/3588AdminBackend
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
1ff391f055
3588AdminBackend/docs/superpowers/specs/2026-04-19-device-config-ia-redesign.md

16 KiB
Raw Blame History

设备与配置管理信息架构重设计方案

目标

将 RK3588 后台管理系统重设计为一个清晰、统一、面向多台视觉识别设备的运维控制台。

这次重设计的重点不是在现有页面上继续打补丁，而是彻底解决下面几个问题：

  • 页面入口越来越多，但边界不清楚
  • 同一个信息在多个地方重复出现，内容还不完全一致
  • 用户很难判断“去哪里看状态”“去哪里做操作”“去哪里管理公共配置”
  • 设备管理、配置管理、调试页面混在一起，造成认知负担

新的设计必须保证：同一种信息只有一个权威展示位置，页面职责清楚，用户能快速找到正确入口。

为什么现有 UI 已经不适合继续扩展

当前后台是围绕零散流程和已有接口逐步长出来的，所以会出现这些现象：

  • 同一个概念在多个页面里反复出现，只是叫法略有不同
  • 设备详情、设备操作、配置预览、配置修改互相重叠
  • config-friendly、config-ui、config-preview 三套入口并行存在
  • 一级导航混合了业务对象、页面功能、技术工具和调试能力
  • 用户在使用时很难形成稳定心智，不知道某类信息到底应该去哪一页看

所以这次不是“优化现有导航文案”，而是重新定义整个后台的信息架构。

产品范围

这个后台的本质，是一个统一管理少量视觉识别设备的管理平台。设备规模通常不会超过十几台，因此设计重点应放在清晰、简洁、好判断，而不是面向超大规模设备的高密度监控墙。

当前最重要的职责有四类：

  1. 发现所有设备，并清楚显示每台设备当前状态
  2. 统一管理模板、profile、overlay 等公共配置资产
  3. 管理单台设备的服务与配置操作
  4. 记录操作日志与系统管理行为

设计原则

后续所有页面和交互都必须遵守这几条原则：

  1. 同一个信息只允许有一个权威展示位置
    例如：当前运行配置的完整权威摘要属于“设备详情”，其他页面只能显示简短摘要或跳转。

  2. 查看和操作必须分离
    “这台设备现在怎么样”与“我要对这台设备做什么”不能混在一个页面里。

  3. 一级导航只放业务域，不放动作和技术工具
    导航应该按对象组织，而不是按零散功能组织。

  4. 长技术字段退居二级
    设备名优先，device_id、路径、原始 JSON、内部字段都应降级显示。

  5. 能用图标表达的状态，尽量不用大段文字
    后台首先要支持快速扫视和判断，而不是让用户读说明书。

  6. 每个页面只回答一个核心问题
    比如：

    • 现在发生了什么？
    • 这台设备是什么状态？
    • 我可以做哪些操作？
    • 目前有哪些配置资产？
    • 谁做过哪些变更？

参考方向

整体风格参考 ThingsBoard 这类平台型运维后台，但不是照搬它的功能复杂度。我们借鉴的是它的设计气质和组织方式：

  • 左侧是稳定、克制的主导航
  • 主工作区层次清楚
  • 设备状态展示紧凑、易扫视
  • 查看、管理、审计分开
  • 风格统一、简洁，不做普通 CRUD 表单后台的拼贴感

官方模板参考入口

后续所有 UI 细节实现，除了参考 ThingsBoard 这类整体风格方向，还必须优先参考当前后台实际采用的 Tabler 官方文档与示例页面。

统一参考入口：

这两个页面的作用不同：

  • https://docs.tabler.io/ui
    用来查看官方组件目录、整体视觉语言和页面级组织方式。

  • https://docs.tabler.io/ui/components/cards
    用来查看卡片、标签页卡片、卡片内容分区等具体结构，尤其适合作为详情页、控制页、标签页容器的直接参考。

官方示例优先规则

后续实现 UI 时，必须遵守这条规则：

  1. 先看 Tabler 官方页面的实际效果
  2. 再看官方示例代码结构
  3. 能直接复用官方结构时，不允许先自定义一个“看起来差不多”的版本
  4. 只有官方没有提供合适结构时，才允许做小范围本地样式补充

这条规则尤其适用于下面这些高频区域：

  • tabs / nav-tabs
  • card-tabs
  • card + card-body / card-header
  • 表格工具栏
  • 按钮层级
  • 详情页与控制页的内容容器

例如：

  • 如果要做标签页，就优先参考官方 card-tabs + nav nav-tabs + tab-content + card tab-pane 结构
  • 如果要做卡片分区，就优先参考官方 card / card-header / card-body 结构
  • 如果要做按钮、表单、tab 组合，不应先手写一套近似样式，再去慢慢调整

文档使用约定

以后只要文档里写到“按模板实现”“使用官方组件结构”“参考 Tabler 示例”，默认就是指向上面这两个官方入口。

也就是说，后续如果要继续调整：

  • 设备详情页
  • 设备控制页
  • 配置页
  • 审计页
  • 任务页

都应该先打开官方页面看示例效果和代码，再决定如何落地，而不是只凭组件名称或经验去猜结构。

UI 视觉系统约束

这次重设计不仅要重做信息架构，也要约束 UI 本身的表现方式，避免后续页面继续变成“每页一个风格”。

后续实现必须遵守下面这些视觉约束：

  1. 优先基于统一的后台模板风格来实现
    不允许在不同页面随意发明新的颜色体系、按钮样式、字体层级、卡片风格和状态表现。

  2. 颜色必须克制且有明确语义

    • 中性色用于背景、分隔、普通信息
    • 绿色用于成功 / 在线 / 正常
    • 红色用于失败 / 离线 / 异常
    • 黄色或橙色用于警告 / 风险
    • 主强调色只承担选中、高亮、关键入口，不应泛滥

  3. 字体和字号层级必须固定
    不允许为了“显眼”在局部页面随意放大、缩小或切换字体。标题、正文、说明、技术字段都应使用统一层级。

  4. 组件样式必须统一
    按钮、表格、摘要卡、标签、状态点、抽屉、折叠区、表单输入框都应使用统一规则，不能每页重新设计。

  5. 图标优先表达状态，文字优先表达对象
    状态类信息尽量图标化；对象名、配置名、操作名则保持清楚简洁，不做花哨修饰。

  6. 页面视觉重心必须稳定
    不允许通过随意的高饱和颜色、大块阴影、混乱圆角、过多描边来制造“设计感”。这套后台应是稳定、专业、克制的运维界面。

信息分层与收纳策略

后台默认只展示运维真正需要的重点信息，其他内容应当有明确的收纳方式，避免页面堆满“技术上有用但不是当前最重要”的信息。

信息展示分三层：

第一层：默认可见的核心信息

这是页面一打开就应该看到的信息，只保留支持判断和操作的关键内容。例如：

  • 设备是否在线
  • 服务是否运行
  • 当前运行配置摘要
  • 最近操作是否成功
  • 当前可执行的关键动作

第二层：次要但常用的参考信息

这些信息不是第一眼最重要，但经常需要核对。应通过折叠区、展开面板或局部详情块承载，例如：

  • device_id
  • IP、hostname
  • build_id、git_sha
  • 配置来源中的模板 / profile / overlay 明细
  • 最近一次操作的详细结果

第三层：低频技术信息

这些信息只在排查问题或高级使用时才需要，不能默认大面积展开。应进入抽屉、技术详情区或高级模式，例如：

  • 原始 JSON
  • 完整响应体
  • 原始路径
  • 调试输出
  • 底层接口报错细节

收纳规则

后续所有页面都应遵守以下收纳规则：

  • 默认页面只保留“判断当前状态”和“执行当前动作”需要的信息
  • 次要参考信息优先进入折叠区
  • 低频技术信息优先进入抽屉或高级面板
  • 不能因为“也许有人会看”就把所有信息都铺在主页面上

这条规则非常重要：
页面不是数据库字段的平铺视图，而是运维任务的工作界面。

一级信息架构

整个系统最终只保留四个一级模块：

  1. 设备
  2. 配置资产
  3. 操作审计
  4. 系统

这四个模块正好对应产品的四个核心职责。

1. 设备

作用：回答“有哪些设备、每台设备当前是什么状态、哪台设备需要处理”

包含：

  • 全部设备总览
  • 设备列表
  • 单设备详情
  • 单设备控制

不包含：

  • 模板 / profile / overlay 这类公共配置资产管理
  • 平台级系统设置
  • 全量审计日志主体内容

2. 配置资产

作用：回答“系统里有哪些可复用的配置资产”

包含：

  • 模板
  • 环境参数（Profiles）
  • 覆盖项（Overlays）
  • 配置发布记录

不包含：

  • 设备实时状态
  • 单设备服务控制
  • 当前运行配置的权威展示

3. 操作审计

作用：回答“谁在什么时间对哪台设备做了什么，结果怎样”

包含：

  • 操作历史
  • 操作结果摘要
  • 按时间、设备、操作者、动作类型过滤

4. 系统

作用：回答“后台管理系统自身如何配置和运行”

包含：

  • 设备发现与注册设置
  • agent 认证与访问令牌管理
  • 后台服务健康状态
  • 后台版本信息
  • OpenAPI 与系统级入口

不包含：

  • 日常设备操作
  • 配置资产编辑

首页：设备总览

首页默认进入 设备 模块。

整体采用你确认过的混合结构：上方摘要，下方设备列表。

顶部摘要区

顶部是一排图标化摘要卡，用于快速判断整体状态。建议至少包含：

  • 在线设备数
  • 离线设备数
  • 服务异常设备数
  • 配置不一致设备数
  • 最近操作失败设备数

这里不放解释性长文本，只负责总览和快速筛选。

主设备列表

摘要区下方是主设备列表。由于设备数量不多，不需要做极端高密度表格，应优先保证清晰易读。

每台设备只显示最关键的信息：

  • 设备图标
  • 有意义的设备名
  • 在线状态
  • media-server 状态
  • 当前运行配置摘要
  • 当前软件版本
  • 最后心跳时间
  • 快捷入口

设备身份显示规则

  • 设备名始终是主显示信息
  • device_id 只作为次级技术信息出现
  • 冗长标识不应成为列表主视觉元素
  • 技术字段可放在悬浮提示、次级说明或详情页中

设备域设计

每台设备下只保留两个页面：

  1. 设备详情
  2. 设备控制

这是强约束，不允许再把同类信息拆成多个平行页面。

设备详情

作用：只看，不操作。回答“这台设备现在是什么状态”

应展示：

  • 设备名
  • device_id、hostname、IP
  • 在线 / 离线状态
  • 最后心跳
  • agent 版本、build_id、git_sha
  • media-server 运行状态
  • 当前运行配置权威摘要
  • 最近状态或异常摘要
  • 跳转到设备控制与操作审计

不应展示：

  • 配置预览编辑器
  • 候选配置上传操作
  • 应用 / 回滚按钮
  • 默认展开的原始 JSON 编辑区

设备控制

作用：只做操作。回答“我要对这台设备做什么”

应展示：

  • 配置预览生成
  • 上传候选配置
  • 应用候选配置
  • 回滚到上一份配置
  • 启动 / 停止 / 重启 / 重载服务
  • 当前这次操作的结果摘要

约束：

  • 设备控制页可以显示少量安全上下文，例如当前配置摘要、服务状态
  • 但不能重复完整设备详情页内容

现有配置入口的收敛方式

当前系统中以下几个入口职责重叠：

  • config-friendly
  • config-ui
  • config-preview

在新架构下，这三个不再作为独立产品页面存在，而是统一收进 设备控制，作为同一页面中的不同操作模式，例如：

  • 预览模式
  • 引导编辑模式
  • 高级 JSON 模式

这样设备配置操作就只有一个主入口，不再让用户在多个相似页面之间来回跳。

配置资产域设计

配置资产 用来管理可复用的配置组成部分，而不是管理某台设备当前正在运行什么。

建议拆成四个子区：

  1. 模板
  2. 环境参数
  3. 覆盖项
  4. 发布记录

模板

管理核心配置模板，以及模板用途、适用范围、说明等元数据。

环境参数

管理设备或环境差异参数，例如：

  • 视频源地址
  • 后台地址
  • MinIO 参数
  • token API
  • 站点级或设备级差异项

这类差异不应再靠维护多份完整 JSON 来表达。

覆盖项

管理可重复使用的覆盖项，例如：

  • debug 开关
  • 敏感度调整
  • production quiet
  • 其他运行策略覆盖

发布记录

用于记录某次配置生成或发布的来源和结果。至少应能表达：

  • 来自哪个模板
  • 使用哪个 profile
  • 叠加了哪些 overlays
  • 生成了什么配置标识
  • 应用了哪些设备
  • 应用结果如何

这个区域负责把“配置资产”与“设备应用行为”连接起来，但不承担设备状态页的职责。

操作审计域设计

操作审计 是专门的操作历史页，不应再混杂进其他页面的主体区域。

每条审计记录至少应包含：

  • 操作时间
  • 操作者
  • 目标设备
  • 动作类型
  • 输入摘要
  • 执行结果
  • 执行耗时
  • 失败原因

动作类型至少包括：

  • 上传候选配置
  • 应用候选配置
  • 回滚配置
  • 重载服务
  • 启动服务
  • 停止服务
  • 重启服务
  • 批量操作

操作审计的目标是形成管理闭环，而不是暴露底层 HTTP 调试细节。

系统域设计

系统 只放平台级设置和后台自身状态，保持克制，不要再变成杂物间。

建议包含：

  • 设备发现与注册设置
  • 后台访问 agent 的认证设置
  • 后台服务健康
  • 后台版本 / build 信息
  • OpenAPI 入口

不建议放入：

  • 日常设备控制动作
  • 模板 / profile / overlay 资产管理

页面与路由目标形态

实现后整体结构应逐步收敛为下面这类路由：

  • /ui/devices -> 设备总览
  • /ui/devices/{id} -> 设备详情
  • /ui/devices/{id}/control -> 设备控制
  • /ui/assets/templates
  • /ui/assets/profiles
  • /ui/assets/overlays
  • /ui/assets/releases
  • /ui/audit
  • /ui/system

具体命名可以在实现时微调，但页面边界不应变化。

需要移除或并入的旧页面概念

以下内容不应再继续作为一级页面或独立主入口存在：

  • 识别配置
  • 配置管理
  • 模型管理 作为一级入口
  • 高级调试 作为一级入口
  • 服务健康 作为一级入口
  • OpenAPI 作为一级入口

特别是以下三个配置页面，必须并入设备控制，不再平行存在：

  • config-friendly
  • config-ui
  • config-preview

这次重设计的核心之一，就是用一个清晰的设备控制入口，替代多个“看起来差不多”的配置页。

信息归属规则

为了防止以后再次出现重复页面，后续实现必须遵守下面的信息归属：

  • 全局设备状态摘要属于设备总览
  • 当前运行配置的权威摘要属于设备详情
  • 配置操作属于设备控制
  • 模板 / profile / overlay 属于配置资产
  • 操作历史属于操作审计
  • 平台设置与平台健康属于系统

其他页面如果需要引用这些信息，只能显示摘要或者跳转，不能再次变成完整展示页。

错误状态与空状态

新架构必须能在不理想情况下仍然保持清晰：

  • 离线设备也必须可见，只是状态明显不同
  • 配置 metadata 缺失时，应优雅降级，而不是把页面弄乱
  • 操作失败时，应展示简洁结果，并提供进入审计详情的入口
  • 模板、profile、overlay 为空时，应明确告诉用户当前没有资产，而不是留白

默认主流程中，不应直接把原始 JSON、HTTP 报错或调试信息大面积暴露给用户，除非用户明确进入高级模式。

验证要求

第一阶段实现至少要完成：

go test ./...

同时 UI 层面的验证应覆盖：

  • 导航中只保留批准后的一级模块
  • 设备详情和设备控制已经彻底分离
  • 旧的多个配置入口不再以平级页面形式存在
  • 设备总览以设备名和状态为主，而不是以技术标识为主

非目标

这次重设计不追求以下内容：

  • 面向几百台设备的超大规模监控体验
  • 大量动态动画或实时监控大屏
  • 与设备 / 配置 / 审计 / 系统边界无关的功能扩张
  • 向普通用户暴露更多内部算法和管线参数

这次工作的目标，是把后台做得更清楚、更统一、更容易理解，而不是把它做得更大。