feat(usable): package gui-host validation snapshot

Co-Authored-By: Paperclip <noreply@paperclip.ing>

TUI_ACCEPTANCE_CHECKLIST.md

@@ -2,79 +2,111 @@
 
 ## 当前结论
 
-- 当前仍不能把 `dbtool-tui-v1` 整体判定为阶段 2 live integration 已全部通过；但 `CMP-36` 的 `sqlite-local` 真实 query / results / export 路径已经完成宿主机侧重建与验收回填。
+- 当前仍不能把 `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 优先级对齐依据：第二阶段关键路径仍是 `[CMP-34](/CMP/issues/CMP-34)` → `[CMP-35](/CMP/issues/CMP-35)` → `[CMP-36](/CMP/issues/CMP-36)`，QA 不应越过 shared app 契约提前宣告 live 通过。
+- 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`。
-- 当前 runner 不能把“源码可重建”记为通过：系统无 `cargo` / `rustc` / `rustfmt`，无法执行 `cargo check`、`cargo test -p dbtool-tui` 或重新生成二进制。
-- `dbtool-tui` 是 TTY 程序；`./target/debug/dbtool-tui --help` 在无 TTY 场景下返回 `No such device or address`，这必须被记录为非交互限制，而不是被误记为 smoke 失败或帮助能力已通过。
+- 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] `printf 'q' | script -qec 'stty rows 40 cols 120; ./target/debug/dbtool-tui' /tmp/tui-normal.log` 可稳定启动并退出
+- [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 会展示静态连接 / schema / query / results 上下文，但这些仍是本地示例状态，不是 live shared app 数据
-- [x] `printf 'q' | script -qec 'stty rows 20 cols 90; ./target/debug/dbtool-tui' /tmp/tui-small.log` 可稳定启动并退出
+- [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 的验收边界已在本文档中显式分层
-- [ ] 当前 runner 上源码重建通过
-- [ ] 当前 runner 上源码测试通过
+- [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（当前必须保持未通过）
+### B. 第二阶段 live integration（当前 runner demo path 已可复验）
 
-- [ ] `[CMP-34](/CMP/issues/CMP-34)` 已冻结 TUI live integration 契约
-- [ ] `[CMP-35](/CMP/issues/CMP-35)` 的 `sqlite-local` 真实 connect / inspect 路径已完成源码重建并回填运行证据
-- [x] `[CMP-36](/CMP/issues/CMP-36)` 的 `sqlite-local` 真实 query / results / export 路径已完成源码重建并回填运行证据
+- [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 数据下仍有明确文案
-- [ ] `Query Editor` 可针对真实活动连接执行查询
+- [x] `Query Editor` 可针对真实活动连接执行查询
 - [x] 真实查询可区分 `running` / `success` / `empty` / `error`
 - [ ] 真实结果区在常见终端尺寸下仍可浏览
 - [x] export 结果会给出明确成功 / 失败反馈
-- [ ] 全路径复用 `crates/db-app`，不通过 CLI 文本解析旁路取数
+
+### 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 验收
-- [ ] TUI 专属 demo / seed / Docker 路径已建立
+- [x] TUI 专属 demo / seed / Docker 路径已建立
 - [ ] release artifact / packaged binary 在目标平台有真实执行证据
 
 ## 当前 blocker
 
-- [ ] `[CMP-34](/CMP/issues/CMP-34)` 仍在 `in_progress`
-- [ ] `[CMP-35](/CMP/issues/CMP-35)` 仍在 `in_progress`，且当前 runner 缺少 Rust 工具链，无法回填重建证据
-- [x] `[CMP-36](/CMP/issues/CMP-36)` 已完成宿主机侧构建与验收回填；当前 agent runner 仍缺 Rust 工具链，但不再阻塞该 issue 关闭
+- [ ] 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`
-- [ ] 仓库仍无 TUI 专属 demo / seed / Docker live 验证路径
-- [ ] 当前 runner 缺 `cargo` / `rustc` / `rustfmt`，无法执行源码重建、测试与格式化
+- [ ] 当前 runner 默认裸 `cargo` 仍会被空的 `CARGO_REGISTRIES_CRATES_IO_PROTOCOL` 环境变量绊倒，runbook 需要显式写出 override
+- [ ] release artifact / packaged binary 仍缺真实 smoke 证据
 
-## 2026-03-27 已回填证据
+## 2026-03-27 ~ 2026-03-31 已回填证据
 
-- 正常尺寸 shell smoke：`printf 'q' | script -qec 'stty rows 40 cols 120; ./target/debug/dbtool-tui' /tmp/tui-normal.log`
+- 正常尺寸 shell smoke：`scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui`
 - 正常尺寸 shell 结果：退出码 `0`；日志包含六区布局、`Ready`、`Execution Idle`、静态 connections/schema/results 文案
-- 小终端 shell smoke：`printf 'q' | script -qec 'stty rows 20 cols 90; ./target/debug/dbtool-tui' /tmp/tui-small.log`
+- 小终端 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`
-- 非交互限制：`./target/debug/dbtool-tui --help` 返回 `Error: Os { code: 6, kind: Uncategorized, message: "No such device or address" }`
-- 源码状态盘点：`apps/tui/src/main.rs` 已引入 `sqlite-local` 的真实 connect / inspect / query / results / export worker 接线，以及内联测试覆盖
-- 源码验证限制：当前 runner 无 `cargo` / `rustc`，因此无法在本次回合执行 `cargo check`、`cargo test -p dbtool-tui` 或重新生成 `target/debug/dbtool-tui`
+- 源码重建：`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 连接切换
+- [x] 真实 shared app 连接切换
 - [ ] 真实 inspect / schema browser
-- [ ] 真实 query 执行
+- [x] 真实 query 执行
 - [ ] 真实 empty / error 结果处理
-- [ ] 真实 export 反馈
+- [x] 真实 export 反馈
 - [ ] TUI CI smoke
 - [ ] TUI release artifact smoke
-- [ ] TUI demo / seed / Docker 路径