paperclip/dbtool-cli-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a28dab4cd9f7a21dd0d537f65335bea71ea567fd
dbtool-cli-v1/TUI_ACCEPTANCE_CHECKLIST.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.6 KiB
Raw Blame History

dbtool-tui-v1 验收检查表（阶段 2 分层版）

当前结论

  • 当前仍不能把 dbtool-tui-v1 的全部发布前工作都判定为完成；但当前 runner 已建立 PostgreSQL / MySQL 的 TTY live demo path，CMP-55 范围内的 network live blocker 已解除。
  • Product / PM 对齐依据：[CMP-33](/CMP/issues/CMP-33)、[CMP-37](/CMP/issues/CMP-37)、plans/2026-03-27-dbtool-tui-v1-phase-2-scope.md。
  • CTO 优先级对齐依据：当前应优先补 live 覆盖深度（failure / empty / restricted / browse-stability）与 release smoke，而不是继续把 “缺少 live-path” 当成主 blocker。
  • 2026-03-27 当前 runner 已回填 shell baseline 证据：./target/debug/dbtool-tui 在 120x40 与 90x20 TTY 路径都可复现，退出码均为 0。
  • 2026-03-28 当前 runner 已直接执行 CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse cargo build -p dbtool-tui 与 CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse cargo test -p dbtool-tui；默认裸 cargo 仍会因为空的 CARGO_REGISTRIES_CRATES_IO_PROTOCOL 环境变量而失败，这属于环境口径问题，不是产品失败。
  • dbtool-tui 是 TTY 程序；2026-03-28 源码重建后的 ./target/debug/dbtool-tui --help 已返回退出码 1，并明确提示需要交互式 TTY 和 scripts/tui/smoke-tty.sh，不能再把旧的 No such device or address 产物输出当成当前契约。
  • 2026-03-31 当前 runner 已确认可通过 host.docker.internal:55432/53306 访问 demo 数据库，并直接通过 scripts/tui/live-network-smoke.sh 复跑 PostgreSQL / MySQL TUI live path。

usable-v1 签收关注点

1. 状态恢复

  • r 必须被视为当前唯一显式“恢复到 Ready”的键位；它会同时清空 query / export 反馈，而不是只重置单一面板。
  • 失败连接、坏 SQL、空结果、导出错误都必须在工作区持续可见，直到用户主动切换连接、切换草稿或按 r 清空。
  • 查询运行中若立即导出，界面应给出明确提示 Wait for the current query to finish before exporting.，而不是静默无响应。

2. 键位一致性

  • Enter 只跟随当前焦点语义变化，不应在同一焦点下承担多个冲突动作。
  • Esc 在编辑模式与普通导航模式都应把用户带回更稳定、更可理解的状态。
  • [ / ] 只在 Query Editor 与 Results 生效；文档和 QA 结论不能再写入不存在的快捷键。

验收分层

A. Shell baseline（当前可验）

  • 预构建二进制 target/debug/dbtool-tui 存在
  • scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui 可稳定启动并退出
  • 正常尺寸下可见六区布局：Connections、Schema Browser、Query Editor、Results、Inspector、Status & Activity
  • 正常尺寸下默认状态包含 Ready、Execution Idle、Workspace
  • 当前 shell baseline 的可见工作区可稳定复现，但仅凭这组可见文本不能单独记成 live shared app 验收通过
  • scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui 20 90 /tmp/tui-small.log 可稳定启动并退出
  • 小终端路径会显示 Terminal Too Small
  • 小终端路径会显示 Resize the terminal
  • shell baseline 与 live integration 的验收边界已在本文档中显式分层
  • 当前 runner 上源码重建通过：CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse cargo build -p dbtool-tui
  • 当前 runner 上源码测试通过：CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse cargo test -p dbtool-tui
  • dbtool-tui 独立 release artifact smoke 已建立

B. 第二阶段 live integration（当前 runner demo path 已可复验）

  • 当前 runner 已有可重复的 PostgreSQL / MySQL TTY live smoke 入口
  • 当前 runner 已直接观察到真实连接激活与 schema 加载 happy path
  • sqlite-local 与 network live 都复用 crates/db-app，不通过 CLI 文本解析旁路取数
  • PostgreSQL live smoke：scripts/tui/live-network-smoke.sh postgres ./target/debug/dbtool-tui
  • MySQL live smoke：scripts/tui/live-network-smoke.sh mysql ./target/debug/dbtool-tui
  • 真实连接激活可区分 loading / success / failure
  • 真实连接失败后，错误能在 Inspector 与 Status & Activity 中持续可见
  • 真实 schema browser 可展示 schema / object / column 层级
  • empty schema 与 restricted schema 在 live 数据下仍有明确文案
  • Query Editor 可针对真实活动连接执行查询
  • 真实查询可区分 running / success / empty / error
  • 真实结果区在常见终端尺寸下仍可浏览
  • export 结果会给出明确成功 / 失败反馈

