dbtool-cli-v1/apps/tui

dbtool-tui Shell

apps/tui 提供 dbtool-tui-v1 的终端工作台实现。

当前范围

当前实现包含：

• 独立 dbtool-tui 应用入口
• 稳定的六区工作台布局
• 顶部视图切换与底部快捷键提示
• 连接管理列表、当前连接上下文和失败连接可视化区分
• 键盘驱动的连接切换工作流，以及连接 loading / success / failure 可视状态
• sqlite-local 的真实 connect / inspect 路径，schema browser 可展示 live schema / table / column
• sqlite-local 的真实 query / results / export 工作流，直接复用 crates/db-app
• PostgreSQL / MySQL 的 Docker demo live activation / query / export 路径
• 查询草稿切换、基础键入编辑、执行触发与执行状态反馈
• 成功 / 空结果 / 错误三类查询结果展示，以及宽表列分页提示
• 当前结果集导出到 /tmp 的 CSV / JSON 反馈
• 面板焦点管理
• 列表选择与基础键盘导航
• Ready / Loading / Error 三种基础界面状态
• 终端尺寸过小的显式降级提示

当前不包含：

• 多连接并发会话
• 自定义新增 / 编辑连接表单
• 非 demo 自定义 network profile
• 完整 SQL 编辑器能力

usable-v1 口径边界

当前 TUI 能力要按三层结论理解，避免把局部 live path 误记为整体通过：

层级	当前结论	含义
shell baseline	pass	六区布局、焦点、状态、TTY 启动与退出可直接复核
sqlite-local local live	partial	单机会话内可复核 connect / inspect / query / export，但只覆盖本地 SQLite
PostgreSQL / MySQL network live	pass	当前 runner 可通过 host.docker.internal、Docker demo 容器与 TTY smoke 脚本复核真实激活、查询、导出

• sqlite-local 仍是最轻量的本地单机验证入口，但不再是唯一 live 路径。
• 当前 usable-v1 的 runner 内 network live 回放口径已经建立，可直接复核 PostgreSQL / MySQL。
• QA 在对外汇报时，应明确写成“shell baseline = pass、sqlite-local = partial、PostgreSQL/MySQL network live = pass（demo path）”。

运行方式

在项目根目录执行：

cargo run -p dbtool-tui

当前默认 live 路径是 sqlite-local，底层使用 examples/tmp/dbtool-demo.sqlite。 启动后会自动对 sqlite-local 执行 connect + inspect；切换连接时会重新触发 live activation。 内置 reporting-postgres / orders-mysql profile 默认走 host.docker.internal:55432/53306，并分别复用 dbtool_demo / qa_demo demo 数据。

如果当前 runner 缺少 Rust 工具链，可先使用已有产物：

./target/debug/dbtool-tui

TTY smoke 契约

• dbtool-tui 需要交互式 TTY；正常终端启动与自动化 smoke 都必须走 TTY 路径。
• 当前最小可重复入口：

scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui

• PostgreSQL live smoke：

export DBTOOL_PASSWORD=dbtool
scripts/tui/live-network-smoke.sh postgres ./target/debug/dbtool-tui

• MySQL live smoke：

export DBTOOL_PASSWORD=dbtool
scripts/tui/live-network-smoke.sh mysql ./target/debug/dbtool-tui

• 小终端降级入口：

scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui 20 90 /tmp/dbtool-tui-small.log

• ./target/debug/dbtool-tui --help 不是有效 smoke；当前它只用于确认“非 TTY 会被明确拒绝”这一限制。
• 共享 runbook 见 TUI_SMOKE_RUNBOOK.md。

键盘交互

• Tab / Shift+Tab：切换焦点面板
• ← / → 或 1 / 2 / 3：切换顶部视图
• ↑ / ↓：移动连接、schema/object 或结果行选择
• Enter：在 Connections 焦点下激活所选连接；在 Schema Browser 焦点下展开 / 折叠 schema 或确认对象；在 Query Editor 焦点下执行当前查询
• i：在 Query Editor 中进入基础插入模式
• x：将当前结果集导出为 CSV 到 /tmp
• j：将当前结果集导出为 JSON 到 /tmp
• [ / ]：在 Query Editor 中切换查询草稿；在 Results 中横向翻页宽表列
• r：清空当前 query / export 反馈，回到 Ready
• Esc：回到默认工作台
• q：退出

状态恢复与键位一致性

