# 变更提案: admin-frontend-node-status-filter-batch-delete

## 元信息
```yaml
类型: 功能增强
方案类型: implementation
优先级: P1
状态: 待执行
创建: 2026-04-25
```

---

## 1. 需求

### 背景
`admin-frontend` 的 `#/nodes` 已具备关键词搜索、类型 / 权限组 / 父子节点筛选、跨分页勾选与批量修改能力，但当前还缺少“按在线 / 离线状态快速筛选”的运营入口，也没有针对已勾选节点的批量删除动作。用户希望继续沿用 Apple 化后台工作台结构，在节点管理页补齐这两个高频运营动作。

### 目标
- 在节点管理页工具条补充“在线节点 / 离线节点”状态筛选。
- 按本轮确认口径，仅把显式“离线”节点纳入“离线节点”筛选；`待同步 / 已停用` 不归入离线筛选结果。
- 为已勾选节点补齐批量删除入口，并接通真实 `server/manage/batchDelete` 后端链路。

### 约束条件
```yaml
范围约束: 本轮只增强节点管理页筛选与批量操作，不扩展新的节点详情、状态面板或更多批量动作
技术约束: 继续使用 Vue3 + TypeScript + Element Plus，不新增第三方依赖
视觉约束: 保持当前“黑色 hero + 白色工作台 + 低噪音工具条”Apple 风格后台基线，不引入厚重危险卡片或额外弹窗层级
业务约束: 在线 / 离线判定继续以后端 `available_status` 与现有 `getNodeStatusMeta()` 为真相源；批量删除使用现成 `server/manage/batchDelete`
确认约束: “离线节点”仅筛 `getNodeStatusMeta().dotClass === 'offline'` 的节点，`pending / disabled` 继续只出现在“全部节点”
```

### 验收标准
- [ ] 节点页工具条新增状态筛选，并支持“全部节点 / 在线节点 / 离线节点”切换。
- [ ] “离线节点”筛选结果只包含显式离线节点，不包含 `待同步 / 已停用`。
- [ ] 已勾选节点时可触发批量删除，并在确认后真实调用 `server/manage/batchDelete`。
- [ ] 批量删除成功后会清空勾选、刷新列表，并给出明确成功 / 失败反馈。
- [ ] 节点页文案、提示与底部说明同步覆盖新增筛选和批量删除能力。
- [ ] `admin-frontend` 执行 `npm run build` 通过。

---

## 2. 方案

### 页面结构
1. 工具条在现有“类型 / 权限组 / 节点关系”筛选之后新增“状态”筛选，下拉项固定为“全部节点 / 在线节点 / 离线节点”。
2. 批量删除不额外引入新弹窗入口层级，而是与现有“批量修改”一起留在节点工作台主操作流中，只在已勾选节点时启用。
3. 选择摘要条继续承担“当前已勾选多少节点”的上下文提示，并补充危险操作入口，避免在无勾选态暴露无效删除动作。

### 前端实现策略
1. 在 `src/utils/nodes.ts` 中新增状态筛选类型与过滤逻辑，保持节点状态口径统一由工具层维护。
2. 在 `src/api/admin.ts` 中新增 `batchDeleteNodes()`，统一封装 `server/manage/batchDelete`。
3. 在 `src/views/nodes/NodesView.vue` 中：
   - 新增状态筛选状态与 `hasActiveFilters` 判断
   - 将状态筛选接入 `filterNodes()`
   - 增加批量删除确认、提交、清空勾选与刷新流程
   - 同步更新 hero 文案、工具条按钮与选择摘要区
4. 尽量维持现有样式骨架，只做最小 UI 增量，避免破坏节点页当前 Apple 化后台节奏。

### 风险评估
| 风险 | 等级 | 应对 |
|------|------|------|
| “离线”语义与 `待同步 / 已停用` 容易混淆 | 中 | 过滤逻辑只认 `offline` dotClass，并在方案与实现中固定该口径 |
| 批量删除属于不可恢复操作，误触风险较高 | 高 | 仅在已勾选节点时启用，并在提交前二次确认删除数量与不可恢复性 |
| 跨分页勾选后删除可能留下过期选中状态 | 中 | 删除成功后统一 `clearSelection()` 并重载节点数据，避免残留选中 ID |

---

## 3. 技术决策

### admin-frontend-node-status-filter-batch-delete#D001: 离线筛选只匹配显式 offline 状态
**日期**: 2026-04-25
**状态**: ✅采纳
**背景**: 用户已在评估阶段明确选择“离线节点不包含待同步/已停用”。
**决策**: `statusFilter='offline'` 时仅保留 `getNodeStatusMeta(node).dotClass === 'offline'` 的节点。
**理由**: 能保持离线筛选语义清晰，避免把待同步或停用节点混入故障排查视图。

### admin-frontend-node-status-filter-batch-delete#D002: 批量删除复用主工作台选择摘要，不新增独立批量操作弹窗
**日期**: 2026-04-25
**状态**: ✅采纳
**背景**: 当前节点工作台已具备跨分页勾选与选择摘要区，用户只要求补齐批量删除，不要求重做批量操作体系。
**决策**: 批量删除入口放在现有勾选摘要区 / 工具条动作流中，通过确认框完成最后确认。
**理由**: 改动最小、上下文最清晰，也更符合 Apple 风格后台“主表格内完成高频动作”的设计基线。
