292 lines
9.3 KiB
Markdown
292 lines
9.3 KiB
Markdown
# dbtool-cli-v1 Future Desktop GUI Foundation
|
||
|
||
日期：2026-03-25
|
||
作者：Senior Frontend Engineer
|
||
对应 issue：`CMP-9`
|
||
|
||
## 1. 当前前端基线评估
|
||
|
||
### 真实现状
|
||
|
||
- 当前仓库没有前端入口，也没有任何展示层基础。
|
||
- 当前不存在 `package.json`、React 工程、桌面壳、页面路由、组件目录或样式系统。
|
||
- 当前项目仍以 CLI V1 为主路径，GUI 只允许做未来方向基线，不进入本期交付主链路。
|
||
|
||
### 结论
|
||
|
||
- GUI 第一轮最合理的交付形态应是“信息架构 + 组件边界 + 契约清单 + 静态原型”。
|
||
- 不应在本 issue 中直接引入 Electron、Tauri、React 或完整桌面工程。
|
||
- 后续 GUI 项目启动时，推荐使用 React + shadcn/ui + Tailwind CSS，并以本文件作为产品层输入。
|
||
|
||
## 2. 首版 UI/UX 范围建议
|
||
|
||
首版未来桌面端 GUI 建议仅覆盖一个高价值工作台，而不是多页面堆叠：
|
||
|
||
1. **Connection Manager**
|
||
- 展示已保存连接、最近连接、驱动类型与连接健康状态
|
||
- 支持新建连接、测试连接、进入工作台
|
||
2. **Database Workspace**
|
||
- 左侧 schema browser
|
||
- 中间 query editor + execution toolbar
|
||
- 下方 results / history / export 分页区
|
||
- 右侧 inspector 展示连接、对象和执行详情
|
||
3. **Execution Feedback**
|
||
- 展示执行中、成功、失败、空结果、已导出等状态
|
||
4. **Export Flow**
|
||
- 选择格式、目标路径、覆盖提醒、导出结果提示
|
||
|
||
### 当前刻意不做
|
||
|
||
- dashboard 首页
|
||
- 图表和 BI 视图
|
||
- AI 助手面板
|
||
- migration / schema editing
|
||
- 多窗口复杂工作流
|
||
|
||
## 3. 信息架构
|
||
|
||
```text
|
||
Desktop GUI
|
||
├─ Connection Manager
|
||
│ ├─ Saved Connections
|
||
│ ├─ New Connection
|
||
│ └─ Test / Open Workspace
|
||
└─ Workspace
|
||
├─ Schema Browser
|
||
│ ├─ Schemas
|
||
│ ├─ Tables / Views
|
||
│ └─ Columns
|
||
├─ Query Workbench
|
||
│ ├─ Query Tabs
|
||
│ ├─ Execution Toolbar
|
||
│ └─ SQL Editor
|
||
├─ Result Region
|
||
│ ├─ Results Table
|
||
│ ├─ Query History
|
||
│ └─ Export Status
|
||
└─ Inspector
|
||
├─ Connection Summary
|
||
├─ Object Metadata
|
||
└─ Execution Detail / Error
|
||
```
|
||
|
||
## 4. 主工作区布局方向
|
||
|
||
### Layout Principle
|
||
|
||
- 使用“三栏 + 底部结果区”的桌面工作台布局。
|
||
- 结构重于装饰，让 schema、SQL、结果和状态成为主视觉主体。
|
||
- 避免通用 SaaS 卡片拼贴，不引入噪音型 dashboard 模块。
|
||
|
||
### 推荐布局
|
||
|
||
```text
|
||
┌────────────────────────────────────────────────────────────────────┐
|
||
│ App Header / Connection Switcher / Global Actions │
|
||
├──────────────┬─────────────────────────────────────┬───────────────┤
|
||
│ Schema Tree │ Query Toolbar + SQL Editor │ Inspector │
|
||
│ │ │ │
|
||
│ │ │ │
|
||
├──────────────┴─────────────────────────────────────┴───────────────┤
|
||
│ Results / History / Export / Problems │
|
||
└────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 区域职责
|
||
|
||
- **Header**：连接切换、当前数据库上下文、主题、全局命令
|
||
- **Schema Tree**：浏览 schema / table / view / column，支持搜索和展开
|
||
- **Workbench**：SQL 编写、运行、停止、格式切换、目标连接展示
|
||
- **Inspector**：对象详情、执行摘要、错误详情、导出选项
|
||
- **Bottom Panel**：结果表格、历史、导出日志、问题列表
|
||
|
||
## 5. 页面与状态设计
|
||
|
||
### Connection Manager
|
||
|
||
- 主要目标：尽快进入一个明确的工作区
|
||
- 关键状态：
|
||
- 无连接
|
||
- 测试连接中
|
||
- 测试连接成功
|
||
- 测试连接失败
|
||
- 驱动不支持 / 配置不完整
|
||
|
||
### Workspace
|
||
|
||
- 主要目标：围绕单一连接完成 inspect → query → export
|
||
- 关键状态：
|
||
- 尚未选择对象
|
||
- schema 载入中
|
||
- SQL 执行中
|
||
- 查询成功且有结果
|
||
- 查询成功但空结果
|
||
- 查询失败
|
||
- 导出成功 / 导出失败
|
||
|
||
## 6. 组件清单
|
||
|
||
以下为后续 React + shadcn/ui 落地建议组件边界：
|
||
|
||
| 组件 | 作用 | 建议基础 |
|
||
| --- | --- | --- |
|
||
| `AppShell` | 承载桌面工作台骨架 | `ResizablePanelGroup`, `Separator` |
|
||
| `ConnectionSwitcher` | 切换当前连接和工作区入口 | `Popover`, `Command`, `Select` |
|
||
| `ConnectionCard` | 展示连接摘要与状态 | `Card`, `Badge`, `Button` |
|
||
| `SchemaTree` | 浏览 schema / table / column | `ScrollArea`, `Collapsible`, `Input` |
|
||
| `QueryToolbar` | 运行、停止、导出、当前连接状态 | `Button`, `Badge`, `Tooltip` |
|
||
| `QueryTabs` | 管理多个 SQL 标签 | `Tabs`, `ContextMenu` |
|
||
| `SqlEditorPanel` | 容纳 SQL 编辑器 | 自定义容器，后续接入编辑器 |
|
||
| `ResultTabs` | 在结果、历史、导出间切换 | `Tabs` |
|
||
| `ResultsTable` | 呈现查询结果集 | `Table`, `ScrollArea` |
|
||
| `ExecutionBanner` | 一眼可见的执行状态与错误摘要 | `Alert`, `Badge` |
|
||
| `InspectorPanel` | 展示对象属性和执行详情 | `Sheet` 或固定侧栏容器 |
|
||
| `ExportDrawer` | 处理导出参数与确认 | `Dialog` / `Sheet` / `Form` |
|
||
|
||
## 7. 与 shadcn/ui + Tailwind + impeccable 的对齐说明
|
||
|
||
### 视觉基线
|
||
|
||
- 以稳定中性色为主，不使用高饱和主视觉。
|
||
- 强调结构、对齐、排版和间距，而不是装饰性卡片。
|
||
- light / dark 都应保持低噪音层次和稳定对比度。
|
||
|
||
### 交互基线
|
||
|
||
- 键盘优先：连接切换、schema 搜索、执行操作、底部面板切换应支持快捷路径。
|
||
- 错误优先可读：错误摘要直接进入可见区，不藏在 toast 里。
|
||
- 信息密度优先：结果、状态和元数据必须同时可读，避免只做“大留白”。
|
||
|
||
### 不应出现的方向
|
||
|
||
- 营销站式英雄区
|
||
- 强发光深色主题
|
||
- 以卡片拼贴为主的 dashboard 首页
|
||
- 视觉噪音很高的渐变、阴影、发光描边
|
||
|
||
## 8. 未来 GUI 需要的核心数据契约
|
||
|
||
桌面 GUI 不应重新定义产品对象，而应直接映射 CLI 已明确概念。
|
||
|
||
### 连接与上下文
|
||
|
||
- `ConnectionTarget`
|
||
- `id`
|
||
- `name`
|
||
- `databaseKind`
|
||
- `environmentLabel`
|
||
- `status`
|
||
- `lastValidatedAt`
|
||
|
||
### schema browser
|
||
|
||
- `CatalogNode`
|
||
- `id`
|
||
- `kind` (`schema` / `table` / `view` / `column`)
|
||
- `name`
|
||
- `parentId`
|
||
- `isExpandable`
|
||
- `metadata`
|
||
|
||
### 查询执行
|
||
|
||
- `QueryRequest`
|
||
- `connectionId`
|
||
- `sql`
|
||
- `source` (`inline` / `file`)
|
||
- `limitMode`
|
||
|
||
- `QueryExecutionState`
|
||
- `status` (`idle` / `running` / `success` / `error`)
|
||
- `startedAt`
|
||
- `finishedAt`
|
||
- `durationMs`
|
||
- `rowCount`
|
||
- `message`
|
||
|
||
### 结果与导出
|
||
|
||
- `ResultSet`
|
||
- `columns`
|
||
- `rows`
|
||
- `rowCount`
|
||
- `truncated`
|
||
|
||
- `ExportRequest`
|
||
- `connectionId`
|
||
- `queryText`
|
||
- `format` (`csv` / `json`)
|
||
- `outputPath`
|
||
- `overwrite`
|
||
|
||
- `ExportResult`
|
||
- `status`
|
||
- `outputPath`
|
||
- `exportedRows`
|
||
- `message`
|
||
|
||
## 9. 后端契约提前识别
|
||
|
||
未来 GUI 项目启动前，建议 CTO / Backend 先固定以下输出形态：
|
||
|
||
1. schema introspection 返回结构是否可直接树化
|
||
2. query 返回结构是否区分“空结果成功”和“执行失败”
|
||
3. export 是否返回可复用的结果对象和错误对象
|
||
4. 连接测试结果是否提供统一状态码和展示文案
|
||
5. 错误对象是否包含用户可展示摘要与底层细节
|
||
|
||
若这些结构过度 CLI-only，后续 GUI 会被迫做适配层补丁。
|
||
|
||
## 10. 最小可见界面实现
|
||
|
||
本次已提供静态原型：
|
||
|
||
- `gui/prototype/index.html`
|
||
- `gui/prototype/styles.css`
|
||
- `gui/prototype/app.js`
|
||
|
||
该原型的作用是验证：
|
||
|
||
- 工作台结构是否稳定
|
||
- 连接管理与执行反馈是否易懂
|
||
- schema browser、query editor、results table、inspector 是否形成合理分区
|
||
|
||
该原型不是正式桌面应用，也不接真实数据源。
|
||
|
||
## 11. 运行方式
|
||
|
||
### 直接打开
|
||
|
||
浏览器打开 `gui/prototype/index.html`。
|
||
|
||
### 本地预览
|
||
|
||
```bash
|
||
node gui/preview-server.mjs
|
||
```
|
||
|
||
访问 `http://127.0.0.1:4173`。
|
||
|
||
## 12. 界面验收说明
|
||
|
||
QA / CTO / PM 可按以下标准验收本次产物：
|
||
|
||
1. 明确确认当前项目“尚无前端基线”这一事实是否被准确记录
|
||
2. 评估信息架构是否完整覆盖 connection manager、schema browser、query editor、results table、export flow
|
||
3. 评估布局是否体现高信息密度桌面工作台，而非通用后台模板
|
||
4. 评估组件清单是否足够拆分后续 GUI 子任务
|
||
5. 评估契约清单是否能指导 backend 提前稳定输出结构
|
||
|
||
## 13. 建议的后续 GUI 项目拆分
|
||
|
||
后续若单独立项 GUI，可按以下顺序拆 issue：
|
||
|
||
1. GUI shell 与设计 token 基线
|
||
2. Connection Manager
|
||
3. Schema Browser
|
||
4. Query Workbench
|
||
5. Results Table 与状态系统
|
||
6. Export Flow
|
||
7. 错误与问题面板
|
||
8. 快捷键与可用性细化
|