dbtool-cli-v1/gui/desktop-foundation.md

dbtool-cli-v1 Future Desktop GUI Foundation

日期：2026-03-25
作者：Senior Frontend Engineer
对应 issue：CMP-9

1. 当前前端基线评估

真实现状

• 当前仓库没有正式前端工程入口：不存在 package.json、React 工程、桌面壳、页面路由、组件目录或样式系统。
• 当前仓库已经存在展示层 foundation：gui/prototype 静态工作台原型、gui/preview-server.mjs 本地预览服务，以及 apps/tui 的终端工作台壳层。
• 当前项目仍以 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. 信息架构

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 模块。

推荐布局

┌────────────────────────────────────────────────────────────────────┐
│ 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 是否形成合理分区
• success / empty / error / exported 等关键状态是否能被明确区分
• 当前界面状态是否仍能映射回共享 query / export 契约，且 running 被识别为前端暂态
• light / dark 主题下的结构层次是否保持稳定

该原型不是正式桌面应用，也不接真实数据源。

11. 运行方式

直接打开

浏览器打开 gui/prototype/index.html。

本地预览

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. 快捷键与可用性细化