# 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 的稳定工作台分区
- 按连接切换不同的 schema catalog、SQL 草稿标签、结果列和默认导出路径
- `Running` / `Success` / `Empty` / `Error` / `Exported` 五种可预览执行态
- Light / Dark 主题切换
- schema 搜索过滤、连接切换、结果 / 历史 / 导出 / 问题面板切换
- 当前界面状态到共享结构化契约的映射预览，其中 `running` 明确标记为前端暂态
- 键盘快捷路径：`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. 是否能看出连接概览、工作区上下文、执行反馈三层信息同时存在
2. 工作台布局是否保持“操作台”气质，而不是卡片拼贴式 dashboard
3. 成功、空结果、失败、导出完成四种状态是否都能一眼区分
4. `Running` 态是否能在不离开工作区的前提下持续显示执行反馈，并暂时锁定导出动作
5. 切换连接后，顶部摘要、中部工作区和右侧 inspector 是否同步更新
6. 切换连接后，schema tree、query tab 标签、结果列与默认导出路径是否也同步切换到对应驱动上下文
7. Light / Dark 两种主题下信息密度、对比度和可读性是否仍然稳定
8. `⌘/Ctrl+K` 快捷操作面板是否能帮助 QA 快速预览状态与连接切换
9. 文档中的后端契约需求是否仍可映射到 CLI 已定义产品概念
10. `Contract` 面板是否能帮助 QA 与 Backend 快速核对 `query` / `export` envelope，以及 `running` 暂态边界