# dbtool-usable-v1 测试策略

## 目标

- 验证“真实技术操作者”能否在当前阶段顺利完成高频数据库工作流。
- 将 CLI 已成立的能力、TUI 当前能力和发布证据链分层管理，避免混淆“局部通过”和“整体通过”。
- 对 PM 的可用性边界与 CTO 的技术边界给出可执行 QA 要求。

## 当前测试优先级

1. CLI 三库核心工作流是否仍成立
2. 失败路径是否可解释、可复现
3. TUI 是否已从 shell baseline 进入真实可用路径
4. 发布链路是否有跨平台可审计证据

## 测试分层

### 1. CLI 核心工作流

- PostgreSQL / MySQL / SQLite 分别验证 `connect -> inspect -> query -> export`
- 优先保留技术操作者最常见的排障与取证路径
- CLI 是 `usable-v1` 当前最成熟的真实使用入口

### 2. 失败路径

- 连接失败：错误 host / port / database / user / password、网络不可达、SQLite 文件异常
- 查询失败：坏 SQL、空结果、权限错误、对象不存在
- 导出失败：覆盖、目录不存在、无结果集、编码问题
- 失败路径必须和 happy path 一样保留证据

### 3. TUI 分层验收

- shell baseline：启动、布局、焦点、状态、终端尺寸降级、退出
- local live：`sqlite-local` 的 connect / inspect / query / export
- network live：PostgreSQL / MySQL 真实连接激活、错误持久显示、结果浏览与导出
- 未达到 network live 前，TUI 只能被标记为部分通过

### 4. 发布与可交付

- Linux / macOS / Windows 需要真实 runner 证据，而不是仅有 workflow 文件
- release artifact 需验证 `--help`、`--version`、最小 smoke
- README / runbook / smoke 脚本要和实际执行结果一致

## 证据规则

- 通过项必须保留命令、输入、输出摘要、环境信息
- 失败项必须保留复现步骤、退出码或错误摘要、预期与实际差异
- 未执行项必须明确写出原因
- 环境 blocker 与产品 blocker 分开记，不得混写

## 当前基线证据

- 源码测试资产：当前仓库可观察到 `52` 个 Rust 内联测试；2026-03-28 当前 runner 已通过用户态 Rust toolchain + `zig cc` / `zig ar` 复跑 `cargo test --workspace`
- CLI / SQLite：2026-03-28 本地 release / debug binary 重跑 happy path 与关键 failure path
- CLI / PostgreSQL：2026-03-26 `CMP-17` 宿主机 happy-path smoke
- CLI / MySQL：2026-03-26 `CMP-17` happy-path smoke + 2026-03-27 `CMP-23` Unicode patched-run
- TUI / shell：2026-03-28 本地 `scripts/tui/smoke-tty.sh` 正常终端与小终端路径通过
- TUI / deeper live：参考 `apps/tui/README.md`、`TUI_ACCEPTANCE_CHECKLIST.md`，但仍需在 usable-v1 口径下继续补证

## Failure-Path 补证闭环

1. 执行环境固定为 Docker-capable 宿主机，避免把当前 runner 缺 `docker` 的限制误记成产品失败。
2. 宿主机先按 `QA_RUNTIME_ENVIRONMENT.md` 完成 compose 启动和 PostgreSQL / MySQL bootstrap。
3. 优先按 `HOST_FAILURE_PATH_CHECKLIST.md` 执行宿主机检查顺序；记录格式仍以 `FAILURE_PATH_EVIDENCE_TEMPLATE.md` 为准，并用 `FAILURE_PATH_EVIDENCE_SAMPLE.md` 校准回填样式。
4. 每条证据至少断言：
   - `status`
   - `state`
   - `error.kind`
   - 无敏感信息泄露
5. 一轮执行完成后，同时回填：
   - 原始 issue 评论
   - `USABLE_EVIDENCE_LEDGER.md`
   - `USABLE_RELEASE_GATE.md`
6. 若任何场景的 `error.kind` 与模板不一致，优先拆 defect issue，而不是把台账改成 `verified`。

## Backend 验收要求

- `CMP-42` 至少需要补齐 PostgreSQL / MySQL 的真实可复验路径，而不只停留在 repo 内的 fixture 或单元测试
- `db-app` 的 connect / inspect / query / export 契约必须继续稳定，避免 TUI 与 CLI 对同一结果产生不同语义
- CLI `--result-format json` 的验收不应只看 `status`；对空结果和错误路径还应断言 `state`
- MySQL UTF-8、导出编码和错误分类回归必须继续可由 QA 独立验证
- 新缺陷必须拆成独立 issue，且附带最小复现步骤

## Frontend / TUI 验收要求

- `CMP-43` 需要把 TUI 从“可演示”推进到“可连续使用”
- 至少要形成一条真实网络数据库的可复验路径，不能只依赖 `sqlite-local`
- 失败连接、空结果、坏 SQL、导出反馈必须持续可见，不得只给瞬时提示
- 所有交互都要能由键盘完成，并能被 QA 以固定步骤复核

## 目前不应误判为通过的情况

- 只有 shell baseline 可启动
- 只有 README / workflow / runbook，但没有实际执行证据
- 只有 CLI 通过，而 TUI 仍未进入真实网络数据库路径
- 只有宿主机口头结论，没有 binary path、commit SHA 或关键输出摘要

## 下一轮验证重点

- 按 `HOST_FAILURE_PATH_CHECKLIST.md` 补齐 PostgreSQL / MySQL failure-path 6 条场景证据；首次回填可直接参考 `FAILURE_PATH_EVIDENCE_SAMPLE.md`
- 补齐 usable-v1 口径下的 TUI live SQLite 完整证据
- 追踪 `CMP-42` / `CMP-43` 是否给出可被 QA 直接复用的验收入口
- 补齐 GitHub macOS / Windows release runner 的真实 smoke 证据
- 对 PostgreSQL / MySQL failure-path 做最少一轮可审计回归