From 04de2308fbed379ffff1f3bf8d97cb54fb211ff1 Mon Sep 17 00:00:00 2001
From: tian <11429339@qq.com>
Date: Mon, 20 Apr 2026 10:44:18 +0800
Subject: [PATCH] Add profile-centered config design spec

---
 ...26-04-20-profile-centered-config-design.md | 331 ++++++++++++++++++
 1 file changed, 331 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-04-20-profile-centered-config-design.md

diff --git a/docs/superpowers/specs/2026-04-20-profile-centered-config-design.md b/docs/superpowers/specs/2026-04-20-profile-centered-config-design.md
new file mode 100644
index 0000000..3c4a425
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-20-profile-centered-config-design.md
@@ -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.