dbtool-cli-v1/ACCEPTANCE_CHECKLIST.md

dbtool-cli-v1 验收检查表（初版）

当前结论

• 当前环境中，项目配置声明的主工作区路径为 /workspace/repo/dbtool-cli-v1。
• QA 首次盘点时，该路径原本不存在；当前已经补齐 Rust workspace、CLI、demo seed 资产、smoke runbook 和 release-smoke workflow 基线。
• 2026-03-26 本地 Linux 已执行：CLI --help、--version、SQLite connect / inspect / query / export、SQLite seed 重放、Linux artifact checksum 与 artifact smoke。
• 2026-03-26 CMP-17 评论已回填宿主机 smoke 结果：PostgreSQL / MySQL happy path 已在具备 Docker 的宿主机完成，说明“QA 在宿主机执行、数据库由仓库内 compose 临时拉起”的推荐路径成立。
• 2026-03-26 当前 QA runner 仍确认：node v24.14.0 可用，docker 不在 PATH；Rust toolchain 可通过显式 PATH 与 zig 包装器调用，但本 agent 仍无法在本地拉起 Docker 数据库。
• 2026-03-26 已补做 MySQL 修复的离线回归：cargo test -p db-drivers mysql_ 通过，cargo test -p dbtool-cli 通过，cargo build -p dbtool-cli --release 通过，且 target/release/dbtool 已包含 SET NAMES utf8mb4 COLLATE utf8mb4_unicode_ci。
• 2026-03-27 新的宿主机评论与 CMP-22 指出：在干净重建并显式 UTF-8 导入后，MySQL 官方 CLI、dbtool query 与 dbtool export 均正常，说明问题边界进一步收敛到 bootstrap/import 字符集路径。
• 2026-03-27 CMP-23 已补齐宿主机 patched-run 证据：character_set_% / collation_% 变量、MySQL 官方 CLI 查询结果、dbtool query 结果、dbtool export CSV/JSON 摘要均已附上，且 张敏、权限验证、emoji 显示正常。
• 当前检查表仍不能直接宣布整体通过，因为 GitHub 的 macOS / Windows release runner 仍缺实测证据；MySQL Unicode 缺陷已被收敛并具备关闭 CMP-23 的证据，不再是当前 backend blocker。

与 PM / CTO 的当前对齐依据

• PM 对齐来源：项目说明与任务描述中定义的范围和完成标准。
• CTO 对齐来源：项目说明中的工程边界与跨平台目标。
• 待补强项：来自产品说明任务和架构任务的正式共享文档落地后，需要回填到本检查表。

发布门槛

• 项目仓库已落地到可访问工作区，路径可重复获取
• 安装、启动、demo、seed、smoke、Docker 路径存在且写入文档
• PostgreSQL、MySQL、SQLite 三类数据库均有可执行验证步骤
• macOS、Linux、Windows 的期望行为已记录
• 失败路径可复现、可记录、可区分严重级别
• 验收证据可由非开发者重复执行

基础可运行性

• 仓库可拉起或可构建
• CLI 二进制或运行命令已定义
• --help 输出稳定
• 版本信息可读取
• 缺失依赖时返回可理解错误

启动 / Demo / Seed / Smoke / Docker

• 启动说明存在且从零可执行
• demo 数据准备步骤存在
• seed 步骤存在且幂等
• smoke 脚本存在且可一键执行
• Dockerfile 或 compose 路径存在并可运行
• 上述路径都有预期输出与失败输出说明

连接验证

PostgreSQL

• 有效连接参数可成功连接
• 无效 host / port / database / user / password 会失败
• 网络不可达时返回清晰错误
• 权限不足时返回清晰错误

MySQL

• 有效连接参数可成功连接
• 无效 host / port / database / user / password 会失败
• 网络不可达时返回清晰错误
• 权限不足时返回清晰错误

SQLite

• 有效文件路径可成功连接
• 文件不存在时返回清晰错误
• 路径无权限时返回清晰错误
• 非数据库文件时返回清晰错误

Schema Introspection

• 可列出 schema（适用时）
• 可列出 table / view
• 可查看列定义
• 空 schema / 空数据库表现明确
• 不支持对象类型时提示明确

查询执行

• 可执行基础查询
• 可执行带条件查询
• 空结果集表现正确
• 语法错误会失败且可定位
• 超时 / 长查询路径可观测
• 参数化查询行为明确

导出流程

• 导出命令存在
• 输出路径规则明确
• 目标文件已存在时行为明确
• 空结果导出行为明确
• 编码、换行、分隔符规则明确
• 导出失败时无静默成功