• Esc 在两个场景下都承担“回到稳定态”的职责：编辑模式下先退回 navigate mode；普通导航下回到默认 Workspace + Query Editor 焦点。
• r 是唯一的显式恢复键：会同时清空 query 结果、query 错误、export 成功/失败反馈，并把界面状态收口回 Ready。
• [ / ] 只在两个焦点区生效：Query Editor 下切换草稿，Results 下横向翻页；其他面板按下不会触发隐藏状态变化。
• x / j 只在当前工作区已有“成功且可导出”的结果集时成立；若查询仍在运行或当前没有可导出结果，会保留明确错误/提示，而不是静默失败。
• Enter 的语义由当前焦点决定：Connections = 激活连接，Schema Browser = 展开/确认对象，Query Editor = 执行查询；插入模式下 Enter 只插入换行。

快速测试路径

如果你只是想快速走通一遍当前可见工作流，推荐按下面步骤操作：

1. 启动 cargo run -p dbtool-tui
2. 等待默认连接 sqlite-local 从 Loading 变成可用状态
3. 按 Tab 把焦点切到 Schema Browser
4. 用 ↑ / ↓ 选择 main.accounts 或 main.tickets
5. 按 Tab 切到 Query Editor
6. 先不要按 i，直接按 [ / ] 切换草稿
7. 选中 account_ticket_summary.sql 后按 Enter，确认成功结果
8. 切到 empty_recent_tickets.sql 后按 Enter，确认空结果
9. 切到 bad_syntax.sql 后按 Enter，确认错误结果持续留在工作区
10. 切到 ticket_export_preview.sql 后按 Enter，成功后按 x 或 j，确认导出反馈和 /tmp 路径

常见困惑

• Inserted a newline. Press Esc, then Enter to run.：表示你已经按了 i 进入编辑模式，然后按了 Enter；这时 Enter 不会执行查询，而是插入换行。按 Esc 退出编辑模式后，再按 Enter 才是执行查询。
• 当前不能自定义输入数据库连接：这是当前范围外能力。当前 TUI 只提供内置的 sqlite-local、Postgres、MySQL 示例连接，用于验证工作台流程和状态反馈。
• 如果觉得界面文字偏多：本轮已先做一轮 Help / Status / Connections 文案收敛；当前版本仍偏向 QA / 契约验证界面，后续再继续收敛文案。

界面验收

QA 可按以下步骤复核：

1. 启动后能看到 Connections、Schema Browser、Query Editor、Results、Inspector、Status & Activity 六个区域
2. 默认活动连接应为 sqlite-local，且 Connections 列表中能区分当前连接、可选连接和失败连接
3. 使用 2 进入 Connections 视图后，可用 ↑ / ↓ 移动连接选择
4. 在 Connections 焦点下按 Enter 激活失败连接时，Status & Activity 与 Inspector 会持续显示可读错误，而不是只给瞬时提示
5. 启动后或回到 sqlite-local 后，连接状态会先进入 Loading，随后在 Schema Browser 焦点下可浏览 main.accounts 和 main.tickets
6. 选中对象后，Results 会展示列定义，Inspector 会展示当前 schema / object / column 上下文
7. 在 Query Editor 焦点下可用 [ / ] 切换查询草稿，i 进入基础输入模式，Enter 触发执行
8. account_ticket_summary.sql 应返回真实结果行，empty_recent_tickets.sql 应显示空结果，bad_syntax.sql 应显示结构化错误
9. ticket_export_preview.sql 执行成功后，按 x 或 j 应在工作区内看到导出成功反馈和 /tmp 输出路径
10. 成功结果在 Results 中以表格方式展示，宽表会给出列分页提示，长结果仍可用 ↑ / ↓ 浏览
11. 错误状态会保留可读错误信息，不退化成空白或瞬时提示
12. 使用 Tab / Shift+Tab 时，当前焦点区域边框高亮会移动
13. 使用 ← / → 或 1 / 2 / 3 时，中间内容区会随视图切换
14. 使用 r 时，query / export 反馈会清空并回到 Ready
15. 将终端缩小到低于 100x28 时，会出现尺寸不足提示而不是错乱布局
16. 使用 Esc 可恢复默认工作台，使用 q 可稳定退出

当前限制

• sqlite-local 仍是当前最快的本地 runner live connect / inspect / query / export 路径
• Postgres / MySQL 当前默认指向 Docker demo 容器；若 demo stack 未启动，会回退为可读失败态
• 当前 runner 若缺少 cargo，需要使用已有二进制做交互 smoke；源码重建与测试需在具备 Rust 工具链的环境完成
• 非 TTY 启动当前会明确报错并退出；这是已记录限制，不是可支持的帮助命令路径

共享 QA 文档：

• TUI_ACCEPTANCE_CHECKLIST.md
• TUI_SMOKE_RUNBOOK.md
• TUI_TEST_STRATEGY.md
• TUI_REGRESSION_CHECKLIST.md