94 lines
4.4 KiB
Markdown
94 lines
4.4 KiB
Markdown
# GUI Foundation Artifacts
|
||
|
||
本目录用于存放 `CMP-9` 的未来桌面端 GUI 基线产物，而不是正式应用代码。
|
||
|
||
## 当前基线结论
|
||
|
||
- 当前仓库仍然没有正式 Web / Desktop 前端工程入口：没有 `package.json`、React 应用、Electron / Tauri 壳。
|
||
- 当前已经存在最小展示层基础：`gui/prototype` 静态工作台原型、`gui/preview-server.mjs` 本地预览服务，以及 `apps/tui` 的终端工作台壳层。
|
||
- 因此，当前前端可见面不再是“完全空白”，但仍属于 foundation 级别，不进入 CLI V1 产品范围。
|
||
|
||
## 首版 UI/UX 范围建议
|
||
|
||
当前最合理的首版未来 GUI 范围是单一数据库工作台，而不是多页面 dashboard：
|
||
|
||
- **Connection Manager**：展示已保存连接、驱动类型、环境标签、连接健康状态，并支持测试连接和进入工作台
|
||
- **Database Workspace**：固定为 schema browser、query editor、results/history/export 底部区域、右侧 inspector 的工作台布局
|
||
- **Execution Feedback**：明确区分 `Running`、`Success`、`Empty`、`Error`、`Exported`，且执行反馈持续留在工作区内
|
||
- **Export Flow**：围绕当前结果集提供格式选择、目标路径、覆盖提醒和导出结果反馈
|
||
|
||
当前刻意不做：
|
||
|
||
- 正式 React / Electron / Tauri 工程
|
||
- 真实数据库接入或后端契约改造
|
||
- dashboard 首页、图表 BI、AI 助手、migration / schema editing
|
||
|
||
## 当前产物
|
||
|
||
- `desktop-foundation.md`：信息架构、布局方向、组件清单、契约要求和 UI/UX 建议
|
||
- `prototype/index.html`：最小可见工作台原型
|
||
- `prototype/styles.css`：原型样式
|
||
- `prototype/app.js`：原型内交互与状态切换
|
||
- `preview-server.mjs`：零依赖本地预览服务
|
||
|
||
## 原型包含内容
|
||
|
||
- 连接管理、schema browser、query editor、results、export、inspector 的稳定工作台分区
|
||
- 明确的 `connect -> inspect -> query -> export` 引导式评审轨道
|
||
- 按连接切换不同的 schema catalog、SQL 草稿标签、结果列和默认导出路径
|
||
- `Running` / `Success` / `Empty` / `Error` / `Exported` 五种可预览执行态
|
||
- Light / Dark 主题切换
|
||
- schema 搜索过滤、连接切换、结果 / 历史 / 导出 / 问题面板切换
|
||
- 当前界面状态到共享结构化契约的映射预览，其中 `running` 明确标记为前端暂态
|
||
- 键盘快捷路径：`C` / `I` / `Q` / `E`、`1` / `2` / `3` / `4` / `5`、`R`、`T`、`/`、`⌘/Ctrl+K`
|
||
|
||
## 查看方式
|
||
|
||
### 方式一：直接打开
|
||
|
||
直接用浏览器打开 `gui/index.html`。
|
||
|
||
若希望直接进入工作台原型，也可以打开 `gui/prototype/index.html`。
|
||
|
||
### 方式二：启动本地预览
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
node gui/preview-server.mjs
|
||
```
|
||
|
||
然后访问：
|
||
|
||
```text
|
||
http://127.0.0.1:4173
|
||
```
|
||
|
||
当前 `/` 会落到 `gui/index.html`，再从入口页进入工作台原型。
|
||
|
||
## 建议评审路径
|
||
|
||
推荐按以下顺序评审：
|
||
|
||
1. 用 `C` 或顶部 workflow strip 查看 `Connect`，确认目标卡片、健康态和工作区摘要
|
||
2. 用 `I` 查看 `Inspect`，确认 schema tree、selection 和 inspector 同步
|
||
3. 用 `Q` 查看 `Query`，确认 SQL 草稿、执行 banner 和结果区处于同一上下文
|
||
4. 用 `R`、`1`–`5` 或 `⌘/Ctrl+K` 预览不同执行态
|
||
5. 用 `E` 查看 `Export`，确认默认路径、empty guidance 与 blocked export 行为
|
||
|
||
## 界面验收
|
||
|
||
验收人应重点确认：
|
||
|
||
1. 是否能看出连接概览、工作区上下文、执行反馈三层信息同时存在
|
||
2. 工作台布局是否保持“操作台”气质，而不是卡片拼贴式 dashboard
|
||
3. 成功、空结果、失败、导出完成四种状态是否都能一眼区分
|
||
4. `Running` 态是否能在不离开工作区的前提下持续显示执行反馈，并暂时锁定导出动作
|
||
5. 切换连接后，顶部摘要、中部工作区和右侧 inspector 是否同步更新
|
||
6. 切换连接后，schema tree、query tab 标签、结果列与默认导出路径是否也同步切换到对应驱动上下文
|
||
7. Light / Dark 两种主题下信息密度、对比度和可读性是否仍然稳定
|
||
8. 顶部 workflow strip 和 `C` / `I` / `Q` / `E` 是否能帮助 QA 明确当前正在评审哪一步主流程
|
||
9. `⌘/Ctrl+K` 快捷操作面板是否能帮助 QA 快速预览状态与连接切换
|
||
10. 文档中的后端契约需求是否仍可映射到 CLI 已定义产品概念
|
||
11. `Contract` 面板是否能帮助 QA 与 Backend 快速核对 `query` / `export` envelope，以及 `running` 暂态边界
|