Add profile editor design spec
This commit is contained in:
parent
d772882ba3
commit
02733c39a2
341
docs/superpowers/specs/2026-04-20-profile-editor-design.md
Normal file
341
docs/superpowers/specs/2026-04-20-profile-editor-design.md
Normal file
@ -0,0 +1,341 @@
|
||||
# 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
|
||||
|
||||
只有这样，后续“设备命名、视频源、输出流、候选配置下发”这条主线才会真正清晰，后台的配置管理也才不会重新退回到信息混杂、入口重复的状态。
|
||||
Loading…
Reference in New Issue
Block a user