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 / 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
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
• 权限 / 用户管理
• 备份 / 恢复
• 多连接并发在线工作区