3588AdminBackend/docs/superpowers/specs/2026-04-19-device-batch-operations-design.md

设备页批量操作设计方案

目标

在新的后台信息架构下，为多设备统一运维提供一个清晰、低干扰、可追踪的入口。

这次设计不新增一级导航，不再引入新的独立“批量操作页面”，而是把多设备统一操作收纳到 设备 模块内部，作为设备总览页的一种工作模式。

设计目标有三条：

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. 保证总览、操作、审计三者边界清楚，不再到处重复显示类似信息

这也是当前最符合本项目规模和运维目标的方案。