feat(usable): package gui-host validation snapshot

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

USABLE_ACCEPTANCE_CHECKLIST.md

@@ -0,0 +1,153 @@
+# dbtool-usable-v1 验收检查表
+
+## 当前结论
+
+- 当前结论：`no-go`。
+- 原因 1：CLI 已有较强真实使用证据，但 `dbtool-usable-v1` 不能只按 CLI 通过来判定整体通过。
+- 原因 2：TUI 已形成 PostgreSQL / MySQL demo live happy path，但仍缺 failure / empty / restricted / browse-stability 等更广覆盖证据。
+- 原因 3：发布链路仍缺 GitHub macOS / Windows runner 与 packaged binary 的真实执行证据。
+- 当前统一台账见 `USABLE_EVIDENCE_LEDGER.md`，当前发布门槛结论与模板见 `USABLE_RELEASE_GATE.md`。
+
+## 与 PM / CTO 的当前对齐依据
+
+- PM 验收边界：`PRODUCT_REQUIREMENTS.md`、`TUI_PRODUCT_REQUIREMENTS.md`、`DATABASE_SUPPORT_MATRIX.md`
+- CTO 技术边界：`CTO_REQUIREMENTS_HANDOFF.md`、`TUI_BACKEND_CONTRACT.md`
+- 当前状态说明：usable-v1 的统一 QA 结论已可建立；截至 2026-03-31，直接 blocker 已不再是 “TUI 缺 live-path”，而是 live 覆盖深度与 release evidence 仍未收口。
+
+## TUI 分层判定规则
+
+| 层级 | 允许结论 | 当前结论 | 备注 |
+| --- | --- | --- | --- |
+| shell baseline | `pass` / `blocked` | `pass` | 只判断启动、布局、焦点、TTY 契约与稳定退出 |
+| `sqlite-local` local live | `partial` / `blocked` | `partial` | 只能证明本地 SQLite 单会话工作流成立，不能代表跨库可交付 |
+| PostgreSQL / MySQL network live | `pass` / `blocked` | `pass` | 2026-03-31 当前 runner 已直接通过 PostgreSQL / MySQL demo live smoke |
+
+- network live 已不再是当前主 blocker，但单条 happy path 不能直接上抬成 usable-v1 整体 `pass`。
+- `sqlite-local` 真实路径应被保留为正向证据，但结论必须是 `partial`，不能上抬成整体完成。
+
+## 当前测试 / Smoke / 手工验证盘点
+
+### 自动化测试资产
+
+- 已观察到 Rust 内联测试共 `53` 个：
+  - `apps/cli/src/main.rs`：`21`
+  - `apps/tui/src/main.rs`：`9`
+  - `crates/db-app/src/lib.rs`：`6`
+  - `crates/db-config/src/lib.rs`：`3`
+  - `crates/db-core/src/lib.rs`：`4`
+  - `crates/db-drivers/src/lib.rs`：`10`
+- 2026-03-31 当前 runner 已复核测试资产盘点，并通过用户态 Rust toolchain + `zig cc` / `zig ar` 直接复跑 `cargo test --workspace`。
+
+### Smoke / 发布资产
+
+- 运行型 smoke：`SMOKE_RUNBOOK.md`
+- 发布型 smoke：`RELEASE_RUNBOOK.md`、`.github/workflows/release-smoke.yml`、`scripts/release/smoke-binary.sh`
+- Demo / seed / Docker 资产：`docker-compose.demo.yml`、`examples/scripts/bootstrap-postgres.sh`、`examples/scripts/bootstrap-mysql.sh`、`examples/scripts/bootstrap-sqlite.sh`
+
+### 本 heartbeat 的直接执行证据
+
+- `bash -n` 已通过：三份 bootstrap 脚本、`scripts/release/smoke-binary.sh` 与 `scripts/tui/smoke-tty.sh`
+- `./examples/scripts/bootstrap-sqlite.sh` 已通过；当前 runner 使用 `node` fallback seed
+- `./target/release/dbtool --help`、`--version`、SQLite `connect -> inspect -> query -> export` 已通过
+- SQLite failure-path 已复核：missing file、non-db file、bad SQL、export overwrite guard
+- CLI JSON 结构化结果已复核：
+  - validation error 返回 `status=error`、`state=error`
+  - 空结果查询返回 `status=success`、`state=empty`
+- `scripts/release/smoke-binary.sh ./target/release/dbtool` 已通过
+- `scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui 40 120 /tmp/qa-dbtool-tui.log` 已通过
+- `scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui 20 90 /tmp/qa-dbtool-tui-small.log` 已通过
+- `scripts/tui/live-network-smoke.sh postgres ./target/debug/dbtool-tui /tmp/dbtool-tui-postgres-live-qa.log` 已通过
+- `scripts/tui/live-network-smoke.sh mysql ./target/debug/dbtool-tui /tmp/dbtool-tui-mysql-live-qa.log` 已通过
+- PostgreSQL live smoke 日志已直接观察到：
+  - `Validation: Connected`
+  - `3 rows returned`
+  - `3 rows exported to /tmp/dbtool-tui-reporting-postgres-account-ticket-summary-sql.csv`
+- MySQL live smoke 日志已直接观察到：
+  - `Validation: Connected`
+  - `3 rows returned`
+  - `3 rows exported to /tmp/dbtool-tui-orders-mysql-account-ticket-summary-sql.csv`
+- `docker exec -i dbtool-cli-v1-postgres-1 psql ... < examples/fixtures/postgres/init.sql` 已通过
+- `docker exec -i dbtool-cli-v1-mysql-1 mysql ... < examples/fixtures/mysql/init.sql` 已通过
+- 通过 sidecar container 进入 `dbtool-cli-v1_default` 网络后，已直接执行 PostgreSQL / MySQL failure-path：
+  - PostgreSQL 错误密码返回 `error.kind=authentication`
+  - PostgreSQL 不可达端口返回 `error.kind=connection`
+  - PostgreSQL 坏 SQL 返回 `error.kind=query`
+  - MySQL 错误密码返回 `error.kind=authentication`
+  - MySQL 不可达端口返回 `error.kind=connection`
+  - MySQL `--file examples/sql/mysql/failing_query.sql` 在最新 sidecar 复跑中已返回 `error.kind=query`
+
+## 真实使用验收矩阵
+
+| 领域 | 真实场景 | 通过标准 | 当前证据 | 结论 |
+| --- | --- | --- | --- | --- |
+| CLI / SQLite | QA 用本地 SQLite 文件完成 `connect -> inspect -> query -> export` | 命令可重复执行，输出可读，失败路径可解释 | 2026-03-28 本地重跑 `bootstrap-sqlite`、`target/release/dbtool --help`、`connect`、`inspect`、`query`、CSV / JSON `export` 均通过 | `pass` |
+| CLI / SQLite failure | 本地错误文件、坏文件、坏 SQL、导出覆盖 | 非零退出码，错误信息可行动 | 2026-03-28 本地重跑 missing file、non-db file、bad SQL、export overwrite；均给出明确错误 | `pass` |
+| CLI / PostgreSQL | 技术操作者在 Docker 宿主机完成 happy path | `connect`、`inspect`、`query` 可跑通且有可审计输出 | 2026-03-26 `CMP-17` 宿主机评论已回填 happy-path smoke | `partial` |
+| CLI / MySQL | 技术操作者在 Docker 宿主机完成 happy path 与 Unicode 导出 | `connect`、`inspect`、`query`、`export` 可跑通，中文和 emoji 不损坏 | 2026-03-26 `CMP-17` happy path；2026-03-27 `CMP-23` patched-run 证据已覆盖字符集变量、官方 CLI、`dbtool query`、`dbtool export` | `partial` |
+| CLI / 跨库一致性 | PostgreSQL / MySQL / SQLite 共享同一 mental model | connect / inspect / query / export 一致，差异有文档 | `README.md`、`PRODUCT_REQUIREMENTS.md`、`DATABASE_SUPPORT_MATRIX.md` 已定义差异；CLI 侧证据较强 | `partial` |
+| TUI / shell baseline | 用户能进入工作台、看懂状态、稳定退出 | 六区布局、焦点切换、尺寸降级、退出稳定 | 2026-03-28 本地重跑 `scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui` 的正常终端与小终端路径，均通过 | `pass` |
+| TUI / sqlite-local live path | 用户能在单会话内看到连接、schema、draft、结果与导出反馈 | `sqlite-local` connect / inspect / query / export 全链路可复核 | 当前共享文档与 `apps/tui/README.md` 已定义路径，但本轮仅直接观察到启动与状态骨架 | `partial` |
+| TUI / PostgreSQL & MySQL live path | 用户能在 TUI 内真实激活并使用网络数据库 | 激活连接、浏览对象、运行查询、查看错误或结果 | 2026-03-31 当前 runner 直接通过 PostgreSQL / MySQL live smoke；日志已见连接成功、schema 加载、查询成功与导出成功 | `pass` |
+| 发布 / Linux artifact | 非源码路径可被 QA 复核 | artifact 解包、`--help`、`--version`、smoke 脚本通过 | 既有 `ACCEPTANCE_CHECKLIST.md` 已记录 Linux artifact smoke | `pass` |
+| 发布 / macOS & Windows artifact | 非 Linux 用户也能获得同等级发布证据 | 实际 runner 执行成功，日志可审计 | 当前仓库仅有 workflow 与 runbook，缺真实执行证据 | `blocked` |
+
+## 本轮直接执行证据
+
+- `./examples/scripts/bootstrap-sqlite.sh`
+- `./target/release/dbtool --help`
+- `./target/release/dbtool --version`
+- `./target/release/dbtool connect --driver sqlite --path examples/tmp/dbtool-demo.sqlite`
+- `./target/release/dbtool inspect --driver sqlite --path examples/tmp/dbtool-demo.sqlite --schema main`
+- `./target/release/dbtool inspect --driver sqlite --path examples/tmp/dbtool-demo.sqlite --schema main --table tickets`
+- `./target/release/dbtool query --driver sqlite --path examples/tmp/dbtool-demo.sqlite --file examples/sql/sqlite/happy_path_query.sql`
+- `./target/release/dbtool export --driver sqlite --path examples/tmp/dbtool-demo.sqlite --file examples/sql/sqlite/export_query.sql --format csv --output /tmp/dbtool-export.csv`
+- `./target/release/dbtool export --driver sqlite --path examples/tmp/dbtool-demo.sqlite --file examples/sql/sqlite/export_query.sql --format json --output /tmp/dbtool-export.json`
+- `./target/release/dbtool connect --driver sqlite --path examples/tmp/does-not-exist.sqlite`
+- `./target/release/dbtool connect --driver sqlite --path /tmp/not-a-db.txt`
+- `./target/release/dbtool query --driver sqlite --path examples/tmp/dbtool-demo.sqlite --file examples/sql/sqlite/failing_query.sql`
+- `./target/debug/dbtool query --driver sqlite --path examples/tmp/dbtool-demo.sqlite --sql "SELECT id FROM tickets WHERE status = ?1" --param missing --result-format json`
+- `./target/debug/dbtool query --driver sqlite --path /tmp/notfound.sqlite --sql '' --result-format json`
+- 二次串行执行 `export` 到同一路径，确认默认拒绝覆盖，错误为 `output file ... already exists; pass --overwrite to replace it`
+- `scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui 40 120 /tmp/qa-dbtool-tui.log`
+- `scripts/tui/smoke-tty.sh ./target/debug/dbtool-tui 20 90 /tmp/qa-dbtool-tui-small.log`
+
+## PostgreSQL / MySQL failure-path 补证最短闭环
+
+1. 在 Docker-capable 宿主机按 `QA_RUNTIME_ENVIRONMENT.md` 拉起 `docker compose -f docker-compose.demo.yml up -d postgres mysql`，并执行两份 bootstrap 脚本。
+2. 按 `HOST_FAILURE_PATH_CHECKLIST.md` 的顺序执行 6 个场景，记录格式继续使用 `FAILURE_PATH_EVIDENCE_TEMPLATE.md`：
+   - `PG-CONN-AUTH-001`
+   - `PG-CONN-NET-001`
+   - `PG-QUERY-SQL-001`
+   - `MY-CONN-AUTH-001`
+   - `MY-CONN-NET-001`
+   - `MY-QUERY-SQL-001`
+3. 每条证据都必须留：UTC 时间、操作者、宿主机、execution path、binary path、`--version`、commit SHA、branch、完整命令、退出码、关键 JSON / 错误摘要、最终 verdict。
+4. 先把原始执行包回填到对应 issue / heartbeat 评论，再同步更新 `USABLE_EVIDENCE_LEDGER.md` 与 `USABLE_RELEASE_GATE.md`。
+5. 若 `status` / `state` / `error.kind` 任何一项偏离模板预期，不把它记成“补证完成”，而是单独拆 defect issue。
+6. 如需减少人工抄录，可在宿主机直接运行 `scripts/qa/run-failure-path-evidence.sh ./target/release/dbtool all ./tmp/failure-path-evidence`；当前 helper 会自动校验 `status` / `state` / `error.kind`、traceability 完整性，并对可检测到的密码泄露模式直接判 `fail`，但仍需逐条人工复核生成的 markdown 包。
+7. 2026-03-28 当前 QA 容器虽已可访问 Docker daemon，但仍不能直接访问 `127.0.0.1:55432/53306` 或数据库容器 IP；当前有效执行路径是 sidecar container 加入 `dbtool-cli-v1_default` 网络后运行 `dbtool`。
+
+## 产品 blocker
+
+- `dbtool-usable-v1` 还不能把 TUI 视为“已完整签收”的跨库操作台；当前已覆盖 live happy path，但覆盖仍偏窄。
+- TUI 的 PostgreSQL / MySQL 真实激活、基础 schema 加载、查询与导出已进入可验状态。
+- TUI 的 failure / empty / restricted / browse-stability 仍缺最新直接 runner 证据。
+- PostgreSQL / MySQL 的 failure-path 已有最新直接执行证据，且最新 sidecar 复验已确认 6 个场景全部满足模板预期。
+
+## 环境 / 证据 blocker
+
+- 当前 QA runner 已能访问 `docker` daemon，但仍缺 `docker compose` 子命令。
+- 当前 QA runner 不能直接访问 `127.0.0.1:55432/53306` 或数据库容器 IP；TUI 当前有效入口是 `host.docker.internal` + TTY smoke 脚本。
+- GitHub macOS / Windows release runner 仍缺真实执行日志与产物 smoke 证据。
+- release artifact / packaged binary 的 binary path 与 commit SHA / branch 仍待补齐，可追溯性不足。
+
+## 回归风险
+
+- MySQL UTF-8 / collation 回归会直接破坏“真实可用”的跨库承诺。
+- TUI 若只保留 shell 演示而没有真实网络连接路径，会造成“能演示但不可交付”的误判。
+- 发布流程若只有 workflow 文件而没有真实 runner 证据，容易把“声明可发布”误当成“已验证可发布”。
+
+## 当前发布判断
+
+- 当前不能宣布 `dbtool-usable-v1` 通过验收。
+- 当前更准确的结论是：CLI 已经具备较强可用性证据；TUI 已具备 demo live happy path，但尚未完成更广的真实跨库验收；发布证据链仍不完整。