diff --git a/docs/superpowers/specs/2026-04-19-device-config-ia-redesign.md b/docs/superpowers/specs/2026-04-19-device-config-ia-redesign.md index 542e6b6..04d14f6 100644 --- a/docs/superpowers/specs/2026-04-19-device-config-ia-redesign.md +++ b/docs/superpowers/specs/2026-04-19-device-config-ia-redesign.md @@ -1,328 +1,357 @@ -# Device And Config Information Architecture Redesign +# 设备与配置管理信息架构重设计方案 -## Goal +## 目标 -Redesign the RK3588 admin backend as a clear multi-device operations console for visual-recognition devices. The redesign must stop the current page sprawl, remove repeated information, and establish one authoritative place for each important piece of device and configuration state. +将 RK3588 后台管理系统重设计为一个清晰、统一、面向多台视觉识别设备的运维控制台。 -## Why The Current UI No Longer Fits +这次重设计的重点不是在现有页面上继续打补丁,而是彻底解决下面几个问题: -The current UI grew around individual workflows and API surfaces. As a result: +- 页面入口越来越多,但边界不清楚 +- 同一个信息在多个地方重复出现,内容还不完全一致 +- 用户很难判断“去哪里看状态”“去哪里做操作”“去哪里管理公共配置” +- 设备管理、配置管理、调试页面混在一起,造成认知负担 -- the same concept appears in multiple places with slightly different wording -- device detail, device control, and configuration workflows overlap -- "configuration" is split across several parallel entry points such as `config-friendly`, `config-ui`, and `config-preview` -- top-level navigation mixes business objects with actions and technical tools -- users cannot quickly tell where to view status, where to operate a device, and where to manage reusable configuration assets +新的设计必须保证:同一种信息只有一个权威展示位置,页面职责清楚,用户能快速找到正确入口。 -This redesign intentionally does not patch those pages in place. It defines a new information architecture and treats existing pages only as implementation material that can be merged, replaced, or removed. +## 为什么现有 UI 已经不适合继续扩展 -## Product Scope +当前后台是围绕零散流程和已有接口逐步长出来的,所以会出现这些现象: -The backend is a unified management console for a small fleet of visual-recognition devices, usually no more than a dozen devices at a time. The most important responsibilities are: +- 同一个概念在多个页面里反复出现,只是叫法略有不同 +- 设备详情、设备操作、配置预览、配置修改互相重叠 +- `config-friendly`、`config-ui`、`config-preview` 三套入口并行存在 +- 一级导航混合了业务对象、页面功能、技术工具和调试能力 +- 用户在使用时很难形成稳定心智,不知道某类信息到底应该去哪一页看 -1. discover all devices and show their current operational state clearly -2. manage reusable configuration assets such as templates, profiles, and overlays -3. manage service and configuration operations for a single device -4. record operations and outcomes for administrative traceability +所以这次不是“优化现有导航文案”,而是重新定义整个后台的信息架构。 -The UI should optimize for clarity, fast scanning, and low duplication rather than for high-density fleet scale. +## 产品范围 -## Design Principles +这个后台的本质,是一个统一管理少量视觉识别设备的管理平台。设备规模通常不会超过十几台,因此设计重点应放在清晰、简洁、好判断,而不是面向超大规模设备的高密度监控墙。 -Every screen in the redesign follows these rules: +当前最重要的职责有四类: -1. One authoritative location per information type. - - Example: current running configuration is authoritative in device detail, not repeated as a second full status block elsewhere. -2. View and operate are separate. - - Read-only device understanding belongs to device detail. - - Actions such as apply, rollback, restart, and reload belong to device control. -3. Top-level navigation names business domains, not button actions. -4. Long technical fields are secondary. - - Device name is primary. - - `device_id`, raw paths, and raw JSON belong to secondary or advanced areas. -5. Icons and concise status markers are preferred over repeated explanatory text. -6. A page should answer one question well. - - "What is happening?" - - "What can I change?" - - "What assets exist?" - - "Who changed what?" +1. 发现所有设备,并清楚显示每台设备当前状态 +2. 统一管理模板、profile、overlay 等公共配置资产 +3. 管理单台设备的服务与配置操作 +4. 记录操作日志与系统管理行为 -## Reference Direction +## 设计原则 -The target product style should align with the clarity and consistency of ThingsBoard-style operations consoles: +后续所有页面和交互都必须遵守这几条原则: -- stable left navigation -- a clean workspace with strong section hierarchy -- compact but readable device status presentation -- separation between monitoring, asset management, and operations -- restrained visual style rather than generic CRUD admin forms +1. 同一个信息只允许有一个权威展示位置 + 例如:当前运行配置的完整权威摘要属于“设备详情”,其他页面只能显示简短摘要或跳转。 -This is a design reference, not a requirement to mimic ThingsBoard feature-for-feature. +2. 查看和操作必须分离 + “这台设备现在怎么样”与“我要对这台设备做什么”不能混在一个页面里。 -## Top-Level Information Architecture +3. 一级导航只放业务域,不放动作和技术工具 + 导航应该按对象组织,而不是按零散功能组织。 -The product should have exactly four top-level modules: +4. 长技术字段退居二级 + 设备名优先,`device_id`、路径、原始 JSON、内部字段都应降级显示。 + +5. 能用图标表达的状态,尽量不用大段文字 + 后台首先要支持快速扫视和判断,而不是让用户读说明书。 + +6. 每个页面只回答一个核心问题 + 比如: + - 现在发生了什么? + - 这台设备是什么状态? + - 我可以做哪些操作? + - 目前有哪些配置资产? + - 谁做过哪些变更? + +## 参考方向 + +整体风格参考 ThingsBoard 这类平台型运维后台,但不是照搬它的功能复杂度。我们借鉴的是它的设计气质和组织方式: + +- 左侧是稳定、克制的主导航 +- 主工作区层次清楚 +- 设备状态展示紧凑、易扫视 +- 查看、管理、审计分开 +- 风格统一、简洁,不做普通 CRUD 表单后台的拼贴感 + +## 一级信息架构 + +整个系统最终只保留四个一级模块: 1. `设备` 2. `配置资产` 3. `操作审计` 4. `系统` -These modules map directly to the product scope. +这四个模块正好对应产品的四个核心职责。 ### 1. 设备 -Purpose: answer "which devices exist, what state are they in, and which device needs attention?" +作用:回答“有哪些设备、每台设备当前是什么状态、哪台设备需要处理” -Includes: +包含: -- fleet summary -- device list -- single-device detail -- single-device control +- 全部设备总览 +- 设备列表 +- 单设备详情 +- 单设备控制 -Does not include: +不包含: -- reusable template/profile/overlay authoring -- platform-level settings -- audit history beyond short cross-links +- 模板 / profile / overlay 这类公共配置资产管理 +- 平台级系统设置 +- 全量审计日志主体内容 ### 2. 配置资产 -Purpose: answer "what reusable configuration building blocks exist?" +作用:回答“系统里有哪些可复用的配置资产” -Includes: +包含: -- templates -- profiles -- overlays -- release records or configuration publications +- 模板 +- 环境参数(Profiles) +- 覆盖项(Overlays) +- 配置发布记录 -Does not include: +不包含: -- live device status -- single-device service operations -- duplicated current running config displays +- 设备实时状态 +- 单设备服务控制 +- 当前运行配置的权威展示 ### 3. 操作审计 -Purpose: answer "who changed what, on which device, and what happened?" +作用:回答“谁在什么时间对哪台设备做了什么,结果怎样” -Includes: +包含: -- operation history -- operation result summaries -- filters by time, operator, target device, and action type +- 操作历史 +- 操作结果摘要 +- 按时间、设备、操作者、动作类型过滤 ### 4. 系统 -Purpose: answer "how is the management backend itself configured and authenticated?" +作用:回答“后台管理系统自身如何配置和运行” -Includes: +包含: -- discovery and registration settings -- agent authentication token management -- backend service health -- backend version -- OpenAPI or integration entry points +- 设备发现与注册设置 +- agent 认证与访问令牌管理 +- 后台服务健康状态 +- 后台版本信息 +- OpenAPI 与系统级入口 -Does not include: +不包含: -- routine device operations -- configuration authoring workflows +- 日常设备操作 +- 配置资产编辑 -## Home Page: Device Overview +## 首页:设备总览 -The default landing page is `设备`. +首页默认进入 `设备` 模块。 -The layout has two layers. +整体采用你确认过的混合结构:上方摘要,下方设备列表。 -### Top Summary Band +### 顶部摘要区 -Show concise fleet state with icon-led summary tiles: +顶部是一排图标化摘要卡,用于快速判断整体状态。建议至少包含: -- online devices -- offline devices -- media service abnormal devices -- configuration mismatch devices -- recent failed operations +- 在线设备数 +- 离线设备数 +- 服务异常设备数 +- 配置不一致设备数 +- 最近操作失败设备数 -The summary band is for quick scanning and filtering, not for detailed explanation. +这里不放解释性长文本,只负责总览和快速筛选。 -### Main Device List +### 主设备列表 -Below the summary band, present a compact device list. Since the fleet size is small, the design should optimize for readability rather than extreme table density. +摘要区下方是主设备列表。由于设备数量不多,不需要做极端高密度表格,应优先保证清晰易读。 -Each device row should show only the most decision-useful fields: +每台设备只显示最关键的信息: -- device icon -- meaningful device name -- online status -- media-server status -- current running config summary -- current software version -- last heartbeat -- quick entry actions +- 设备图标 +- 有意义的设备名 +- 在线状态 +- media-server 状态 +- 当前运行配置摘要 +- 当前软件版本 +- 最后心跳时间 +- 快捷入口 -### Device Identity Rules +### 设备身份显示规则 -- meaningful device name is always primary -- `device_id` is secondary and should not dominate the layout -- long technical identifiers appear only in tooltips, secondary text, or detail pages +- 设备名始终是主显示信息 +- `device_id` 只作为次级技术信息出现 +- 冗长标识不应成为列表主视觉元素 +- 技术字段可放在悬浮提示、次级说明或详情页中 -## Device Domain +## 设备域设计 -The device domain contains exactly two per-device pages: +每台设备下只保留两个页面: 1. `设备详情` 2. `设备控制` -This separation is mandatory. +这是强约束,不允许再把同类信息拆成多个平行页面。 ### 设备详情 -Purpose: understand the device, not operate it. +作用:只看,不操作。回答“这台设备现在是什么状态” -Shows: +应展示: -- device name -- device identity details: `device_id`, hostname, IP -- online/offline state and last heartbeat -- agent version, build metadata, git SHA -- media-server running state -- authoritative current running config summary -- recent status or alert summary -- links to operation audit and device control +- 设备名 +- `device_id`、hostname、IP +- 在线 / 离线状态 +- 最后心跳 +- agent 版本、build_id、git_sha +- media-server 运行状态 +- 当前运行配置权威摘要 +- 最近状态或异常摘要 +- 跳转到设备控制与操作审计 -Does not show: +不应展示: -- config preview editor -- candidate upload workflow -- apply/rollback forms -- raw JSON editor by default +- 配置预览编辑器 +- 候选配置上传操作 +- 应用 / 回滚按钮 +- 默认展开的原始 JSON 编辑区 ### 设备控制 -Purpose: operate a single device. +作用:只做操作。回答“我要对这台设备做什么” -Shows: +应展示: -- config preview generation workflow -- candidate upload -- apply candidate config -- rollback to previous config -- media-server start, stop, restart, reload -- result summary for the current operation +- 配置预览生成 +- 上传候选配置 +- 应用候选配置 +- 回滚到上一份配置 +- 启动 / 停止 / 重启 / 重载服务 +- 当前这次操作的结果摘要 -Important constraint: +约束: -- device control may show compact status context needed for safe operation -- device control must not repeat the full authoritative detail layout +- 设备控制页可以显示少量安全上下文,例如当前配置摘要、服务状态 +- 但不能重复完整设备详情页内容 -### Existing Config Entry Consolidation +### 现有配置入口的收敛方式 -The current UI has several overlapping entry points: +当前系统中以下几个入口职责重叠: - `config-friendly` - `config-ui` - `config-preview` -Under the redesign these are no longer separate product destinations. They become modes or panels inside `设备控制`, for example: +在新架构下,这三个不再作为独立产品页面存在,而是统一收进 `设备控制`,作为同一页面中的不同操作模式,例如: -- preview mode -- guided editing mode -- advanced JSON mode +- 预览模式 +- 引导编辑模式 +- 高级 JSON 模式 -This keeps one operational home for single-device configuration work. +这样设备配置操作就只有一个主入口,不再让用户在多个相似页面之间来回跳。 -## Configuration Assets Domain +## 配置资产域设计 -`配置资产` manages reusable configuration inputs rather than live device state. +`配置资产` 用来管理可复用的配置组成部分,而不是管理某台设备当前正在运行什么。 -It should contain four subareas: +建议拆成四个子区: 1. `模板` -2. `Profiles` -3. `Overlays` +2. `环境参数` +3. `覆盖项` 4. `发布记录` ### 模板 -Manages core configuration templates and their metadata, purpose, and compatibility notes. +管理核心配置模板,以及模板用途、适用范围、说明等元数据。 -### Profiles +### 环境参数 -Manages environment-specific differences such as endpoints, source addresses, MinIO, token API, and other per-device or per-site parameters that should not require full JSON duplication. +管理设备或环境差异参数,例如: -### Overlays +- 视频源地址 +- 后台地址 +- MinIO 参数 +- token API +- 站点级或设备级差异项 -Manages reusable overlays such as debug options, sensitivity changes, and production quiet presets. +这类差异不应再靠维护多份完整 JSON 来表达。 + +### 覆盖项 + +管理可重复使用的覆盖项,例如: + +- debug 开关 +- 敏感度调整 +- production quiet +- 其他运行策略覆盖 ### 发布记录 -Tracks rendered or published configurations produced from: +用于记录某次配置生成或发布的来源和结果。至少应能表达: -- one template -- one profile -- zero or more overlays +- 来自哪个模板 +- 使用哪个 profile +- 叠加了哪些 overlays +- 生成了什么配置标识 +- 应用了哪些设备 +- 应用结果如何 -And records: +这个区域负责把“配置资产”与“设备应用行为”连接起来,但不承担设备状态页的职责。 -- generated config identity -- target devices -- apply results +## 操作审计域设计 -This is the bridge between assets and operational rollout, without mixing assets into device state pages. +`操作审计` 是专门的操作历史页,不应再混杂进其他页面的主体区域。 -## Audit Domain +每条审计记录至少应包含: -`操作审计` is a dedicated operations history surface. +- 操作时间 +- 操作者 +- 目标设备 +- 动作类型 +- 输入摘要 +- 执行结果 +- 执行耗时 +- 失败原因 -Each record should include: +动作类型至少包括: -- timestamp -- operator -- target device -- action type -- input summary -- result -- duration -- failure reason when applicable +- 上传候选配置 +- 应用候选配置 +- 回滚配置 +- 重载服务 +- 启动服务 +- 停止服务 +- 重启服务 +- 批量操作 -Action types should include at least: +操作审计的目标是形成管理闭环,而不是暴露底层 HTTP 调试细节。 -- upload candidate config -- apply candidate config -- rollback config -- reload service -- start service -- stop service -- restart service -- batch actions +## 系统域设计 -The goal is traceability and accountability, not raw transport debugging. +`系统` 只放平台级设置和后台自身状态,保持克制,不要再变成杂物间。 -## System Domain +建议包含: -`系统` should remain intentionally small and platform-scoped. +- 设备发现与注册设置 +- 后台访问 agent 的认证设置 +- 后台服务健康 +- 后台版本 / build 信息 +- OpenAPI 入口 -Expected content: +不建议放入: -- discovery and registration settings -- backend-to-agent authentication settings -- backend health -- backend version/build info -- OpenAPI entry +- 日常设备控制动作 +- 模板 / profile / overlay 资产管理 -This module should not become a second admin junk drawer. +## 页面与路由目标形态 -## Page And Route Outcome +实现后整体结构应逐步收敛为下面这类路由: -The redesign should converge the product toward the following destination structure: - -- `/ui/devices` -> device overview -- `/ui/devices/{id}` -> device detail -- `/ui/devices/{id}/control` -> device control +- `/ui/devices` -> 设备总览 +- `/ui/devices/{id}` -> 设备详情 +- `/ui/devices/{id}/control` -> 设备控制 - `/ui/assets/templates` - `/ui/assets/profiles` - `/ui/assets/overlays` @@ -330,73 +359,73 @@ The redesign should converge the product toward the following destination struct - `/ui/audit` - `/ui/system` -Exact route naming can be adjusted during implementation, but the domain boundaries should not change. +具体命名可以在实现时微调,但页面边界不应变化。 -## Existing Pages To Remove Or Merge +## 需要移除或并入的旧页面概念 -The following concepts should no longer survive as separate top-level product destinations: +以下内容不应再继续作为一级页面或独立主入口存在: - `识别配置` - `配置管理` -- `模型管理` as a standalone first-class top-level domain unless future scope proves it deserves one -- `高级调试` as a top-level navigation item -- `服务健康` as a top-level navigation item -- `OpenAPI` as a top-level navigation item +- `模型管理` 作为一级入口 +- `高级调试` 作为一级入口 +- `服务健康` 作为一级入口 +- `OpenAPI` 作为一级入口 -More specifically, these configuration pages must be merged into device control instead of remaining parallel entry points: +特别是以下三个配置页面,必须并入设备控制,不再平行存在: - `config-friendly` - `config-ui` - `config-preview` -The redesign intentionally prefers one clean operational flow over multiple similar configuration pages. +这次重设计的核心之一,就是用一个清晰的设备控制入口,替代多个“看起来差不多”的配置页。 -## Data Ownership Rules +## 信息归属规则 -To prevent UI duplication from returning later, the implementation should enforce these ownership rules: +为了防止以后再次出现重复页面,后续实现必须遵守下面的信息归属: -- fleet-wide device status summary belongs to device overview -- authoritative current running config summary belongs to device detail -- configuration operations belong to device control -- reusable templates/profiles/overlays belong to configuration assets -- operation history belongs to audit -- system configuration and platform health belong to system +- 全局设备状态摘要属于设备总览 +- 当前运行配置的权威摘要属于设备详情 +- 配置操作属于设备控制 +- 模板 / profile / overlay 属于配置资产 +- 操作历史属于操作审计 +- 平台设置与平台健康属于系统 -When another page needs the same information, it should link to the owner or show only a short derivative summary. +其他页面如果需要引用这些信息,只能显示摘要或者跳转,不能再次变成完整展示页。 -## Error Handling And Empty States +## 错误状态与空状态 -The redesign should preserve clarity under imperfect conditions: +新架构必须能在不理想情况下仍然保持清晰: -- offline devices remain visible with obvious offline styling -- missing configuration metadata should degrade gracefully with compact placeholders -- operation failures should show concise summaries and a path to audit detail -- configuration asset lists should explain when no templates, profiles, or overlays are available +- 离线设备也必须可见,只是状态明显不同 +- 配置 metadata 缺失时,应优雅降级,而不是把页面弄乱 +- 操作失败时,应展示简洁结果,并提供进入审计详情的入口 +- 模板、profile、overlay 为空时,应明确告诉用户当前没有资产,而不是留白 -The product should avoid dumping raw JSON or transport-level messages into primary workflows unless the user explicitly enters an advanced mode. +默认主流程中,不应直接把原始 JSON、HTTP 报错或调试信息大面积暴露给用户,除非用户明确进入高级模式。 -## Verification +## 验证要求 -The first implementation phase should verify at least: +第一阶段实现至少要完成: ```bash go test ./... ``` -And UI coverage should confirm: +同时 UI 层面的验证应覆盖: -- only the approved top-level domains remain in navigation -- device detail and device control are separate pages with separate responsibilities -- old overlapping config entry points no longer appear as peer destinations -- device overview emphasizes device name and status over raw technical identifiers +- 导航中只保留批准后的一级模块 +- 设备详情和设备控制已经彻底分离 +- 旧的多个配置入口不再以平级页面形式存在 +- 设备总览以设备名和状态为主,而不是以技术标识为主 -## Non-Goals +## 非目标 -This redesign does not require: +这次重设计不追求以下内容: -- a high-scale fleet experience for hundreds of devices -- real-time animated monitoring dashboards -- broad feature expansion unrelated to device/config/audit/system boundaries -- exposing more internal pipeline parameters to ordinary users +- 面向几百台设备的超大规模监控体验 +- 大量动态动画或实时监控大屏 +- 与设备 / 配置 / 审计 / 系统边界无关的功能扩张 +- 向普通用户暴露更多内部算法和管线参数 -The goal is a cleaner, more understandable product, not a larger one. +这次工作的目标,是把后台做得更清楚、更统一、更容易理解,而不是把它做得更大。