dbtool-cli-v1/USABLE_EVIDENCE_LEDGER.md

# 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`，并补齐 `/tmp/cmp64-role-probe-v4.json`、`/tmp/cmp64-postgres-root-inspect-v4.json`、`/tmp/cmp64-postgres-restricted-schema-inspect-v4.stderr.txt`、`/tmp/cmp64-postgres-restricted-query-v4.stderr.txt` 与 `/tmp/cmp64-tui-restricted-live-v6.log` | runner-side restricted / empty / failure 已补齐；剩余缺口转为 packaged artifact / CI / traceability |
| 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 导出成功 | 当前 runner 已补 happy path、failure、empty 与 browse-stability；剩余缺口不在 network-live 本身 |
| TUI / Linux release binary smoke | `target/release/dbtool-tui` 最小 TTY 启动 / 退出 | `verified` | `direct-run` | 2026-03-31 当前 runner 直接通过 `CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse cargo build --release -p dbtool-tui` 与 `scripts/tui/smoke-tty.sh target/release/dbtool-tui 40 120 /tmp/cmp60-dbtool-tui-release-smoke.log`；SHA256=`b02ab9be82ebc683c61cf193945a123a66ff181eb386607e95d3335bed84f339` | 仍缺 packaged artifact / CI contract |
| TUI / packaged artifact smoke | distributable archive / checksum / unpacked smoke | `blocked` | `doc-only` | 当前仓库尚无 `dbtool-tui` package script 或 release workflow entry | 需先建立 artifact contract，再补 Linux/macOS/Windows runner 证据 |
| 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. 在发起宿主机或 sidecar live 执行前，先跑 `scripts/qa/test-failure-path-fixtures.sh`；若只想缩小范围，可改跑 `scripts/qa/test-failure-path-fixtures.sh format` 或 `scripts/qa/test-failure-path-fixtures.sh sidecar`。
2. 在 Docker-capable 宿主机按 `QA_RUNTIME_ENVIRONMENT.md` 拉起 `postgres` / `mysql` 并完成 bootstrap。
3. 优先按 `HOST_FAILURE_PATH_CHECKLIST.md` 的顺序逐条执行 6 个场景；记录格式仍以 `FAILURE_PATH_EVIDENCE_TEMPLATE.md` 为准，首次回填可直接套用 `FAILURE_PATH_EVIDENCE_SAMPLE.md`。
4. 每条记录都必须带：
   - UTC 时间
   - 操作者 / 宿主机
   - binary path / `--version`
   - commit SHA / branch
   - 完整命令
   - 退出码
   - JSON 或错误摘要
   - verdict
5. 回填顺序：
   - 先在 issue / 评论里贴原始执行包
   - 再把 `CLI / PostgreSQL failure path`、`CLI / MySQL failure path` 两行改为 `verified` 或继续保留 `blocked`
   - 最后同步 `USABLE_RELEASE_GATE.md`
6. 若 `status` / `state` / `error.kind` 偏离模板预期，先拆 defect，再继续台账更新。

## Blocker / Risk 清单

### 产品 blocker

- `dbtool-usable-v1` 仍不能把 TUI 视为“已完成签收”的跨库操作台；当前虽已有 PostgreSQL / MySQL live happy path，但 live 覆盖仍偏窄。
- PostgreSQL / MySQL 的 failure-path 当前已补到直接执行层并通过最新 sidecar 复验；这一条线当前主要保持回归即可。
- TUI packaged artifact 证据仍未收口；不过 2026-03-31 Linux runner 已补到 `target/release/dbtool-tui` 的 release-binary 直接 smoke，且 PostgreSQL restricted-schema runner evidence 已完成，剩余缺口已收敛到 artifact contract / CI path。

### 环境 / 证据 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。
- 当前 PostgreSQL demo / TUI `reporting-postgres` profile 已可通过 non-superuser `dbtool` 与 restricted probe 产出真实 schema-level restricted live 证据；runner-side blocker 已解除。
- 当前仓库还没有 `dbtool-tui` 的 package script / workflow matrix；现有 release 直证只到 Linux release binary，不等于 distributable artifact 已验证。
- 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
- 权限 / 用户管理
- 备份 / 恢复
- 多连接并发在线工作区