# 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（当前可验）

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

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

- [x] 当前 runner 已有可重复的 PostgreSQL / MySQL TTY live smoke 入口
- [x] 当前 runner 已直接观察到真实连接激活与 schema 加载 happy path
- [x] `sqlite-local` 与 network live 都复用 `crates/db-app`，不通过 CLI 文本解析旁路取数
- [x] PostgreSQL live smoke：`scripts/tui/live-network-smoke.sh postgres ./target/debug/dbtool-tui`
- [x] 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 数据下仍有明确文案
- [x] `Query Editor` 可针对真实活动连接执行查询
- [x] 真实查询可区分 `running` / `success` / `empty` / `error`
- [ ] 真实结果区在常见终端尺寸下仍可浏览
- [x] export 结果会给出明确成功 / 失败反馈

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

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

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

- [x] QA 已确认 `dbtool-tui` 需要 TTY，不能用 `--help` 替代交互 smoke
- [ ] GitHub Actions 已覆盖 `dbtool-tui` smoke
- [ ] 非开发者可按 runbook 从 packaged binary 复现 TUI 验收
- [x] 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 容器

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

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