yinjianm
0e01153157
新增快捷指令跨标签组拖拽能力，支持将未标记命令直接拖入 目标标签组，并修正 manual/name/last_used 排序按钮状态映射 将状态监控内存与网络卡片的响应式阈值统一收紧到 250px， 同时用可悬浮查看最近采样点的 canvas 历史图替换网络趋势线
198 lines
10 KiB
Markdown
198 lines
10 KiB
Markdown
# 变更提案: quickcommands-cross-group-drag-move
|
|
|
|
## 元信息
|
|
```yaml
|
|
类型: 新功能
|
|
方案类型: implementation
|
|
优先级: P1
|
|
状态: 已完成
|
|
创建: 2026-04-19
|
|
完成: 2026-04-19
|
|
```
|
|
|
|
---
|
|
|
|
## 1. 需求
|
|
|
|
### 背景
|
|
快捷指令视图已经支持分组拖拽排序、组内命令拖拽排序和扁平列表拖拽排序，但当前命令拖放逻辑仍然把拖拽限制在“同一分组内”。这会导致用户虽然能整理每个分组内部的顺序，却不能把命令从一个标签组直接拖到另一个标签组，也不能把“未标记”命令直接拖进目标标签组，和 Workbench 中“拖到目标容器即完成归类”的直觉交互不一致。
|
|
|
|
### 目标
|
|
- 让已标记分组中的命令可以拖到另一个已标记分组内，并在落点位置插入。
|
|
- 让“未标记”分组中的命令可以直接拖到已标记分组内，并自动添加目标标签。
|
|
- 跨分组移动后移除原分组标签，只保留目标分组与其它未受影响的既有标签。
|
|
- 修正快捷指令排序按钮在 `manual / name / last_used` 三种模式下的文案和图标映射。
|
|
|
|
### 约束条件
|
|
```yaml
|
|
时间约束: 本轮完成前端实现、构建验证与知识库同步
|
|
性能约束: 不新增依赖，继续使用现有原生 drag/drop 与 store action
|
|
兼容性约束: 优先复用现有后端增量标签同步与重排接口，不新增后端路由
|
|
业务约束: 搜索过滤态仍禁止拖拽排序；本轮暂不支持把已标记命令拖入“未标记”分组
|
|
```
|
|
|
|
### 验收标准
|
|
- [ ] 开启标签分组时，把命令从标签 A 拖到标签 B 后，命令会移除标签 A、加入标签 B，并插入到标签 B 的目标位置。
|
|
- [ ] 开启标签分组时，把“未标记”命令拖到标签 B 后，命令会新增标签 B，并插入到标签 B 的目标位置。
|
|
- [ ] 当前轮次不支持把已标记命令拖入“未标记”分组，界面会给出非阻断提示而不是错误修改标签。
|
|
- [ ] 排序按钮能正确反映 `manual / name / last_used` 三种模式的标题与图标。
|
|
- [ ] `npm run build --workspace @nexus-terminal/backend` 与 `npm run build --workspace @nexus-terminal/frontend` 通过。
|
|
|
|
---
|
|
|
|
## 2. 方案
|
|
|
|
### 技术方案
|
|
本次改动只调整前端编排，继续复用已落地的快捷指令更新与顺序持久化能力，不新增后端接口。
|
|
|
|
第一步，在 `QuickCommandsView.vue` 放开命令拖放目标的“同组限制”，并补一个支持“源项不在目标列表中时插入”的列表工具函数。这样拖拽命中目标组后，既能处理原来的组内重排，也能处理跨组插入。
|
|
|
|
第二步，在命令 drop 分支中区分三类路径：同组重排继续沿用现有 `reorderCommandsInTag` / `reorderQuickCommands`；“未标记 -> 已标记”与“已标记 A -> 已标记 B”则先通过 `updateQuickCommand(...)` 更新标签集合，再按目标组当前列表调用 `reorderCommandsInTag(targetTagId, ...)` 固定落点顺序。
|
|
|
|
第三步，保留“拖到未标记分组”禁用策略。因为本轮已确认的业务语义是“移除原标签并加入目标标签”，而未标记分组没有可加入的标签，若开放该动作就会变成“删除标签”或“清空所有标签”，和当前确认范围冲突，所以只给用户提示，不执行实际写入。
|
|
|
|
最后顺手修正排序按钮在 `manual` 模式下的标题与图标，让拖拽完成后切回 `manual` 时，控件状态与实际排序一致。
|
|
|
|
### 影响范围
|
|
```yaml
|
|
涉及模块:
|
|
- frontend: QuickCommandsView 需要实现跨分组拖放与 manual 排序按钮修正
|
|
- knowledge-base: 需要同步 frontend/backend 模块文档与 CHANGELOG
|
|
预计变更文件: 5-7
|
|
```
|
|
|
|
### 风险评估
|
|
| 风险 | 等级 | 应对 |
|
|
|------|------|------|
|
|
| 跨组移动先改标签、再改目标组顺序，中间刷新可能导致落点顺序丢失 | 中 | 在标签更新完成后立刻基于刷新后的目标组列表再次提交 `reorderCommandsInTag` |
|
|
| 目标是“未标记”分组时语义不清，可能被误实现为清空全部标签 | 高 | 明确禁止该路径，仅提示用户本轮不支持 |
|
|
| 多标签命令跨组移动时若直接覆盖 tagIds，可能误删其他标签 | 中 | 基于原 `tagIds` 做“移除 sourceTagId、加入 targetTagId”的增量计算 |
|
|
| `manual` 排序按钮状态未修正，用户会误判当前排序模式 | 低 | 同步补齐 `sortButtonTitle` 和 `sortButtonIcon` 的三态映射 |
|
|
|
|
---
|
|
|
|
## 3. 技术设计
|
|
|
|
### 架构设计
|
|
```mermaid
|
|
flowchart LR
|
|
A[QuickCommandsView drop] --> B{是否跨分组}
|
|
B -->|否| C[现有组内重排]
|
|
B -->|是| D[updateQuickCommand 同步 tagIds]
|
|
D --> E[reorderCommandsInTag 固定目标组落点]
|
|
E --> F[(现有 reorder / association API)]
|
|
```
|
|
|
|
### API设计
|
|
#### PUT /api/v1/quick-commands/:id
|
|
- **请求**:
|
|
```json
|
|
{
|
|
"name": "Deploy",
|
|
"command": "npm run deploy",
|
|
"tagIds": [5, 9]
|
|
}
|
|
```
|
|
- **响应**:
|
|
```json
|
|
{
|
|
"message": "快捷指令已更新"
|
|
}
|
|
```
|
|
|
|
#### PUT /api/v1/quick-commands/reorder-by-tag
|
|
- **请求**:
|
|
```json
|
|
{
|
|
"tagId": 9,
|
|
"commandIds": [12, 7, 19]
|
|
}
|
|
```
|
|
- **响应**:
|
|
```json
|
|
{
|
|
"message": "标签内快捷指令顺序已更新"
|
|
}
|
|
```
|
|
|
|
### 数据模型
|
|
| 字段 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| `QuickCommandFE.tagIds` | `number[]` | 命令当前绑定的标签集合，跨组移动时按“移除源标签 + 加入目标标签”增量计算 |
|
|
| `QuickCommandFE.tagOrders` | `Record<number, number>` | 命令在各标签组中的局部顺序，更新标签后通过目标组重排接口重新固定 |
|
|
| `GroupedQuickCommands.commands` | `QuickCommandFE[]` | 分组视图当前命令列表，跨组插入后用于计算目标顺序 |
|
|
| `QuickCommandSortByType` | `'manual' | 'name' | 'usage_count' | 'last_used'` | 排序按钮需要正确反映其中实际启用的三种前端模式 |
|
|
|
|
---
|
|
|
|
## 4. 核心场景
|
|
|
|
### 场景: 已标记命令拖到另一个已标记分组
|
|
**模块**: frontend
|
|
**条件**: 用户开启快捷指令标签分组，当前不处于搜索过滤状态。
|
|
**行为**: 用户把标签 A 中的命令拖到标签 B 的某个命令上，前端先移除标签 A、加入标签 B，再按落点重排标签 B。
|
|
**结果**: 命令从标签 A 消失，出现在标签 B 的目标位置，刷新后保持一致。
|
|
|
|
### 场景: 未标记命令拖到已标记分组
|
|
**模块**: frontend
|
|
**条件**: 用户开启快捷指令标签分组，存在“未标记”分组且当前不处于搜索过滤状态。
|
|
**行为**: 用户把“未标记”命令拖到某个标签组内，前端为命令新增目标标签，并在目标组内固定插入顺序。
|
|
**结果**: 命令离开“未标记”分组，进入目标标签组。
|
|
|
|
### 场景: 已标记命令拖到未标记分组
|
|
**模块**: frontend
|
|
**条件**: 用户尝试把某个标签组中的命令拖到“未标记”分组。
|
|
**行为**: 前端识别为当前轮次未支持的路径，只给出提示，不提交更新请求。
|
|
**结果**: 原有标签关系保持不变，避免误清空标签。
|
|
|
|
---
|
|
|
|
## 5. 技术决策
|
|
|
|
### quickcommands-cross-group-drag-move#D001: 优先复用现有更新与重排接口，而不是新增“跨组移动”专用后端接口
|
|
**日期**: 2026-04-19
|
|
**状态**: 已采纳
|
|
**背景**: 现有后端已经提供 `updateQuickCommand`、`reorder-by-tag` 和增量标签关联同步能力，理论上足以表达“移除原标签、加入目标标签、固定目标组顺序”。
|
|
**选项分析**:
|
|
| 选项 | 优点 | 缺点 |
|
|
|------|------|------|
|
|
| A: 新增后端 `move-between-tags` 专用接口 | 前端调用简单，语义集中 | 需要新增 controller/service/repository 路径，改动面更大 |
|
|
| B: 复用现有更新命令 + 标签内重排接口 | 后端零新增接口，改动集中在前端编排 | 前端需要串联两步请求 |
|
|
**决策**: 选择方案 B
|
|
**理由**: 当前用户确认的是交互增强，不是后端能力缺失。复用现有接口可以最小代价完成需求，并降低本轮回归面。
|
|
**影响**: frontend
|
|
|
|
### quickcommands-cross-group-drag-move#D002: 本轮禁止“已标记 -> 未标记”拖放
|
|
**日期**: 2026-04-19
|
|
**状态**: 已采纳
|
|
**背景**: 已确认的业务语义是“拖到目标分组后，移除原分组标签并加入目标分组标签”。未标记分组没有可加入的标签，因此该路径语义不完整。
|
|
**选项分析**:
|
|
| 选项 | 优点 | 缺点 |
|
|
|------|------|------|
|
|
| A: 拖入未标记时清空全部标签 | 交互看起来完整 | 会把“移动分组”变成“清空标签”，风险高且和当前确认不一致 |
|
|
| B: 拖入未标记时只移除源标签 | 语义比清空全部标签更保守 | 对多标签命令仍不清晰，用户难以预期 |
|
|
| C: 本轮禁用该路径，只提示用户 | 范围清晰，不引入隐式删除语义 | 功能覆盖面少一步 |
|
|
**决策**: 选择方案 C
|
|
**理由**: 当前需求边界已经确认到“加入目标标签”，而未标记不具备该条件。禁用比猜测性实现更安全。
|
|
**影响**: frontend
|
|
|
|
---
|
|
|
|
## 6. 成果设计
|
|
|
|
### 设计方向
|
|
- **美学基调**: 延续现有快捷指令工作台的深色工具面板风格，不做视觉重设计，只强化“卡片可以被移入另一组”的操作感。
|
|
- **记忆点**: 命令卡片在跨组拖放时仍使用现有虚线高亮占位，用户可以直接感知落点是在目标组内部而不是只做选中。
|
|
- **参考**: 复用当前 `QuickCommandsView.vue` 中已存在的组内拖拽高亮和手动排序交互。
|
|
|
|
### 视觉要素
|
|
- **配色**: 继续沿用主题变量和当前 `qc-drop-target` 虚线反馈，不新增独立拖拽色板。
|
|
- **字体**: 沿用现有标题和命令 monospace 体系，不调整文本层级。
|
|
- **布局**: 保持现有分组头和命令卡结构，仅扩展拖放命中逻辑与排序按钮状态表达。
|
|
- **动效**: 继续使用现有 hover / 拖放过渡，不增加额外动画。
|
|
- **氛围**: 保持克制、偏工程控制台的交互表达，让跨组归类像“拖入目标容器”一样直接。
|
|
|
|
### 技术约束
|
|
- **可访问性**: 不能破坏现有单击选中、双击执行、右键菜单和键盘选择逻辑。
|
|
- **响应式**: 继续兼容紧凑模式与 Workbench 窄栏布局，不增加额外结构占位。
|