边界与回归关注

• 大结果集不会直接崩溃
• 特殊字符 / Unicode 结果可处理
• NULL 值处理一致
• 时区 / 日期时间输出规则明确
• 数据库间差异有记录
• 回归验证步骤可重复执行

2026-03-26 执行证据

• 本地 Linux：target/release/dbtool --help、target/release/dbtool --version
• SQLite happy path：connect、inspect --schema main、inspect --schema main --table tickets、query、export --format csv|json
• SQLite failure path：missing file、permission denied、missing table、multi statement blocked、export overwrite blocked
• SQLite connect failure path：non-db file 现在返回非零退出码，并输出 connection failed: file is not a database
• SQLite seed：examples/scripts/bootstrap-sqlite.sh 使用 Node fallback 成功重放
• Linux artifact：dist/dbtool-0.1.0-x86_64-unknown-linux-gnu.tar.gz checksum 通过，解包后二进制 --help / --version 通过
• 宿主机 Docker smoke：根据 CMP-17 的 2026-03-26 评论，PostgreSQL happy path 与 MySQL happy path 已在具备 Docker 的宿主机完成，推荐执行路径已被验证成立
• 宿主机 Unicode 复核：后续 patched-run 已确认 dbtool query / dbtool export 在干净重建 + 显式 UTF-8 导入后可正确显示中文与 emoji，因此此前宿主机乱码结论已被后续证据覆盖
• MySQL 修复离线回归：cargo test -p db-drivers mysql_ 通过，覆盖 mysql_connection_enforces_utf8mb4_session 与 mysql_string_values_preserve_multilingual_utf8
• CLI 回归：cargo test -p dbtool-cli 13 个测试全部通过；cargo build -p dbtool-cli --release 成功，target/release/dbtool --help / --version 通过
• bootstrap 脚本修复：examples/scripts/bootstrap-mysql.sh 已显式加入 --default-character-set=utf8mb4，且 bash -n examples/scripts/bootstrap-mysql.sh 通过
• 新宿主机线索：根据 CMP-22 与 CMP-23，干净重建后 dbtool 命令在宿主机已报告通过
• 宿主机 patched-run 证据：根据 CMP-23，SHOW VARIABLES LIKE 'character_set_%' / collation_% 已留档；MySQL 官方 CLI、dbtool query、dbtool export 都正确显示 张敏、权限验证、emoji smoke 😀
• 当前 runner 能力盘点：node v24.14.0 存在；docker 不在 PATH；Rust toolchain 可经显式 PATH 使用；本地端口 127.0.0.1:53306 与 127.0.0.1:55432 当前均关闭
• MySQL live retest blocker：对 127.0.0.1:53306 执行 connect、happy-path query、SHOW VARIABLES LIKE 'character_set_%'、SHOW VARIABLES LIKE 'collation_%' 均返回 Connection refused (os error 111)
• 当前 runner 复核：examples/scripts/bootstrap-sqlite.sh、target/release/dbtool connect --driver sqlite ...、inspect --schema main、query --file examples/sql/sqlite/happy_path_query.sql 再次通过
• 当前 runner 导出复核：已有文件时 export 明确拒绝覆盖；改用 examples/tmp/qa-export-2.csv 后导出 4 行成功，内容与 EXPECTED_RESULTS.md 一致

平台矩阵

场景	Linux	macOS	Windows	备注
安装 / 构建	本地 Linux 已验证	待验证	待验证	GitHub workflow 已配置，macOS / Windows runner 未在当前环境执行
CLI 启动	本地 Linux 已验证	待验证	待验证	--help / --version 已纳入 release-smoke workflow
PostgreSQL	宿主机 Docker smoke 已验证	待验证	待验证	证据源为 CMP-17
MySQL	宿主机 Docker smoke 已验证	待验证	待验证	happy path 与 Unicode patched-run 均已验证；当前剩余工作是跨平台 release 证据
SQLite	本地 Linux 已验证	待验证	待验证	本地 query / export happy path 已验证
导出流程	本地 Linux 已验证	待验证	待验证	CSV / JSON 本地已验证，跨平台产物仍待 CI 实测

当前阻塞

• 阻塞 1：当前 agent 环境无法执行 GitHub 的 macOS / Windows runner，因此 release artifact matrix 还缺跨平台实测证据。
• 阻塞 2：发布 workflow 已落地，但仍需真实 CI 运行记录与 QA 证据来关闭发布前验收风险。