diff --git a/docs/superpowers/specs/2026-04-19-device-batch-operations-design.md b/docs/superpowers/specs/2026-04-19-device-batch-operations-design.md new file mode 100644 index 0000000..f6d1803 --- /dev/null +++ b/docs/superpowers/specs/2026-04-19-device-batch-operations-design.md @@ -0,0 +1,298 @@ +# 设备页批量操作设计方案 + +## 目标 + +在新的后台信息架构下,为多设备统一运维提供一个清晰、低干扰、可追踪的入口。 + +这次设计不新增一级导航,不再引入新的独立“批量操作页面”,而是把多设备统一操作收纳到 `设备` 模块内部,作为设备总览页的一种工作模式。 + +设计目标有三条: + +1. 让用户在设备总览页就能完成常见的多设备统一操作 +2. 不破坏当前已经收敛好的四个一级模块结构 +3. 保证“发起操作”和“查看执行结果”仍然职责分离 + +## 为什么不放进主菜单 + +多设备统一操作当然重要,但它不是一个独立业务域。 + +它本质上仍然属于“设备运维动作”,只是作用对象从一台设备变成多台设备。如果把它单独提成一级菜单,会立刻带来两个问题: + +- 主菜单又开始按“动作类型”膨胀,而不是按“业务对象”组织 +- 用户会在“设备”“批量操作”“操作审计”之间反复跳转,心智重新变乱 + +因此,这个能力不应该进入主菜单。 + +最合理的位置,是把它作为 `设备总览` 页中的批量工作模式:先看设备,再选设备,再执行统一操作。 + +## 入口定位 + +入口放在 `设备` 页主列表上方,以“按需浮现”的方式出现。 + +默认状态下: + +- 设备总览保持简洁 +- 不显示任何批量操作条 +- 用户只看到设备状态和单设备快捷入口 + +当用户勾选 1 台或多台设备后: + +- 页面顶部出现批量操作条 +- 操作条显示已选设备数量 +- 只展示当前阶段最重要的批量动作 + +这种模式的核心价值是: + +- 不勾选时,页面完全是总览页 +- 勾选后,页面自然切换到“批量运维模式” +- 入口不冗余,也不会占据主导航资源 + +## 页面结构 + +`设备` 页继续保持现有主结构: + +1. 顶部摘要区 +2. 设备列表 + +在此基础上,加入一个新的中间层: + +3. 批量操作条 + +最终结构如下: + +1. 顶部摘要区 + 用于整体状态判断和快速筛选 + +2. 批量操作条 + 仅在用户选择设备后出现 + +3. 设备列表 + 负责设备选择、状态查看、进入单设备详情和控制页 + +这样可以保证页面仍然只回答一个核心问题: +“当前有哪些设备,我要不要对其中几台一起做操作” + +## 批量操作条设计 + +批量操作条应该是一条紧凑、稳定、图标优先的操作带,而不是新的大页面。 + +它至少包含以下元素: + +- 已选设备数量 +- 清空选择 +- 服务操作组 +- 配置操作组 +- 发起后查看任务结果的入口 + +### 服务操作组 + +第一版只放最常用、风险最可控的统一操作: + +- 启动服务 +- 重启服务 +- 停止服务 +- 重载服务 + +这些动作直接对应 agent 已有的多设备任务能力,概念清楚,用户也容易理解。 + +### 配置操作组 + +配置相关动作也放在这条操作带里,但第一版要严格收边界,不把它做成复杂的发布系统。 + +第一版建议只支持: + +- 统一下发候选配置 +- 统一应用候选配置 +- 统一回滚到上一份配置 + +这里的“统一下发候选配置”不是让用户在设备总览页直接编辑大段 JSON,而是进入一个轻量的批量配置面板,在里面完成配置选择与确认。 + +## 批量配置面板 + +从设备总览页点击“统一下发候选配置”后,打开批量配置面板。 + +这个面板不是一级页面,也不是长期停留的工作区,它更适合作为抽屉或模态层,承接一次明确的配置发布动作。 + +面板只回答三个问题: + +1. 要发给哪些设备 +2. 这次配置从哪里来 +3. 是否立即创建任务 + +### 第一版支持的配置来源 + +为了和当前的模板化配置体系保持一致,第一版只允许以下来源: + +- 选择模板 +- 选择 profile +- 选择一个或多个 overlay + +必要时允许展示生成后的配置摘要,但不在这个面板里默认展开完整 JSON。 + +### 面板默认展示内容 + +默认只显示运维真正需要确认的摘要: + +- 目标设备数量 +- 目标设备名称列表摘要 +- 模板名 +- profile 名 +- overlay 列表 +- 生成后的 `config_id` +- 生成后的 `config_version` +- 配置摘要 SHA + +### 面板收纳规则 + +以下内容不在主视图大面积展开: + +- 完整 JSON +- 原始文件路径 +- 渲染细节 +- 原始响应体 + +这些内容如果要看,应进入折叠区或技术详情抽屉。 + +## 结果呈现与职责分离 + +批量操作发起后,不在设备总览页里展开每台设备的完整执行日志。 + +职责划分必须明确: + +- `设备` 页负责发起批量动作 +- `操作审计` 负责查看任务执行过程和结果 + +因此,批量操作后的结果呈现只分两层: + +### 第一层:设备页即时反馈 + +用户发起操作后,设备页顶部给出简洁反馈: + +- 任务已创建 +- 任务类型 +- 目标设备数 +- 当前任务状态摘要 + +并提供一个明确入口进入任务详情或操作审计页。 + +### 第二层:审计页详细结果 + +详细结果统一在任务详情页或操作审计页中查看,包括: + +- 每台设备是否执行成功 +- 调用了哪个 agent 接口 +- 返回了什么结果 +- 哪台设备失败 +- 失败原因是什么 + +这样可以避免总览页被“执行细节”淹没。 + +## 与现有能力接口的关系 + +这次设计建立在当前已经存在的多设备任务能力之上,不需要重新发明一套后端模型。 + +当前能力层已具备的统一操作包括: + +- `media_start` +- `media_restart` +- `media_stop` +- `reload` +- `rollback` +- `config_apply` + +因此这次实现重点不是重写任务系统,而是把这些能力纳入新的主线 UI: + +- 让批量服务操作成为设备页的正式入口 +- 让批量配置下发有明确的配置选择面板 +- 让任务结果自然落到操作审计中 + +## 状态与可用性规则 + +批量操作必须遵守一套简单、稳定的可用性规则,避免页面显得“什么都能点”。 + +### 设备选择规则 + +- 未选择设备时,不显示批量操作条 +- 只选择 1 台设备时,也允许使用批量操作条,但视觉上不强调“批量”,避免用户困惑 +- 选择多台设备时,明确显示“已选 N 台” + +### 动作可用性规则 + +- 服务类动作始终可见,但在无设备选中时不显示 +- 配置“应用候选配置”和“回滚到上一份配置”允许直接发起 +- “统一下发候选配置”必须先完成配置选择与确认 + +### 反馈规则 + +- 任务创建成功后,立即给出任务摘要 +- 任务创建失败时,给出简洁错误,不直接把原始技术响应堆在主页面 +- 技术细节进入折叠区或审计页 + +## 不做的事情 + +为了控制范围,第一版明确不做下面这些内容: + +- 不新增一级菜单“批量操作” +- 不做独立的“大屏式任务调度中心” +- 不在设备总览页直接编辑完整 JSON +- 不在设备总览页展示每台设备的详细执行日志 +- 不在第一版中加入复杂的发布审批、分批灰度、自动回滚策略 + +这些都可能以后再做,但不属于当前最短路径。 + +## 实现边界 + +这次实现建议分两步: + +### 第一步:设备页批量服务操作正式化 + +包括: + +- 设备列表支持稳定多选 +- 出现批量操作条 +- 接入统一的服务操作任务创建 +- 操作后跳到任务详情或审计入口 + +### 第二步:批量配置下发正式化 + +包括: + +- 新增批量配置面板 +- 以模板 + profile + overlay 生成配置摘要 +- 创建 `config_apply` 任务 +- 在任务视图中查看各设备结果 + +这样能先把最稳的能力做出来,再接配置下发,不会把第一版拖得过大。 + +## 验证方式 + +本设计的验证分为两类: + +### 本地验证 + +- `设备` 页在未选择设备时保持干净 +- 选择设备后出现批量操作条 +- 批量服务操作能成功创建任务 +- 批量配置面板能正确展示模板 / profile / overlay 摘要 +- 成功和失败反馈不会在总览页造成信息堆积 + +### 运行侧验证 + +需要在真实 agent 环境下确认: + +- 多设备服务操作是否按预期逐台执行 +- 批量配置下发到不同设备时是否正确到达 agent +- 任务结果与审计记录是否一致 +- UI 摘要是否能正确反映各设备执行状态 + +## 最终结论 + +多设备统一操作应该是 `设备` 页里的批量工作模式,而不是主菜单一级页面。 + +这条设计路径有三个优点: + +1. 不破坏已经稳定下来的四个一级模块 +2. 让用户的操作路径保持自然:看设备、选设备、做操作 +3. 保证总览、操作、审计三者边界清楚,不再到处重复显示类似信息 + +这也是当前最符合本项目规模和运维目标的方案。