safesight-control/docs/superpowers/specs/2026-04-20-profile-editor-design.md

Profile 配置编辑页设计方案

背景

当前后台已经具备模板、Profile、Overlay 资产浏览能力，但 Profile 页面仍然是只读详情页，无法承载“以设备独有属性为中心”的配置管理流程。

这与当前项目的配置方向不一致：

• 模板负责共享能力与公共服务接入
• Profile 负责单台设备的独有属性
• Overlay 负责测试、调优、生产安静模式等附加差异

因此，后台需要把 Profile 从“资产查看页”升级为“设备独有配置编辑入口”。

目标

本次设计只解决一个核心问题：

让运维人员能够在后台中，以清晰、低冗余的方式查看和编辑 Profile 中真正属于单台设备的配置。

本次不试图一次性完成所有配置管理问题，重点只放在：

1. 明确 Profile 的字段边界
2. 设计可编辑的 Profile 页面结构
3. 设计与现有“生成预览 / 上传候选配置”流程的衔接方式

设计原则

1. Profile 只放设备独有属性

Profile 的职责是表达“这台设备是谁、接什么视频、向哪里输出”。

因此，下面这类内容应归属于 Profile：

• 设备显示名
• 实例名
• 站点名
• 设备编号
• 视频源地址
• HLS / RTSP 输出信息
• 通道号
• 少量单设备调试项

2. 模板继续负责共享服务接入

下面这类共享服务配置不应出现在 Profile 编辑页中：

• MinIO
• 外部告警接口
• token 接口
• 租户编码

这些内容继续由模板负责，并在模板资产页面中管理。

3. 内部默认值不向用户暴露

已经确认应内收进程序默认值或模板默认值的内容，不应进入 Profile 编辑页，例如：

• face_gallery_path
• 纯内部含义、易误配的底层参数

如果某些少量调试项暂时仍需保留，也必须进入“高级设置”，并默认折叠。

4. 页面围绕运维任务组织，不平铺 JSON

Profile 编辑页不是原始 JSON 的表单化翻译，而是围绕运维任务组织：

• 先认识这台设备
• 再看它接什么视频
• 再看它往哪里输出
• 最后才是少量高级参数

原始 JSON 只作为参考内容收起展示，不参与默认工作流。

Profile 字段边界

应展示的核心字段

基础信息

• Profile 名称
• 实例名 name
• 设备显示名 display_name
• 设备编号 device_code
• 站点名 site_name
• 通道号 channel_no

视频源

• 视频源地址 rtsp_url

输出流

• HLS 输出路径 publish_hls_path
• RTSP 输出端口 publish_rtsp_port
• RTSP 输出路径 publish_rtsp_path

Profile 级队列设置

• queue.size
• queue.strategy

这部分虽然不是“设备身份信息”，但仍属于当前 Profile 文件本身，且对单设备运行行为有影响，因此保留在编辑页中，但应作为次级信息展示，不放在第一视觉层。

放入高级设置的字段

凡是仍存在于 instance.params 中，但不属于日常运维主流程的字段，统一归入“高级设置”，默认折叠。

高级设置必须满足两个前提：

1. 确实还有业务意义
2. 用户误改后不会轻易破坏系统关键行为

如果某个字段既不常改、又容易出错，则不应继续停留在 Profile 中，而应在后续迭代中内收。

不展示的字段

以下内容不应在 Profile 编辑页直接展示：

• 模板共享服务参数
• 纯内部默认值
• 原始路径类技术字段
• 不面向运维用户的底层算法开关

页面结构

Profile 编辑页采用“四个 tab + 底部统一动作区”的结构。

Tab 1：基础信息

作用：定义这台设备“是谁”。

字段：

• Profile 名称
• 实例名
• 设备显示名
• 设备编号
• 站点名
• 通道号

默认要求：

• 这一页应是用户最常进入的页签
• 设备显示名是最重要的人类可读字段
• 不显示主机名、device_id 等运行态信息

Tab 2：视频源

作用：定义这台设备“从哪里取流”。

字段：

• RTSP 地址

表现要求：

• 使用大一点的单行输入框，便于复制粘贴和检查
• 技术格式提示尽量弱化，不写成长段说明

Tab 3：输出流

作用：定义这台设备“向哪里发布”。

字段：