D. usable-v1 状态恢复与键盘一致性（当前可按现有实现复核）

  • r 会同时清空 query 结果、query 错误与 export feedback，并把界面恢复到 Ready
  • Esc 在普通导航下会回到默认 Workspace 与 Query Editor 焦点
  • Esc 在编辑模式下只退出 insert mode，不会误触发查询执行
  • 插入模式下 Enter 只插入换行，并给出 Press Esc, then Enter to run 提示
  • 查询运行中按 x / j 会给出等待提示，而不是覆盖当前运行状态
  • [ / ] 在 Query Editor 与 Results 之外不会制造隐藏状态变化
  • 当前对外文档已与实现一致，不再声明不存在的 l / e 快捷键

C. 非交互 / 发布前路径（当前必须显式保留限制）

  • QA 已确认 dbtool-tui 需要 TTY，不能用 --help 替代交互 smoke
  • GitHub Actions 已覆盖 dbtool-tui smoke
  • 非开发者可按 runbook 从 packaged binary 复现 TUI 验收
  • TUI 专属 demo / seed / Docker 路径已建立
  • release artifact / packaged binary 在目标平台有真实执行证据

当前 blocker

  • live failure 连接在 Inspector / Status & Activity 的持续可见性仍缺 2026-03-31 当前 runner 证据
  • live empty / restricted schema 文案仍缺 2026-03-31 当前 runner 证据
  • 结果区在常见终端尺寸下的稳定浏览仍缺 2026-03-31 当前 runner 证据
  • .github/workflows/release-smoke.yml 当前只覆盖 dbtool
  • 当前 runner 默认裸 cargo 仍会被空的 CARGO_REGISTRIES_CRATES_IO_PROTOCOL 环境变量绊倒，runbook 需要显式写出 override
  • release artifact / packaged binary 仍缺真实 smoke 证据

2026-03-27 ~ 2026-03-31 已回填证据

  • 正常尺寸 shell smoke：scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui
  • 正常尺寸 shell 结果：退出码 0；日志包含六区布局、Ready、Execution Idle、静态 connections/schema/results 文案
  • 小终端 shell smoke：scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui 20 90 /tmp/tui-small.log
  • 小终端 shell 结果：退出码 0；日志包含 Terminal Too Small 与 Resize the terminal
  • 源码重建：CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse cargo build -p dbtool-tui
  • 源码测试：CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse cargo test -p dbtool-tui，当前直接通过 9 个内联测试
  • 非交互限制（源码重建后二进制）：./target/debug/dbtool-tui --help 返回退出码 1，并输出 dbtool-tui requires an interactive TTY... 与 Use \scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui`...`
  • 源码状态盘点：apps/tui/src/main.rs 已引入 sqlite-local 与 PostgreSQL / MySQL demo profile 的真实 connect / inspect / query / results / export worker 接线，以及内联测试覆盖
  • Docker / demo 盘点：docker --version 与 docker ps 通过；虽然 docker compose version 失败，但当前 demo 容器健康，且 scripts/tui/live-network-smoke.sh 已可在当前 runner 直接复跑 PostgreSQL / MySQL happy path
  • PostgreSQL live smoke：scripts/tui/live-network-smoke.sh postgres ./target/debug/dbtool-tui 直接通过；导出产物 /tmp/dbtool-tui-reporting-postgres-account-ticket-summary-sql.csv
  • MySQL live smoke：scripts/tui/live-network-smoke.sh mysql ./target/debug/dbtool-tui 直接通过；导出产物 /tmp/dbtool-tui-orders-mysql-account-ticket-summary-sql.csv
  • PostgreSQL live 日志摘要：已直接观察到 Validation: Connected、3 rows returned、3 rows exported
  • MySQL live 日志摘要：已直接观察到 Validation: Connected、3 rows returned、3 rows exported
  • network path 盘点：当前 runner 对 127.0.0.1:55432/53306 仍不可达，但可通过 host.docker.internal:55432/53306 稳定访问 demo 容器

当前不应误判为已通过的能力

  • 真实 shared app 连接切换
  • 真实 inspect / schema browser
  • 真实 query 执行
  • 真实 empty / error 结果处理
  • 真实 export 反馈
  • TUI CI smoke
  • TUI release artifact smoke