From 02733c39a2a4a407d3089c5066199f3d72f6922b Mon Sep 17 00:00:00 2001
From: tian <11429339@qq.com>
Date: Mon, 20 Apr 2026 12:44:22 +0800
Subject: [PATCH] Add profile editor design spec

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

diff --git a/docs/superpowers/specs/2026-04-20-profile-editor-design.md b/docs/superpowers/specs/2026-04-20-profile-editor-design.md
new file mode 100644
index 0000000..2ad5301
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-20-profile-editor-design.md
@@ -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
+
+只有这样，后续“设备命名、视频源、输出流、候选配置下发”这条主线才会真正清晰，后台的配置管理也才不会重新退回到信息混杂、入口重复的状态。