paperclip/dbtool-cli-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a28dab4cd9f7a21dd0d537f65335bea71ea567fd
dbtool-cli-v1/TUI_PRODUCT_REQUIREMENTS.md
Paperclip CTO a28dab4cd9
Some checks failed
release-smoke / macos-13 / x86_64-apple-darwin (push) Has been cancelled
Details
release-smoke / ubuntu-latest / x86_64-unknown-linux-gnu (push) Has been cancelled
Details
release-smoke / windows-latest / x86_64-pc-windows-msvc (push) Has been cancelled
Details
feat(usable): package gui-host validation snapshot 
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-03-31 10:21:36 +00:00

8.3 KiB
Raw Blame History

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