diff --git a/.gitignore b/.gitignore index 2a23fc2..ecfc3eb 100644 --- a/.gitignore +++ b/.gitignore @@ -12,9 +12,6 @@ logs/ *.log managerd.local.json -# Agent workflow notes -docs/superpowers/ - # Coverage and profiling coverage.out *.coverprofile 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 new file mode 100644 index 0000000..542e6b6 --- /dev/null +++ b/docs/superpowers/specs/2026-04-19-device-config-ia-redesign.md @@ -0,0 +1,402 @@ +# 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. + +## 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. + +## 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: + +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?" + +## 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 + +This is a design reference, not a requirement to mimic ThingsBoard feature-for-feature. + +## Top-Level Information Architecture + +The product should have exactly four top-level modules: + +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 + +### 2. 配置资产 + +Purpose: answer "what reusable configuration building blocks exist?" + +Includes: + +- templates +- profiles +- 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 +- backend service health +- backend version +- OpenAPI or integration entry points + +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 + +### 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 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 + +Does not show: + +- config preview editor +- candidate upload workflow +- apply/rollback forms +- raw JSON editor by default + +### 设备控制 + +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 + +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` +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 + +Manages reusable overlays such as debug options, sensitivity changes, and production quiet presets. + +### 发布记录 + +Tracks rendered or published configurations produced from: + +- one template +- one profile +- zero or more 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: + +- 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. + +Expected content: + +- discovery and registration settings +- backend-to-agent authentication settings +- 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` -> device overview +- `/ui/devices/{id}` -> device detail +- `/ui/devices/{id}/control` -> device control +- `/ui/assets/templates` +- `/ui/assets/profiles` +- `/ui/assets/overlays` +- `/ui/assets/releases` +- `/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 + +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 + +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 + +The product should avoid dumping raw JSON or transport-level messages into primary workflows unless the user explicitly enters an advanced mode. + +## Verification + +The first implementation phase should verify at least: + +```bash +go test ./... +``` + +And UI coverage should confirm: + +- 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.