feat(usable): package gui-host validation snapshot

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

USABLE_EVIDENCE_LEDGER.md

@@ -0,0 +1,133 @@
+# dbtool-usable-v1 证据台账
+
+## 目的
+
+- 将 usable-v1 的测试、smoke、手工验证和发布证据收敛到同一张表。
+- 明确区分 `verified`、`unverified`、`blocked`、`out-of-scope`。
+- 明确区分直接执行证据、宿主机证据和仅文档声明。
+
+## 状态定义
+
+| 状态 | 含义 |
+| --- | --- |
+| `verified` | 已有可审计执行证据 |
+| `partial` | 已有局部或分层证据，但还不能支撑该领域整体通过 |
+| `unverified` | 有资产或路径，但还没有足够执行证据 |
+| `blocked` | 理论路径存在，但被环境或前置产品能力阻塞 |
+| `out-of-scope` | 不属于 usable-v1 当前承诺 |
+
+## 证据模式定义
+
+| 模式 | 含义 |
+| --- | --- |
+| `direct-run` | 当前或历史 QA 直接执行并留档 |
+| `host-run` | Docker-capable 宿主机或外部 runner 已执行并回填 |
+| `doc-only` | 仅观察到文档、脚本或 workflow，尚无执行证据 |
+
+## TUI 结论映射
+
+| 层级 | 当前状态 | 说明 |
+| --- | --- | --- |
+| TUI / shell baseline | `verified` | 当前已有 TTY 启动、布局与退出直接执行证据 |
+| TUI / `sqlite-local` local live | `partial` | 当前已有局部真实工作流与历史 QA 证据，但仍不足以支撑 usable-v1 的跨库交付判断 |
+| TUI / PostgreSQL live path | `verified` | 2026-03-31 当前 runner 已直接通过 `scripts/tui/live-network-smoke.sh postgres ./target/debug/dbtool-tui` |
+| TUI / MySQL live path | `verified` | 2026-03-31 当前 runner 已直接通过 `scripts/tui/live-network-smoke.sh mysql ./target/debug/dbtool-tui` |
+
+- `sqlite-local` 证据用于证明 TUI 工作台不只是静态演示。
+- usable-v1 的 TUI 是否通过，不再取决于“是否存在 network live path”，而取决于 live 覆盖是否扩展到失败态、空态、浏览稳定性与发布前复验。
+
+## 当前资产盘点
+
+### 自动化测试
+
+| 位置 | 观察到的测试数 | 当前状态 | 备注 |
+| --- | --- | --- | --- |
+| `apps/cli/src/main.rs` | `21` | `verified` | 2026-03-28 已复核计数；当前 runner 复跑 `cargo test --workspace` 通过 |
+| `apps/tui/src/main.rs` | `9` | `verified` | 2026-03-31 已复核计数；当前 runner 复跑 `cargo test --workspace` 通过 |
+| `crates/db-app/src/lib.rs` | `6` | `verified` | 2026-03-28 已复核计数；当前 runner 复跑 `cargo test --workspace` 通过 |
+| `crates/db-config/src/lib.rs` | `3` | `verified` | 2026-03-28 已复核计数；当前 runner 复跑 `cargo test --workspace` 通过 |
+| `crates/db-core/src/lib.rs` | `4` | `verified` | 2026-03-28 已复核计数；当前 runner 复跑 `cargo test --workspace` 通过 |
+| `crates/db-drivers/src/lib.rs` | `10` | `verified` | 2026-03-28 已复核计数；当前 runner 复跑 `cargo test --workspace` 通过 |
+
+### Smoke / 发布 / Demo 资产
+
+| 路径 | 作用 | 当前状态 | 备注 |
+| --- | --- | --- | --- |
+| `SMOKE_RUNBOOK.md` | CLI runtime smoke runbook | `verified` | 路径与输入已可读且已局部执行 |
+| `RELEASE_RUNBOOK.md` | artifact smoke / release contract | `verified` | Linux 路径已有执行证据 |
+| `.github/workflows/release-smoke.yml` | Linux/macOS/Windows release runner | `unverified` | workflow 存在，但缺 macOS / Windows 实跑证据 |
+| `scripts/release/smoke-binary.sh` | 最小二进制 smoke | `verified` | 本 heartbeat 语法检查 + Linux binary 执行通过 |
+| `docker-compose.demo.yml` | PostgreSQL / MySQL demo runtime | `partial` | 当前 runner 已有 Docker daemon，但缺 `docker compose`；当前有效路径是复用已运行容器 + sidecar network execution |
+| `examples/scripts/bootstrap-postgres.sh` | PostgreSQL seed | `partial` | 语法已验证；2026-03-28 本 heartbeat 已通过等价 `docker exec` 完成 live import |
+| `examples/scripts/bootstrap-mysql.sh` | MySQL seed | `partial` | 语法已验证；2026-03-28 本 heartbeat 已通过等价 `docker exec` 完成 live import |
+| `examples/scripts/bootstrap-sqlite.sh` | SQLite seed | `verified` | 2026-03-28 本 heartbeat 通过 `node` fallback 实际执行 |
+| `scripts/tui/live-network-smoke.sh` | TUI PostgreSQL / MySQL live smoke | `verified` | 2026-03-31 当前 runner 已直接执行 postgres / mysql 两条路径 |
+
+## 统一证据台账
+
+| 领域 | 路径 | 状态 | 证据模式 | 最新证据 | 主要缺口 / 下一步 |
+| --- | --- | --- | --- | --- | --- |
+| 启动 / CLI 基础 | `target/release/dbtool --help` / `--version` | `verified` | `direct-run` | 2026-03-28 当前 heartbeat 通过 | 需补 GitHub macOS / Windows artifact 同级证据 |
+| Demo / SQLite seed | `examples/scripts/bootstrap-sqlite.sh` | `verified` | `direct-run` | 2026-03-28 当前 heartbeat 通过 | 无当前 blocker |
+| Demo / PostgreSQL seed | `examples/scripts/bootstrap-postgres.sh` | `partial` | `direct-run` | 2026-03-28 本 heartbeat 已通过等价 `docker exec` 完成 live import | 仍需补齐与 `docker compose` 入口完全同口径的证据 |
+| Demo / MySQL seed | `examples/scripts/bootstrap-mysql.sh` | `partial` | `direct-run` | 2026-03-28 本 heartbeat 已通过等价 `docker exec` 完成 live import | 仍需补齐与 `docker compose` 入口完全同口径的证据 |
+| Docker 路径 | Docker daemon + `dbtool-cli-v1_default` sidecar execution | `partial` | `direct-run` | 2026-03-28 当前 heartbeat 已直接复用运行中的 demo 容器并完成 sidecar execution | 当前 runner 仍缺 `docker compose`，且 QA 容器不能直接访问映射端口 |
+| CLI / SQLite happy path | `connect -> inspect -> query -> export` | `verified` | `direct-run` | 2026-03-28 当前 heartbeat 全链路通过 | 保持回归即可 |
+| CLI / SQLite failure path | missing file / non-db / bad SQL / overwrite | `verified` | `direct-run` | 2026-03-28 当前 heartbeat 通过 | 仍可补目录不存在、空结果导出边界 |
+| CLI / JSON structured envelope | `--result-format json` 的 `status` / `state` / `error|data` | `verified` | `direct-run` | 2026-03-28 已直接复核 validation error=`state:error`、empty result=`state:empty` | 保持 CLI / shared app 契约一致即可 |
+| CLI / PostgreSQL happy path | `connect -> inspect -> query` | `verified` | `host-run` | 2026-03-26 `CMP-17` 宿主机 smoke | 需补 failure-path 证据与 traceability |
+| CLI / PostgreSQL failure path | 错误密码 / 网络异常 / 坏 SQL | `verified` | `direct-run` | 2026-03-28 sidecar 直跑已确认 `status=error`、`state=error`、`error.kind=authentication|connection|query` | 当前该线主要保持回归即可 |
+| CLI / MySQL happy path | `connect -> inspect -> query` | `verified` | `host-run` | 2026-03-26 `CMP-17` 宿主机 smoke | 需补 traceability |
+| CLI / MySQL Unicode / export | `query` / `export` 中文与 emoji | `verified` | `host-run` | 2026-03-27 `CMP-23` patched-run | 持续防回归 |
+| CLI / MySQL failure path | 错误密码 / 网络异常 / 坏 SQL | `verified` | `direct-run` | 2026-03-28 最新 sidecar 复跑已确认 auth / connection / file-based bad SQL 都满足 `status=error`、`state=error`、正确 `error.kind` | 当前该线主要保持回归即可 |
+| TUI / shell baseline | 启动、布局、焦点、退出 | `verified` | `direct-run` | 2026-03-28 当前 heartbeat 正常终端与小终端 TTY smoke 均通过 | 仍需保持 README 与 smoke 口径一致 |
+| TUI / sqlite-local live path | connect / inspect / query / export | `partial` | `direct-run` | 历史 QA 文档已有；本 heartbeat 仅复核启动骨架 | 需按 usable-v1 口径补一轮连续操作证据 |
+| TUI / PostgreSQL live path | 网络数据库真实激活 | `verified` | `direct-run` | 2026-03-31 当前 runner 直接通过 `scripts/tui/live-network-smoke.sh postgres ./target/debug/dbtool-tui`；日志显示 `Validation: Connected`、3 schema entries、`3 rows returned` 与 CSV 导出成功 | 仍需补 failure / empty / restricted / browse-stability 覆盖 |
+| TUI / MySQL live path | 网络数据库真实激活 | `verified` | `direct-run` | 2026-03-31 当前 runner 直接通过 `scripts/tui/live-network-smoke.sh mysql ./target/debug/dbtool-tui`；日志显示 schema 加载、`3 rows returned` 与 CSV 导出成功 | 仍需补 failure / empty / restricted / browse-stability 覆盖 |
+| Linux artifact smoke | `scripts/release/smoke-binary.sh ./target/release/dbtool` | `verified` | `direct-run` | 2026-03-28 当前 heartbeat 通过 | 无当前 blocker |
+| macOS artifact smoke | `.github/workflows/release-smoke.yml` matrix | `blocked` | `doc-only` | workflow 存在 | 缺真实 runner 日志 |
+| Windows artifact smoke | `.github/workflows/release-smoke.yml` matrix | `blocked` | `doc-only` | workflow 存在 | 缺真实 runner 日志 |
+| 源码测试执行 | `cargo test --workspace` | `verified` | `direct-run` | 2026-03-28 当前 runner 通过用户态 Rust toolchain + `zig cc` / `zig ar` 复跑并全量通过 | 保持回归即可 |
+
+## PostgreSQL / MySQL failure-path 补证闭环
+
+1. 在 Docker-capable 宿主机按 `QA_RUNTIME_ENVIRONMENT.md` 拉起 `postgres` / `mysql` 并完成 bootstrap。
+2. 优先按 `HOST_FAILURE_PATH_CHECKLIST.md` 的顺序逐条执行 6 个场景；记录格式仍以 `FAILURE_PATH_EVIDENCE_TEMPLATE.md` 为准，首次回填可直接套用 `FAILURE_PATH_EVIDENCE_SAMPLE.md`。
+3. 每条记录都必须带：
+   - UTC 时间
+   - 操作者 / 宿主机
+   - binary path / `--version`
+   - commit SHA / branch
+   - 完整命令
+   - 退出码
+   - JSON 或错误摘要
+   - verdict
+4. 回填顺序：
+   - 先在 issue / 评论里贴原始执行包
+   - 再把 `CLI / PostgreSQL failure path`、`CLI / MySQL failure path` 两行改为 `verified` 或继续保留 `blocked`
+   - 最后同步 `USABLE_RELEASE_GATE.md`
+5. 若 `status` / `state` / `error.kind` 偏离模板预期，先拆 defect，再继续台账更新。
+
+## Blocker / Risk 清单
+
+### 产品 blocker
+
+- `dbtool-usable-v1` 仍不能把 TUI 视为“已完成签收”的跨库操作台；当前虽已有 PostgreSQL / MySQL live happy path，但 live 覆盖仍偏窄。
+- PostgreSQL / MySQL 的 failure-path 当前已补到直接执行层并通过最新 sidecar 复验；这一条线当前主要保持回归即可。
+- TUI failure / empty / restricted / browse-stability 与 packaged-binary 证据仍未收口。
+
+### 环境 / 证据 blocker
+
+- 当前 QA runner 已有 `docker` daemon，但缺 `docker compose`。
+- 当前 QA runner 已可通过用户态 Rust toolchain + `zig cc` / `zig ar` 复跑源码测试，并可通过 `host.docker.internal` 直接复跑 TUI live smoke；但仍无法按标准 compose/host-port 口径原样复跑。
+- 当前 QA runner 不能直接访问 `127.0.0.1:55432/53306` 或数据库容器 IP。
+- GitHub macOS / Windows release runner 仍缺真实运行日志与产物 smoke 记录。
+- release artifact / packaged binary 的 binary path、commit SHA / branch 仍需补齐追溯性。
+
+### Out-of-scope
+
+- Desktop / Web GUI
+- import、migration / schema editing
+- 权限 / 用户管理
+- 备份 / 恢复
+- 多连接并发在线工作区