feat(usable): package gui-host validation snapshot

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

apps/tui/README.md

@@ -13,6 +13,7 @@
 - 键盘驱动的连接切换工作流，以及连接 `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 反馈
@@ -23,11 +24,25 @@
 
 当前不包含：
 
-- 真实网络数据库连接激活
 - 多连接并发会话
 - 自定义新增 / 编辑连接表单
+- 非 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）”。
+
 ## 运行方式
 
 在项目根目录执行：
@@ -38,6 +53,7 @@ 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 工具链，可先使用已有产物：
 
@@ -45,6 +61,38 @@ cargo run -p dbtool-tui
 ./target/debug/dbtool-tui
 ```
 
+## TTY smoke 契约
+
+- `dbtool-tui` 需要交互式 TTY；正常终端启动与自动化 smoke 都必须走 TTY 路径。
+- 当前最小可重复入口：
+
+```bash
+scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui
+```
+
+- PostgreSQL live smoke：
+
+```bash
+export DBTOOL_PASSWORD=dbtool
+scripts/tui/live-network-smoke.sh postgres ./target/debug/dbtool-tui
+```
+
+- MySQL live smoke：
+
+```bash
+export DBTOOL_PASSWORD=dbtool
+scripts/tui/live-network-smoke.sh mysql ./target/debug/dbtool-tui
+```
+
+- 小终端降级入口：
+
+```bash
+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`：切换焦点面板
@@ -59,6 +107,14 @@ cargo run -p dbtool-tui
 - `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` 只插入换行。
+
 ## 快速测试路径
 
 如果你只是想快速走通一遍当前可见工作流，推荐按下面步骤操作：
@@ -103,12 +159,14 @@ QA 可按以下步骤复核：
 
 ## 当前限制
 
-- `sqlite-local` 是当前唯一可在本地 runner 直接完成 live connect / inspect / query / export 的路径
-- Postgres / MySQL 连接仍以可读失败态保留，用于验证多目标上下文和错误持续可见性
+- `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`