# 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 回归闭环