Add profile-centered config design spec
This commit is contained in:
parent
3e747be2e6
commit
04de2308fb
@ -0,0 +1,331 @@
|
||||
# Profile-Centered Config Design
|
||||
|
||||
## Purpose
|
||||
|
||||
Clarify the field boundary between `template`, `profile`, and `overlay` so the backend management system can treat `profile` as a first-class asset instead of a simple dropdown.
|
||||
|
||||
The target operating model is:
|
||||
|
||||
- one physical device maps to one profile
|
||||
- templates stay reusable across multiple devices and sites
|
||||
- overlays stay limited to debug, sensitivity, and temporary runtime modes
|
||||
- internal media-server implementation parameters remain hidden from normal users
|
||||
|
||||
This design builds on the existing template rendering workflow and does not return to hand-maintained full JSON files.
|
||||
|
||||
## Current Context
|
||||
|
||||
The current maintained config source is:
|
||||
|
||||
- template: `configs/templates/workshop_face_shoe_alarm.json`
|
||||
- profile: `configs/profiles/local_3588_test.json`
|
||||
- overlays: `configs/overlays/*.json`
|
||||
- generated runtime config: `configs/generated/*.json`
|
||||
|
||||
Current reality from the config files:
|
||||
|
||||
- `template` already carries the pipeline skeleton, node graph, models, alarm structure, and default thresholds
|
||||
- `overlay` already behaves well as debug/test/quiet mode overrides
|
||||
- `profile` already contains some device-specific fields such as `rtsp_url`, but it also mixes in shared external-service settings
|
||||
|
||||
That mix is the main problem. It prevents the backend from cleanly exposing profile management as "device/site identity and connection settings".
|
||||
|
||||
## Design Goals
|
||||
|
||||
1. Make `profile` the canonical home of one device's identity and per-device connection settings.
|
||||
2. Keep shared scheme-level settings reusable through templates.
|
||||
3. Keep overlays small and operational.
|
||||
4. Prevent low-level implementation knobs from leaking into the user-facing config UI.
|
||||
5. Support multiple templates, with each template remaining flexible enough to connect to different external services and storage backends.
|
||||
|
||||
## Field Ownership
|
||||
|
||||
### Template
|
||||
|
||||
`template` owns scheme-level shared configuration.
|
||||
|
||||
Typical contents:
|
||||
|
||||
- DAG structure: `nodes`, `edges`
|
||||
- plugin/node selection
|
||||
- shared model defaults
|
||||
- shared algorithm defaults
|
||||
- shared alarm action structure
|
||||
- shared external service settings
|
||||
- shared storage settings
|
||||
- default publish protocol structure
|
||||
|
||||
Examples from `workshop_face_shoe_alarm.json`:
|
||||
|
||||
- node types and node IDs
|
||||
- model paths and model sizes
|
||||
- tracker mode and default tracking thresholds
|
||||
- alarm rule structure
|
||||
- snapshot/clip upload structure
|
||||
- external API action structure
|
||||
- publish outputs structure
|
||||
|
||||
Important rule:
|
||||
|
||||
- shared services in `template` must remain editable template parameters
|
||||
- they must not be treated as hard-coded constants
|
||||
|
||||
That allows multiple templates to point at different MinIO or external alarm services when needed.
|
||||
|
||||
### Profile
|
||||
|
||||
`profile` owns per-device identity and per-device runtime bindings.
|
||||
|
||||
One profile corresponds to one physical device.
|
||||
|
||||
Typical contents:
|
||||
|
||||
- business display name
|
||||
- site/area identity
|
||||
- device-local input source
|
||||
- device-local publish output parameters
|
||||
- device-local resource paths
|
||||
- any device-bound runtime identifier needed by external systems
|
||||
|
||||
Current fields that should stay in profile:
|
||||
|
||||
- `rtsp_url`
|
||||
- `rga_gate`
|
||||
- `face_gallery_path`
|
||||
|
||||
New profile-level fields recommended by this design:
|
||||
|
||||
- `display_name`
|
||||
- `device_code`
|
||||
- `site_name`
|
||||
- `area_name`
|
||||
- `publish_hls_path`
|
||||
- `publish_rtsp_port`
|
||||
- `publish_rtsp_path`
|
||||
- `channel_no`
|
||||
|
||||
The backend device list should primarily show `display_name`. Technical identifiers such as `device_id` and `hostname` belong in device detail views.
|
||||
|
||||
### Overlay
|
||||
|
||||
`overlay` owns short-lived operating modes.
|
||||
|
||||
Allowed uses:
|
||||
|
||||
- debug switches
|
||||
- sensitive test thresholds
|
||||
- quiet production mode
|
||||
- temporary validation behavior
|
||||
|
||||
Examples already aligned with this rule:
|
||||
|
||||
- `face_debug.json`
|
||||
- `shoe_debug.json`
|
||||
- `face_test_sensitive.json`
|
||||
- `shoe_test_sensitive.json`
|
||||
- `production_quiet.json`
|
||||
|
||||
Overlays should not carry:
|
||||
|
||||
- device identity
|
||||
- device-local video sources
|
||||
- per-device publish host/path/port
|
||||
- long-lived external service ownership
|
||||
|
||||
### Hidden Internal Defaults
|
||||
|
||||
These should stay out of normal backend config editing:
|
||||
|
||||
- `cpu_affinity`
|
||||
- queue implementation details
|
||||
- `rga_max_inflight`
|
||||
- low-level tensor/input/output assumptions
|
||||
- internal plugin glue parameters
|
||||
- other fields that are easy to misconfigure and mainly matter to engineering
|
||||
|
||||
These may still exist in template JSON, but they should not be presented as normal user-editable fields.
|
||||
|
||||
## Standard Profile Model
|
||||
|
||||
Recommended logical sections for one profile:
|
||||
|
||||
### 1. Device Identity
|
||||
|
||||
- `display_name`
|
||||
- `device_code`
|
||||
- `site_name`
|
||||
- `area_name`
|
||||
|
||||
### 2. Input Source
|
||||
|
||||
- `rtsp_url`
|
||||
|
||||
### 3. Publish Output
|
||||
|
||||
- `publish_hls_path`
|
||||
- `publish_rtsp_port`
|
||||
- `publish_rtsp_path`
|
||||
- `channel_no`
|
||||
|
||||
Reasoning:
|
||||
|
||||
- publish output is per-device, not shared
|
||||
- it includes device-specific IP/host/port/path semantics
|
||||
- it often determines how downstream systems consume that specific box
|
||||
|
||||
### 4. Device-Local Resources
|
||||
|
||||
- `face_gallery_path`
|
||||
- `rga_gate`
|
||||
- future device-local model or mount paths if needed
|
||||
|
||||
## Template Parameter Model
|
||||
|
||||
Shared services should remain template-level parameters, not profile fields, when they are scheme-level common settings.
|
||||
|
||||
Recommended template-managed shared fields:
|
||||
|
||||
- `minio_endpoint`
|
||||
- `minio_bucket`
|
||||
- `minio_access_key`
|
||||
- `minio_secret_key`
|
||||
- `external_get_token_url`
|
||||
- `external_put_message_url`
|
||||
- `tenant_code`
|
||||
|
||||
Reasoning:
|
||||
|
||||
- these are often shared across a deployment scheme
|
||||
- repeating them in every profile creates duplication and drift
|
||||
- different templates may legitimately use different shared services, so they must remain editable per template
|
||||
|
||||
## Render Parameter Migration
|
||||
|
||||
The following current parameters already exist in the template:
|
||||
|
||||
- `${rtsp_url}`
|
||||
- `${rga_gate}`
|
||||
- `${face_gallery_path}`
|
||||
- `${minio_endpoint}`
|
||||
- `${minio_bucket}`
|
||||
- `${minio_access_key}`
|
||||
- `${minio_secret_key}`
|
||||
- `${external_get_token_url}`
|
||||
- `${external_put_message_url}`
|
||||
- `${tenant_code}`
|
||||
- `${name}`
|
||||
|
||||
This design recommends the following next migration:
|
||||
|
||||
### Keep as profile-driven placeholders
|
||||
|
||||
- `${rtsp_url}`
|
||||
- `${rga_gate}`
|
||||
- `${face_gallery_path}`
|
||||
|
||||
### Keep as template-driven placeholders
|
||||
|
||||
- `${minio_endpoint}`
|
||||
- `${minio_bucket}`
|
||||
- `${minio_access_key}`
|
||||
- `${minio_secret_key}`
|
||||
- `${external_get_token_url}`
|
||||
- `${external_put_message_url}`
|
||||
- `${tenant_code}`
|
||||
|
||||
### Add new profile-driven placeholders
|
||||
|
||||
- `${display_name}` if needed by backend-facing metadata or labels
|
||||
- `${publish_hls_path}`
|
||||
- `${publish_rtsp_port}`
|
||||
- `${publish_rtsp_path}`
|
||||
- `${channel_no}`
|
||||
|
||||
## Publish Output Adjustment
|
||||
|
||||
Current template publish outputs are structurally correct, but some fields should stop being fixed literals.
|
||||
|
||||
Recommended change:
|
||||
|
||||
- keep output protocol structure in template
|
||||
- move per-device output values to profile-backed placeholders
|
||||
|
||||
Suggested publish section direction:
|
||||
|
||||
- HLS output path: use `${publish_hls_path}`
|
||||
- RTSP server port: use `${publish_rtsp_port}`
|
||||
- RTSP server path: use `${publish_rtsp_path}`
|
||||
- external API `channelNo`: use `${channel_no}` instead of `${name}`
|
||||
|
||||
Reasoning:
|
||||
|
||||
- `name` currently mixes instance identity with external business channel semantics
|
||||
- external platform channel identity should be explicit
|
||||
- publish paths and ports are clearly per-device runtime settings
|
||||
|
||||
## Backend Management Implications
|
||||
|
||||
This boundary implies the backend should evolve toward the following asset model:
|
||||
|
||||
### Device
|
||||
|
||||
Operational object discovered from the agent:
|
||||
|
||||
- device ID
|
||||
- hostname
|
||||
- agent reachability
|
||||
- media-server state
|
||||
- current applied config metadata
|
||||
|
||||
### Profile
|
||||
|
||||
Managed configuration asset bound one-to-one to a device:
|
||||
|
||||
- edited in a dedicated profile detail page
|
||||
- contains device identity, input, output, and local resource settings
|
||||
|
||||
### Template
|
||||
|
||||
Managed reusable scheme asset:
|
||||
|
||||
- edited in a dedicated template detail page
|
||||
- contains pipeline structure and shared service parameters
|
||||
|
||||
### Overlay
|
||||
|
||||
Managed operational mode asset:
|
||||
|
||||
- selected during preview/apply workflows
|
||||
- not used as the primary place to hold stable device identity
|
||||
|
||||
## UI Consequences
|
||||
|
||||
The backend should stop treating profile as only a dropdown.
|
||||
|
||||
Minimum intended direction:
|
||||
|
||||
1. profile becomes a first-class asset under config management
|
||||
2. every device detail page should clearly show which profile is bound to it
|
||||
3. device display name should come from profile, not from raw agent defaults
|
||||
4. preview/apply pages only select profile; they should not be the main place where profile data is edited
|
||||
|
||||
## Migration Direction
|
||||
|
||||
This design does not require immediate large-scale config rewrites. A practical migration path is:
|
||||
|
||||
1. define the standard profile field model
|
||||
2. parameterize publish output fields in the template
|
||||
3. move shared external-service settings from profile into template-managed parameters
|
||||
4. introduce backend profile pages and device-profile binding UI
|
||||
5. keep overlays unchanged except for normal cleanup
|
||||
|
||||
## Out of Scope
|
||||
|
||||
This design does not yet define:
|
||||
|
||||
- the full backend profile editor UI layout
|
||||
- template editor UI schema generation
|
||||
- automatic migration tooling for old profile JSON files
|
||||
- permission models for editing templates vs profiles
|
||||
|
||||
Those should be handled in the next design and implementation planning step.
|
||||
Loading…
Reference in New Issue
Block a user