chore: bootstrap independent git workflow
Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Paperclip CTO
291
gui/desktop-foundation.md
Normal file
291
gui/desktop-foundation.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# 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. 快捷键与可用性细化
|
||||
Reference in New Issue
Block a user