paperclip/dbtool-cli-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cmp-66-connection-management-integration
dbtool-cli-v1/TUI_ACCEPTANCE_CHECKLIST.md
Paperclip CTO d5f69462b0
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): integrate current dbtool implementation snapshot 
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-04-02 08:26:18 +00:00

12 KiB
Raw Permalink 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。
  • 2026-03-31 当前 runner 已进一步补齐 PostgreSQL 失败连接 / 空结果 / 坏 SQL、MySQL empty schema / 28x100 结果浏览稳定性，以及 PostgreSQL restricted schema live 直证；当前未收口项已收敛为 CI / packaged artifact / 非开发者复验，而不是 runner-side restricted blocker，见 CMP-64。

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 结论不能再写入不存在的快捷键。

3. 连接管理与 secret 边界

  • 启动前环境变量 override 仍然是 operator fallback，但不再是唯一连接管理路径；当前 TUI 已提供 in-app 的新增 / 编辑 / 删除 / 保存并激活 workflow。
  • 当前 secret handling 已区分两层：profile 文件只持久化非 secret 字段；Session password 只在本次 TUI 进程内复用。
  • PostgreSQL / MySQL 的 demo host override（DBTOOL_TUI_POSTGRES_HOST/PORT、DBTOOL_TUI_MYSQL_HOST/PORT）仍不能误记成普通用户主路径，它只用于特定 host 环境。

验收分层

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 在 live 数据下有明确文案
  • connection-failure fallback 会把 browser state 渲染为 unavailable (restricted) 并保留恢复文案
  • successful live restricted schema 可与 empty / hidden 稳定区分；当前 runner 已直接观察到 restricted_probe、Schema failure、schema access is restricted: restricted_probe 与 query-blocking 文案，见 CMP-64
  • 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 快捷键

E. 连接管理工作流（源码已落地，待 QA 走真实 TTY）

  • Connections 视图展示的列表来自 profile store，而不是硬编码 demo-only 列表
  • n 可进入新增流程，并在中间 Query Editor 显示分步式字段表单
  • e 可编辑已保存 profile，且 Session password 不会明文回显
  • t 会对 staged profile 执行 connect + inspect 测试，并在 Results / Status & Activity 中保留反馈
  • s 会保存非 secret 字段、复用 session secret、设置 active profile，并直接进入查询工作流
  • d 会进入删除确认；只有 Enter 才删除，Esc 会取消
  • DBTOOL_TUI_PROFILE_STORE 可将 smoke 隔离到临时 store，不污染长期配置
  • 持久化的 profile 文件不包含密码或 password JSON 字段

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

  • .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 容器
  • PostgreSQL failure visibility：TTY 脚本日志 /tmp/dbtool-tui-postgres-auth-failure.log 已直接观察到 Connection Failure、Recovery path、postgres authentication failed 与 browser unavailable (restricted) 占位态
  • PostgreSQL empty result：TTY 脚本日志 /tmp/dbtool-tui-postgres-empty-result.log 已直接观察到 empty_recent_tickets.sql、No rows returned、0 rows returned in 77 ms 与 Execution: Empty
  • PostgreSQL bad SQL：TTY 脚本日志 /tmp/dbtool-tui-postgres-bad-sql.log 已直接观察到 bad_syntax.sql、Query error 与 query failed: syntax error ...
  • MySQL empty schema：TTY 脚本日志 /tmp/dbtool-tui-mysql-empty-schema.log 已直接观察到 Schema dbtool_demo is empty. Schema dbtool_demo has no tables or views in the current target.
  • MySQL browse-stability：28x100 TTY 脚本日志 /tmp/dbtool-tui-mysql-browse-stability.log 已直接观察到 4 rows returned in 2 ms、Result columns paged to 2-5 of 6 与结果行浏览更新
  • PostgreSQL restricted-schema probe：2026-03-31 当前 runner 已直接复验 /tmp/cmp64-role-probe-v4.json、/tmp/cmp64-postgres-root-inspect-v4.json、/tmp/cmp64-postgres-restricted-schema-inspect-v4.stderr.txt、/tmp/cmp64-postgres-restricted-query-v4.stderr.txt 与 /tmp/cmp64-tui-restricted-live-v6.log；证据显示 dbtool 为非 superuser、root inspect 保留 restricted_probe、显式 inspect 返回 restricted inspect error、直接 query 返回 permission denied，且 release TUI log 已直接显示 Schema Browser / Inspector / Status & Activity / query-blocking copy 的 restricted 文案

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

  • 真实 shared app 连接切换
  • 真实 inspect / schema browser
  • 真实 query 执行
  • 真实 empty / error 结果处理
  • 真实 export 反馈
  • TUI 连接管理的真实 TTY 直证
  • 连接测试后立即保存并激活自定义 profile 的 QA 直证
  • session-only secret 输入 / 复用的 QA 直证
  • 无需预设 host override 即可完成 PostgreSQL / MySQL 自定义配置
  • TUI CI smoke
  • TUI release artifact smoke