3588AdminBackend/docs/superpowers/specs/2026-04-20-profile-editor-design.md

业务配置编辑页设计方案

背景

当前后台已经具备配置模板、业务配置、配置叠加项资产浏览能力，但业务配置页面仍然需要承载“以业务场景和视频通道为中心”的配置管理流程。

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

• 配置模板负责共享能力与公共服务接入
• 业务配置负责站点业务、视频通道、输入流和输出流
• 配置叠加项负责测试、调优、生产安静模式等附加差异

因此，后台需要把业务配置从“资产查看页”升级为“业务场景配置编辑入口”。

目标

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

让运维人员能够在后台中，以清晰、低冗余的方式查看和编辑业务配置中真正属于某个业务场景及其多路视频通道的配置。

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

1. 明确业务配置的字段边界
2. 设计可编辑的业务配置页面结构
3. 明确业务配置编辑页与设备配置发布页的边界

设计原则

1. 业务配置只放业务场景和视频通道属性

业务配置的职责是表达“这个业务场景在哪个站点、有哪些视频通道、每个通道从哪里取流、向哪里输出”。

因此，下面这类内容应归属于业务配置：

• 业务显示名
• 业务名称 business_name
• 通道名
• 站点名
• 视频源地址
• HLS / RTSP 输出信息
• 通道号
• 少量业务场景调试项

设备 ID、主机名、IP 地址、设备别名、设备编号等属于设备资产信息，不应作为视频通道字段暴露在业务配置页面。历史配置中的 device_code 在设备资产页面完成前由后台保存时原样保留，但不在业务配置 UI 中展示或编辑。

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

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

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

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

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

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

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

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

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

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

• 先认识这个业务配置
• 再看它接什么视频
• 再看它往哪里输出
• 最后才是少量高级参数

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

业务配置字段边界

应展示的核心字段

基础信息

• 业务配置名称
• 业务名称
• 站点名 site_name
• 通道名 name
• 通道显示名 display_name
• 通道号 channel_no

视频源

• 视频源地址 rtsp_url

输出流

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

业务配置级队列设置

• queue.size
• queue.strategy

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

放入高级设置的字段

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

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

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

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

不展示的字段

以下内容不应在业务配置编辑页直接展示：

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

页面结构

业务配置编辑页必须按“业务配置总体信息 + 视频通道列表 + 单通道编辑”组织，不再假设一个业务配置只有一个视频通道。

1. 业务配置总体信息

作用：定义当前业务配置文件自身的信息。

字段：

• 业务配置名称
• 业务名称
• 站点名
• 描述
• 业务配置级队列设置

表现要求：

• 默认放在页面顶部
• 信息密度要低，只保留业务配置级字段
• 不混入某一路视频通道的输入流、输出流或通道显示名

2. 视频通道列表

作用：让用户一眼看到当前业务配置中包含哪些视频通道。

每一行代表一路视频通道，例如：

• cam1
• cam2
• cam3
• cam4

列表默认展示字段：

• 通道名
• 显示名
• 输入 RTSP
• HLS 输出
• RTSP 输出
• 操作按钮

表现要求：

• 列表是多通道业务配置页面的核心区域
• 默认展示四路视频时不能显得拥挤
• 长地址使用等宽字体并允许截断
• 每行提供编辑和删除动作
• 页面提供新增通道入口

2.1 视频通道增删改查

业务配置页面必须支持视频通道级 CRUD，而不只是修改已有通道。

查询

视频通道列表就是查询入口，默认显示当前业务配置中的所有通道。

新增

页面提供 新增通道 按钮。

首版新增通道可以直接在页面中追加一个空编辑面板，不需要弹窗。

新增通道默认值：

• RTSP 输出端口：默认 8555
• 其他字段留空，由用户填写

底层 JSON 中仍然需要 instances[].template，但这是渲染系统需要的技术字段。UI 不把模板作为每个通道的可编辑字段展示，默认沿用当前业务配置第一条通道已有的模板，或者使用系统默认模板。

后续可以根据通道名自动建议 HLS 与 RTSP 输出路径，但首版不强制。

修改

每个通道都可以展开编辑，修改输入流、输出流和基础信息。

删除

删除不应立即从文件中移除，而是先标记为“待删除”。

标记删除后：

• 该通道仍显示在页面中
• 显示 撤销删除
• 点击保存后才真正从业务配置 JSON 中移除

这样可以避免误删一路视频配置。

复制

复制通道属于效率增强，不纳入首版必须完成范围。

3. 单通道编辑

作用：编辑某一路视频通道的具体参数。

推荐使用页面内展开面板或右侧抽屉，首版优先使用页面内展开面板，降低实现复杂度。

单通道编辑分组：

基础信息

• 通道名
• 显示名
• 通道号

输入流

• RTSP 输入地址

输出流

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

高级设置

• 当前通道中非主流程的 params
• 默认折叠

4. 原始 JSON

原始 JSON 继续保留为折叠技术区，不默认展开。

操作区设计

页面只保留 1 个核心动作：

1. 保存

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

保存

作用：

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

业务配置页面不再提供“生成预览”和“上传为候选配置”。

配置发布必须回到设备页或设备配置预览页完成，由那里统一选择配置模板、业务配置、配置叠加项和目标设备。

这样可以避免业务配置编辑页使用本地临时文件渲染配置，导致设备端 metadata 出现本地临时路径或上下文不一致。

与现有页面关系

配置资产总页

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

设备页

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

也就是说：

• “现在设备跑的是什么” 去设备页看
• “这个业务配置本身如何定义” 去配置资产页编辑
• “我要把某个业务配置发布到设备” 去设备控制页或配置预览页操作

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

数据结构改动

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

建议拆成两层：

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

2. 表单视图层
   提供页面渲染和提交时需要的业务配置级字段与多通道字段

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

提交流程

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

读取

1. 打开业务配置编辑页
2. 后台读取目标业务配置 JSON
3. 解析为包含多个视频通道的编辑表单模型

保存

1. 用户修改业务配置级字段或某个视频通道字段
2. 提交表单
3. 后台校验必填字段
4. 重建业务配置 JSON
5. 回写到 configs/profiles/<name>.json

校验规则

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

• 业务配置名称不能为空
• 每个通道名不能为空
• 每个通道的 RTSP 地址不能为空
• 每个通道的 RTSP 输出端口如果填写，必须是合法数字
• 同一个业务配置内的通道名不能重复
• 标记删除的通道不参与必填校验，也不会写回 JSON

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

错误处理

错误展示分三层：

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

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

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

测试策略

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

1. 多通道业务配置资产读取与表单映射测试
2. 多通道业务配置表单提交后的 JSON 重建测试
3. 多通道业务配置页面渲染测试
4. 现有设备配置预览/发布链路的回归测试

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

实施顺序

建议按下面顺序推进：

1. 补充业务配置编辑页设计文档
2. 后台数据结构改为多通道表单视图模型
3. 将业务配置编辑页改为“业务配置总体信息 + 视频通道列表 + 单通道编辑”
4. 增加视频通道新增能力
5. 增加视频通道标记删除与撤销删除能力
6. 接入多通道保存逻辑
7. 跑本地 UI 与服务测试
8. 再通过设备配置预览/发布页验证实际下发链路

结论

业务配置编辑页应成为“业务场景与视频通道定义”的权威编辑入口，而不是继续做成原始 JSON 的浏览页。

它的边界必须非常明确：

• 共享服务归模板
• 业务场景和视频通道归业务配置
• 设备身份和网络入口归设备资产
• 差异调优归配置叠加项

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