dbtool-cli-v1/USABLE_ACCEPTANCE_CHECKLIST.md

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，但尚未完成更广的真实跨库验收；发布证据链仍不完整。