Add backend IA redesign spec
This commit is contained in:
parent
ad460465a5
commit
5f78ce5430
3
.gitignore
vendored
3
.gitignore
vendored
@ -12,9 +12,6 @@ logs/
|
||||
*.log
|
||||
managerd.local.json
|
||||
|
||||
# Agent workflow notes
|
||||
docs/superpowers/
|
||||
|
||||
# Coverage and profiling
|
||||
coverage.out
|
||||
*.coverprofile
|
||||
|
||||
402
docs/superpowers/specs/2026-04-19-device-config-ia-redesign.md
Normal file
402
docs/superpowers/specs/2026-04-19-device-config-ia-redesign.md
Normal file
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user