feat(usable): package gui-host validation snapshot

Co-Authored-By: Paperclip <noreply@paperclip.ing>

TUI_PRODUCT_REQUIREMENTS.md

@@ -0,0 +1,284 @@
+# dbtool-tui-v1 Product Requirements
+
+日期：2026-03-26  
+作者：Product Manager  
+对应 issue：`CMP-24`
+
+## 1. 文档目的
+
+这份文档定义 `dbtool-tui-v1` 的首版产品范围、用户流程、最小功能清单和验收标准，用于：
+
+- 让 CTO 可以继续拆工程 issue
+- 让 Frontend / Backend 对 TUI 边界保持一致
+- 让 QA 能建立独立于 CLI 的验收路径
+
+## 2. 当前真实状态
+
+截至 2026-03-26，仓库已经具备：
+
+- `apps/tui` 终端工作台 shell baseline
+- `crates/db-app` 作为 CLI / TUI 共享应用编排层
+- `TUI_BACKEND_CONTRACT.md`、`TUI_ACCEPTANCE_CHECKLIST.md`、`TUI_TEST_STRATEGY.md` 等配套文档
+
+当前 shell baseline 已验证：
+
+- 六区布局
+- 键盘焦点切换
+- 顶部视图切换
+- `Ready` / `Loading` / `Error` 基础状态
+- 小终端降级提示
+
+当前 shell baseline **尚不等于 TUI V1 完成**。它只是终端工作台壳层，不包含真实数据库工作流闭环。
+
+## 3. 目标用户
+
+### 主用户
+
+已经熟悉命令行、但希望在一个终端会话里连续完成 inspect / query / result 浏览的技术操作者：
+
+- 后端工程师
+- 数据工程师
+- QA 工程师
+- 技术支持 / 排障工程师
+
+### 与 CLI 用户的关系
+
+CLI 更适合：
+
+- 一次性命令执行
+- shell automation
+- CI / smoke / 脚本调用
+
+TUI 更适合：
+
+- 在同一终端会话中反复查看 schema、改 SQL、跑查询、读结果
+- 降低重复输入命令的成本
+- 提高排障和验证过程中的上下文连续性
+
+## 4. 产品问题定义
+
+CLI 已经验证了 `connect -> inspect -> query -> export` 的产品语义，但在高频排障场景下，操作者仍要不断重复：
+
+- 重输命令
+- 来回切换 schema / table 上下文
+- 重新打开 SQL 文件或复制 SQL
+- 在输出滚动中回看错误和结果
+
+`dbtool-tui-v1` 要解决的问题不是“替代桌面 GUI”，而是把已成立的 CLI 核心流程，升级成一个**键盘优先、上下文连续、仍然运行在终端里的单会话工作台**。
+
+## 5. 最重要的用户场景
+
+### 场景 A：排障查询
+
+后端或支持工程师需要在一个终端会话内快速定位异常数据：
+
+1. 选择一个已有连接目标
+2. 验证并激活当前连接
+3. 浏览 schema / table / column
+4. 把目标对象上下文带入 query editor
+5. 运行 SQL
+6. 在结果区和 inspector 中查看结果、空结果或错误
+7. 需要时导出结果
+
+### 场景 B：测试验证
+
+QA 工程师需要在终端里连续验证多个数据点：
+
+1. 切换到目标连接
+2. 通过 schema browser 定位对象
+3. 多次调整 SQL
+4. 查看结果是否符合预期
+5. 导出一份结果作为证据
+
+如果这些场景仍然要求用户频繁退回 CLI 重新拼命令，TUI V1 就没有成立。
+
+## 6. 核心用户流程
+
+`dbtool-tui-v1` 的首版主流程应是：
+
+`select target -> activate connection -> inspect objects -> edit query -> run query -> review result/error -> export`
+
+拆成界面动作：
+
+1. 在 `Connections` 中看到当前可切换目标
+2. 选择并激活一个连接目标
+3. 在 `Schema Browser` 中逐层浏览 schema / table / column
+4. 在 `Query Editor` 中编写或修改 SQL
+5. 触发执行
+6. 在 `Results` 中读取结果，在 `Inspector` / `Status & Activity` 中读取状态与错误
+7. 对当前结果集触发导出
+
+## 7. 首版范围
+
+### In Scope
+
+- 终端中的单会话数据库工作台
+- 单一活动连接上下文
+- 键盘驱动的连接选择与激活
+- live schema / table / column 浏览
+- 最小可用 query editor
+- live query 执行
+- 结果表格浏览
+- 空结果、执行中、执行失败、执行成功的明确反馈
+- 对当前结果集发起 export
+- 基于 `db-app` 的共享结果对象和错误对象
+
+### 最小功能范围清单
+
+- `Connections`
+  - 展示当前会话内可切换目标
+  - 明确当前激活目标
+  - 明确失败目标或不可用目标
+
+- `Schema Browser`
+  - 浏览 schema / table / column
+  - 反映当前激活连接上下文
+
+- `Query Editor`
+  - 至少支持查看、输入、编辑和再次执行 SQL
+  - 不要求完整 IDE 能力
+
+- `Results`
+  - 展示列头、结果行、空结果状态
+  - 对较长结果保持基本可读和可滚动
+
+- `Inspector / Status & Activity`
+  - 展示连接摘要
+  - 展示执行状态
+  - 展示错误摘要和恢复提示
+
+- `Export`
+  - 对当前结果集触发导出
+  - 明确格式、路径、成功或失败反馈
+
+## 8. 非目标
+
+以下内容不进入 `dbtool-tui-v1`：
+
+- Desktop GUI / Web GUI
+- 多连接并发在线工作区
+- 用户可见的持久化 profile 管理
+- 新建复杂连接配置中心
+- 多 query tab
+- query history 持久化
+- SQL autocomplete / formatter / explain plan
+- migration / schema editing
+- import
+- 权限 / 用户管理
+- backup / restore
+- dashboard、图表、BI 分析面板
+- AI 助手
+
+## 9. CLI、TUI、后续版本的边界
+
+### 应保留在共享 `db-app` / core 的
+
+- 连接测试
+- inspect 结构
+- query 请求与结果
+- export 请求与结果
+- 错误分类
+- 脱敏规则
+
+### 应保留在 CLI 的
+
+- 一次性脚本执行
+- shell automation
+- 原始 flags / file path 输入
+- 机器可组合的命令式入口
+
+### 应进入 TUI V1 的
+
+- 单会话连接切换
+- 面板化 inspect / query / result 浏览
+- 错误与状态的持续可见反馈
+- 对当前结果的交互式导出动作
+
+### 留到后续版本的
+
+- 持久化连接管理
+- 多标签页工作流
+- 高级 SQL 编辑器能力
+- 更复杂的历史、搜索和协作能力
+
+## 10. 验收标准
+
+### 全局验收
+
+- TUI V1 必须仍然复用 CLI 已验证的产品语义，而不是重造一套数据库行为
+- TUI V1 必须是键盘优先的完整终端路径，不依赖鼠标
+- TUI V1 必须有独立于 CLI 的验收和回归路径
+- TUI V1 不能被误写成桌面 GUI 或完整数据库管理平台
+
+### 连接工作流验收
+
+当以下条件成立时，连接流程可接受：
+
+- 用户可以看到当前会话中可选的连接目标
+- 用户可以激活一个目标并得到明确成功 / 失败状态
+- 当前激活连接在 `Connections`、`Inspector`、`Status & Activity` 中保持一致
+- 失败连接不会只闪现一次错误，而是持续显示可读问题
+
+### Schema Browser 验收
+
+当以下条件成立时，schema 浏览流程可接受：
+
+- 激活连接后，用户可以浏览 schema 或等价顶层对象
+- 用户可以进一步浏览 table / view 和 column
+- 当前浏览结果与激活连接上下文一致
+- 空 schema / 空表路径给出明确反馈，而不是空白区域
+
+### Query 验收
+
+当以下条件成立时，query 流程可接受：
+
+- 用户可以在 editor 中编写或修改 SQL
+- 用户可以触发执行并看到执行中状态
+- 成功、有结果、空结果、失败这四类结果可以一眼区分
+- 失败时错误摘要在 `Inspector` 或 `Status & Activity` 保持可见
+- TUI 不要求首版拥有高级编辑器能力，但必须保证基本输入和重复执行顺畅
+
+### Results 验收
+
+当以下条件成立时，结果浏览可接受：
+
+- 结果区域能展示列头和结果行
+- 空结果不会被误判成执行失败
+- 结果较长时仍有基本浏览能力
+- 当前结果与最近一次成功执行保持一致
+
+### Export 验收
+
+当以下条件成立时，导出流程可接受：
+
+- 用户可以从当前结果集触发导出
+- 用户能明确知道导出格式和输出路径
+- 导出成功和失败有清晰反馈
+- 导出失败不会伪装成成功
+
+## 11. 成功标准
+
+`dbtool-tui-v1` 在产品上可以视为首版成立，当且仅当：
+
+- 用户能在一个终端会话里完成连接切换、schema 浏览、query 执行、结果查看和导出
+- Frontend、Backend、QA 对 TUI 范围没有歧义
+- TUI 明确复用 `db-app` 契约，而不是解析 CLI 文本
+- CLI、TUI、GUI 的边界没有被混淆
+- QA 可以独立建立 TUI 验收矩阵，而不是借用 CLI 通过来替代 TUI 通过
+
+## 12. 给 CTO 的交接说明
+
+当前 PM 决策是：
+
+- `dbtool-tui-v1` 的目标不是 shell baseline 本身，而是“单会话终端数据库工作台”
+- 当前必须优先围绕真实连接、schema、query、results、export 五段流程收口
+- 不应把持久化连接管理、多标签页和高级编辑器能力塞进首版
+- `db-app` 是 TUI 的唯一共享执行入口，不应绕过
+
+CTO 后续拆解应围绕：
+
+- 连接激活路径
+- schema browser 接入
+- query / results / export 接入
+- 错误与状态一致性
+- QA 回归闭环