重构(前端): 持久化快速命令排序和密码切换
添加持久化排序字段并重新排序快速命令和标签的端点，更新前端以支持手动拖放排序，并为连接和凭据表单添加密码可见性切换。此外，将 SSH 连接测试作为连接列表中的默认操作，并刷新相关模块文档和更改日志。
This commit is contained in:
yinjianm
@@ -0,0 +1,208 @@
|
||||
# 变更提案: quickcommands-drag-reorder
|
||||
|
||||
## 元信息
|
||||
```yaml
|
||||
类型: 新功能
|
||||
方案类型: implementation
|
||||
优先级: P1
|
||||
状态: 已完成
|
||||
创建: 2026-04-19
|
||||
完成: 2026-04-19
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. 需求
|
||||
|
||||
### 背景
|
||||
当前快捷指令视图已经支持按标签分组、按名称或最近使用时间浏览命令，并提供双击执行、右键菜单、动态变量与标签编辑等能力，但分组顺序仍然按标签名派生，组内命令顺序也只能依赖计算排序，用户无法把高频分组和常用命令固定在自己习惯的位置。随着工作台内快捷指令数量增加，这会降低定位效率，也和连接树等区域正在逐步支持拖拽重排的交互方向不一致。
|
||||
|
||||
### 目标
|
||||
- 让快捷指令分组支持拖动排序，并在刷新后保持自定义顺序。
|
||||
- 让快捷指令支持在分组内拖动排序，并在刷新后保持自定义顺序。
|
||||
- 让关闭标签分组后的扁平列表同样支持拖动排序。
|
||||
- 在一条命令可绑定多个标签的前提下，明确全局顺序和标签内顺序的持久化语义。
|
||||
|
||||
### 约束条件
|
||||
```yaml
|
||||
时间约束: 本轮完成前后端联动实现与基础构建验证
|
||||
性能约束: 不新增依赖，复用仓库已有的 vuedraggable
|
||||
兼容性约束: 需要兼容现有 SQLite 数据库，通过 migration 为历史数据补齐顺序字段
|
||||
业务约束: 搜索过滤结果不参与拖拽重排，避免只对局部可见子集排序造成顺序污染
|
||||
```
|
||||
|
||||
### 验收标准
|
||||
- [ ] 开启标签分组时，已标记分组支持拖动排序，刷新页面后顺序保持不变。
|
||||
- [ ] 开启标签分组时，组内命令支持拖动排序，刷新页面后顺序保持不变。
|
||||
- [ ] 关闭标签分组时，扁平命令列表支持拖动排序，刷新页面后顺序保持不变。
|
||||
- [ ] 多标签命令在不同标签组内可拥有各自的组内顺序，不因编辑命令或补标签而丢失既有顺序。
|
||||
- [ ] `packages/backend` 与 `packages/frontend` 的构建验证通过。
|
||||
|
||||
---
|
||||
|
||||
## 2. 方案
|
||||
|
||||
### 技术方案
|
||||
本次改动分三层落地。
|
||||
|
||||
第一层是数据层，为 `quick_commands`、`quick_command_tags` 与 `quick_command_tag_associations` 三张表分别新增 `sort_order` 字段，并通过 migration 为历史数据回填稳定初始顺序。命令表顺序用于扁平列表与“未标记”分组，标签表顺序用于分组顺序，关联表顺序用于“命令在某个标签组中的局部位置”。
|
||||
|
||||
第二层是接口层，在现有快捷指令与快捷指令标签业务域中新增三个重排接口: 标签重排、全局命令重排、标签内命令重排。同时改造现有标签关联写入逻辑，避免编辑命令时通过“先删后插”破坏已有组内顺序。
|
||||
|
||||
第三层是前端交互层，在 `QuickCommandsView.vue` 中接入拖拽句柄和持久化回写逻辑，并把命令排序模式扩展为 `manual`、`name`、`last_used`。用户完成拖拽后自动切回 `manual` 模式，确保拖拽结果可以立即可见且稳定保留。
|
||||
|
||||
### 影响范围
|
||||
```yaml
|
||||
涉及模块:
|
||||
- backend: quick-commands / quick-command-tags / database migration 需要新增顺序字段与重排接口
|
||||
- frontend: quickCommands.store / quickCommandTags.store / QuickCommandsView 需要支持手动顺序与拖拽持久化
|
||||
- knowledge-base: 需要同步 frontend/backend 模块文档与 CHANGELOG
|
||||
预计变更文件: 10-14
|
||||
```
|
||||
|
||||
### 风险评估
|
||||
| 风险 | 等级 | 应对 |
|
||||
|------|------|------|
|
||||
| 多标签命令在多个分组中复用，若仍把组内顺序放在命令表会产生语义冲突 | 高 | 将“标签内顺序”存储到关联表，命令表只承载全局顺序 |
|
||||
| 历史数据库没有顺序字段，直接读取会导致老数据顺序混乱 | 中 | 通过 migration 补字段并按现有主键或 rowid 回填初始顺序 |
|
||||
| 搜索过滤结果下拖拽会导致只重排局部子集，用户感知混乱 | 中 | 搜索态禁用拖拽，只允许在完整列表状态下重排 |
|
||||
| 编辑命令标签时若继续删除并重建关联，会丢失既有组内顺序 | 中 | 改为增量同步标签关联，保留未移除标签的原顺序 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 技术设计
|
||||
|
||||
### 架构设计
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[QuickCommandsView drag end] --> B[quickCommandsStore / quickCommandTagsStore]
|
||||
B --> C[reorder APIs]
|
||||
C --> D[service]
|
||||
D --> E[repository]
|
||||
E --> F[(SQLite sort_order fields)]
|
||||
```
|
||||
|
||||
### API设计
|
||||
#### PUT /api/v1/quick-command-tags/reorder
|
||||
- **请求**:
|
||||
```json
|
||||
{
|
||||
"tagIds": [3, 1, 5]
|
||||
}
|
||||
```
|
||||
- **响应**:
|
||||
```json
|
||||
{
|
||||
"message": "快捷指令标签顺序已更新"
|
||||
}
|
||||
```
|
||||
|
||||
#### PUT /api/v1/quick-commands/reorder
|
||||
- **请求**:
|
||||
```json
|
||||
{
|
||||
"commandIds": [11, 7, 9, 2]
|
||||
}
|
||||
```
|
||||
- **响应**:
|
||||
```json
|
||||
{
|
||||
"message": "快捷指令顺序已更新"
|
||||
}
|
||||
```
|
||||
|
||||
#### PUT /api/v1/quick-commands/reorder-by-tag
|
||||
- **请求**:
|
||||
```json
|
||||
{
|
||||
"tagId": 3,
|
||||
"commandIds": [7, 11, 9]
|
||||
}
|
||||
```
|
||||
- **响应**:
|
||||
```json
|
||||
{
|
||||
"message": "标签内快捷指令顺序已更新"
|
||||
}
|
||||
```
|
||||
|
||||
### 数据模型
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `quick_commands.sort_order` | `INTEGER` | 快捷指令的全局手动顺序，供扁平视图与未标记分组使用 |
|
||||
| `quick_command_tags.sort_order` | `INTEGER` | 快捷指令分组的手动顺序 |
|
||||
| `quick_command_tag_associations.sort_order` | `INTEGER` | 某条命令在某个标签分组内的手动顺序 |
|
||||
| `QuickCommandWithTags.tagOrders` | `Record<number, number>` | 返回给前端的“标签 ID -> 组内顺序”映射 |
|
||||
| `QuickCommandSortByType` | `'manual' | 'name' | 'usage_count' | 'last_used'` | 前端命令列表排序模式 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 核心场景
|
||||
|
||||
### 场景: 调整分组顺序
|
||||
**模块**: frontend / backend
|
||||
**条件**: 用户开启快捷指令标签展示，且当前不处于搜索过滤状态。
|
||||
**行为**: 用户拖动某个已标记分组的标题句柄，前端更新本地拖拽列表并调用标签重排接口。
|
||||
**结果**: 分组按用户定义的顺序显示，刷新后保持一致，“未标记”分组继续固定在已标记分组之后。
|
||||
|
||||
### 场景: 调整标签组内命令顺序
|
||||
**模块**: frontend / backend
|
||||
**条件**: 用户在某个标签分组内拖动命令项，且当前不处于搜索过滤状态。
|
||||
**行为**: 前端将该分组内的命令 ID 顺序提交到标签内重排接口，并自动切换到手动排序模式。
|
||||
**结果**: 当前分组内的命令顺序立即更新，后续刷新后仍保持该顺序，不影响其它标签组的局部顺序。
|
||||
|
||||
### 场景: 调整扁平命令顺序
|
||||
**模块**: frontend / backend
|
||||
**条件**: 用户关闭“显示快捷指令标签”设置后浏览扁平列表。
|
||||
**行为**: 用户拖动命令项，前端提交全局命令重排接口。
|
||||
**结果**: 扁平列表与“未标记”分组的手动顺序保持一致，仍可切换回名称或最近使用排序查看其它视图。
|
||||
|
||||
---
|
||||
|
||||
## 5. 技术决策
|
||||
|
||||
### quickcommands-drag-reorder#D001: 将“标签内命令顺序”存储在关联表，而不是 quick_commands 主表
|
||||
**日期**: 2026-04-19
|
||||
**状态**: 已采纳
|
||||
**背景**: 一条快捷指令可以绑定多个标签，因此同一条命令可能同时出现在多个分组中。如果组内顺序只存到 `quick_commands` 主表，就无法表达“同一条命令在 A 组和 B 组中的位置不同”。
|
||||
**选项分析**:
|
||||
| 选项 | 优点 | 缺点 |
|
||||
|------|------|------|
|
||||
| A: 仅在 `quick_commands` 存一个 `sort_order` | 结构简单，接口少 | 无法支持多标签命令在不同分组中的不同顺序 |
|
||||
| B: 在 `quick_command_tag_associations` 存组内 `sort_order`，命令表保留全局 `sort_order` | 语义完整，能兼容分组视图与扁平视图 | 实现比单表排序稍复杂，需要额外重排接口 |
|
||||
**决策**: 选择方案 B
|
||||
**理由**: 这是唯一能同时满足“分组内可排序”和“命令可绑定多个标签”两项约束的方案，同时仍能通过命令表上的全局顺序支持扁平视图。
|
||||
**影响**: backend, frontend
|
||||
|
||||
### quickcommands-drag-reorder#D002: 保留现有名称与最近使用排序，同时新增手动排序模式承接拖拽结果
|
||||
**日期**: 2026-04-19
|
||||
**状态**: 已采纳
|
||||
**背景**: 现有快捷指令视图已经有按名称与最近使用查看命令的需求，直接移除会造成回归；但拖拽排序又必须有一个稳定的“手动顺序”视图承接。
|
||||
**选项分析**:
|
||||
| 选项 | 优点 | 缺点 |
|
||||
|------|------|------|
|
||||
| A: 用拖拽排序完全替代名称和最近使用排序 | 交互简单 | 会删除已有浏览方式，造成功能回退 |
|
||||
| B: 增加 `manual` 模式，并在拖拽完成后自动切换到该模式 | 兼容现有浏览模式，同时让拖拽结果立即可见 | 排序状态管理略复杂 |
|
||||
**决策**: 选择方案 B
|
||||
**理由**: 能在不删除现有排序入口的前提下，为拖拽排序提供明确而可持久化的展示模式。
|
||||
**影响**: frontend
|
||||
|
||||
---
|
||||
|
||||
## 6. 成果设计
|
||||
|
||||
### 设计方向
|
||||
- **美学基调**: 延续现有工作台深色工具面板风格，在不改变整体布局语言的前提下，加入轻量的“可拖动”信号，让快捷指令列表更像可编排控制台而不是静态目录。
|
||||
- **记忆点**: 分组标题和命令行都带有低干扰的拖拽句柄，拖动时保持现有卡片与高亮体系，仅在当前位置给出明确占位反馈。
|
||||
- **参考**: 当前 `QuickCommandsView.vue` 的工作台卡片样式，以及连接树拖拽占位反馈的交互方向。
|
||||
|
||||
### 视觉要素
|
||||
- **配色**: 继续复用现有主题变量与 hover/highlight 色，不新增独立色板，只让拖拽句柄在 hover 与拖拽时增强对比。
|
||||
- **字体**: 沿用当前工作台文本和命令 monospace 字体体系，避免因交互增强引入新的字体层级。
|
||||
- **布局**: 不改动现有控制栏、分组头和命令项的主体结构，仅在左侧插入窄句柄区域，并在拖拽态显示占位边框。
|
||||
- **动效**: 复用 `vuedraggable` 的位移动画与现有过渡时间，保证拖放反馈清晰但不过度跳动。
|
||||
- **氛围**: 保持克制、专业的终端工作台气质，把“可重排”表达为操作强化，而不是视觉重设计。
|
||||
|
||||
### 技术约束
|
||||
- **可访问性**: 拖拽增强不能破坏现有单击选中、双击执行、键盘 `Enter` 执行与右键菜单入口。
|
||||
- **响应式**: 继续兼容现有紧凑模式与工作台不同宽度场景，句柄区域不能挤占命令文本的主要可读空间。
|
||||
Reference in New Issue
Block a user