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

## 目标

将 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 官方文档与示例页面。

统一参考入口：

- Tabler UI 官方文档首页：  
  <https://docs.tabler.io/ui>

- Tabler Cards 组件文档：  
  <https://docs.tabler.io/ui/components/cards>

这两个页面的作用不同：

- `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 报错或调试信息大面积暴露给用户，除非用户明确进入高级模式。

## 验证要求

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

```bash
go test ./...
```

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

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

## 非目标

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

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

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