• HLS 输出路径
• RTSP 输出端口
• RTSP 输出路径

表现要求：

• HLS 与 RTSP 分组展示
• 输出相关字段使用等宽字体输入框，方便检查路径和端口

Tab 4：高级设置

作用：承载少量仍保留在 Profile 中的非主流程参数。

表现要求：

• 默认折叠
• 不出现大量解释性说明
• 如果当前 Profile 没有高级字段，则展示为空状态，不额外制造占位噪音

操作区设计

页面底部只保留 3 个核心动作：

1. 保存
2. 生成预览
3. 上传为候选配置

不增加多余的跳转按钮、说明按钮、查看原始 JSON 按钮。

保存

作用：

• 仅保存当前 Profile 资产内容
• 不直接影响设备运行态

生成预览

作用：

• 使用当前编辑中的 Profile
• 结合选定模板与 Overlay
• 生成预览摘要与渲染结果

上传为候选配置

作用：

• 将当前预览结果上传到目标设备 agent
• 不直接等同于立即应用

这与现有“候选配置 -> 应用候选配置”的流程保持一致。

与现有页面关系

配置资产总页

Profile tab 继续保留为资产入口，但点击某个 Profile 后，进入的不再是只读详情，而是编辑页。

设备页

设备页仍然负责展示当前运行配置摘要，不承担 Profile 资产编辑职责。

也就是说：

• “现在设备跑的是什么” 去设备页看
• “这个 Profile 本身如何定义” 去配置资产页编辑

这样可以避免运行态信息与资产定义混在一起。

数据结构改动

后台内部需要把现有只读 ConfigProfileAsset 扩展为“适合编辑表单”的视图模型，但不改变底层 Profile JSON 的存储格式。

建议拆成两层：

1. 资产读取层
   继续负责从 configs/profiles/*.json 读取原始结构

2. 表单视图层
   提供页面渲染和提交时需要的扁平字段

这样能避免模板层、资产层、提交层混成一个数据结构。

提交流程

本次只设计最短主流程，不增加复杂版本控制。

读取

1. 打开 Profile 编辑页
2. 后台读取目标 Profile JSON
3. 解析为编辑表单模型

保存

1. 用户修改字段
2. 提交表单
3. 后台校验必填字段
4. 重建 Profile JSON
5. 回写到 configs/profiles/<name>.json

生成预览

1. 读取当前表单值
2. 与所选模板、Overlay 组合
3. 走现有渲染逻辑
4. 在页面中展示预览摘要

上传候选配置

1. 复用当前预览结果
2. 调用现有 agent 上传接口
3. 返回候选配置结果摘要

校验规则

首轮只做最必要的输入校验：

• Profile 名称不能为空
• 实例名不能为空
• 设备显示名不能为空
• RTSP 地址不能为空
• RTSP 端口如果填写，必须是合法数字

其余更强约束可以后续再加，不在本次首轮中扩展。

错误处理

错误展示分三层：

1. 表单校验错误
   直接挂在对应字段旁边

2. 保存 / 预览 / 上传失败
   在操作区上方显示一条明确错误消息

3. 原始技术细节
   收纳在可折叠技术信息区，不默认展开

测试策略

本次优先做后台本地可验证部分：

1. Profile 资产读取与表单映射测试
2. Profile 表单提交后的 JSON 重建测试
3. Profile 页面渲染测试
4. 现有预览/上传链路的回归测试

RK3588 真机验证仍然由现有设备侧配置下发流程完成，不在本地伪装硬件验证。

实施顺序

建议按下面顺序推进：

1. 补充 Profile 编辑页设计文档
2. 后台数据结构增加表单视图模型
3. 将 Profile 详情页替换为四个 tab 的编辑页
4. 接入保存逻辑
5. 接入生成预览逻辑
6. 接入上传为候选配置逻辑
7. 跑本地 UI 与服务测试
8. 再由设备侧验证实际下发与应用链路

结论

Profile 编辑页应成为“单设备独有属性”的权威编辑入口，而不是继续做成原始 JSON 的浏览页。

它的边界必须非常明确：

• 共享服务归模板
• 单设备属性归 Profile
• 差异调优归 Overlay

只有这样，后续“设备命名、视频源、输出流、候选配置下发”这条主线才会真正清晰，后台的配置管理也才不会重新退回到信息混杂、入口重复的状态。