Translate IA redesign spec to Chinese

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.
+1. 发现所有设备，并清楚显示每台设备当前状态
-   - Example: current running configuration is authoritative in device detail, not repeated as a second full status block elsewhere.
+2. 统一管理模板、profile、overlay 等公共配置资产
-2. View and operate are separate.
+3. 管理单台设备的服务与配置操作
-   - Read-only device understanding belongs to device detail.
+4. 记录操作日志与系统管理行为
-   - 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?"
 
-## Reference Direction
+## 设计原则
 
-The target product style should align with the clarity and consistency of ThingsBoard-style operations consoles:
+后续所有页面和交互都必须遵守这几条原则：
 
-- stable left navigation
+1. 同一个信息只允许有一个权威展示位置  
-- 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
 
-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
+- 模板 / profile / overlay 这类公共配置资产管理
-- platform-level settings
+- 平台级系统设置
-- audit history beyond short cross-links
+- 全量审计日志主体内容
 
 ### 2. 配置资产
 
-Purpose: answer "what reusable configuration building blocks exist?"
+作用：回答“系统里有哪些可复用的配置资产”
 
-Includes:
+包含：
 
-- templates
+- 模板
-- profiles
+- 环境参数（Profiles）
-- overlays
+- 覆盖项（Overlays）
-- release records or configuration publications
+- 配置发布记录
 
-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
+- agent 认证与访问令牌管理
-- backend service health
+- 后台服务健康状态
-- backend version
+- 后台版本信息
-- OpenAPI or integration entry points
+- 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
+- media-server 状态
-- current running config summary
+- 当前运行配置摘要
-- current software version
+- 当前软件版本
-- last heartbeat
+- 最后心跳时间
-- quick entry actions
+- 快捷入口
 
-### Device Identity Rules
+### 设备身份显示规则
 
-- meaningful device name is always primary
+- 设备名始终是主显示信息
-- `device_id` is secondary and should not dominate the layout
+- `device_id` 只作为次级技术信息出现
-- long technical identifiers appear only in tooltips, secondary text, or detail pages
+- 冗长标识不应成为列表主视觉元素
+- 技术字段可放在悬浮提示、次级说明或详情页中
 
-## 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
+- `device_id`、hostname、IP
-- online/offline state and last heartbeat
+- 在线 / 离线状态
-- agent version, build metadata, git SHA
+- 最后心跳
-- media-server running state
+- agent 版本、build_id、git_sha
-- authoritative current running config summary
+- media-server 运行状态
-- recent status or alert summary
+- 当前运行配置权威摘要
-- links to operation audit and device control
+- 最近状态或异常摘要
+- 跳转到设备控制与操作审计
 
-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`
+2. `环境参数`
-3. `Overlays`
+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
+- 使用哪个 profile
-- zero or more overlays
+- 叠加了哪些 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
+- 模板 / profile / overlay 资产管理
-- backend health
-- backend version/build info
-- OpenAPI entry
 
-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` -> 设备总览
-
+- `/ui/devices/{id}` -> 设备详情
-- `/ui/devices` -> device overview
+- `/ui/devices/{id}/control` -> 设备控制
-- `/ui/devices/{id}` -> device detail
-- `/ui/devices/{id}/control` -> device 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
+- 模板 / profile / overlay 属于配置资产
-- operation history belongs to audit
+- 操作历史属于操作审计
-- system configuration and platform health belong to system
+- 平台设置与平台健康属于系统
 
-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
+- 配置 metadata 缺失时，应优雅降级，而不是把页面弄乱
-- 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
+- 模板、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.
+这次工作的目标，是把后台做得更清楚、更统一、更容易理解，而不是把它做得更大。