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