# dbtool-cli-v1 CLI 发布与跨平台 smoke 基线

> Status: superseded on 2026-03-26 by `RELEASE_RUNBOOK.md` and `.github/workflows/release-smoke.yml`.
> This file captures the initial blocked-state plan and should not be treated as the current release implementation source of truth.

日期：2026-03-25  
作者：Senior Backend Engineer

## 当前结论

- 当前仓库仅包含产品、QA、backlog 与架构计划文档，尚未落地 Rust workspace、`Cargo.toml`、CLI 可执行入口或任何可构建资产。
- 因此 `CMP-12` 当前不能直接实现“真实可运行”的发布流水线，必须先等待 `CMP-4` 交付最小可编译 CLI 基线。
- 同时，跨平台 smoke 的“有意义输入”还依赖 `CMP-13` 提供最小 fixtures / runbook，否则只能做 `--help` 级别的空载校验。

## 当前领域与后端边界盘点

当前已共享、但尚未代码化的后端核心概念来自 `PRODUCT_REQUIREMENTS.md` 与 `plans/2026-03-25-dbtool-cli-v1-rust-architecture-plan.md`：

- 连接目标：`DatabaseKind` + `ConnectionProfile`
- introspection 结果：schema / table / column 元数据树
- 查询执行：`QueryRequest` / `QueryResult`
- 导出：`ExportRequest`
- 发布链路：`ReleaseArtifact` / checksum / smoke result

这些概念目前仍处于“规划已明确、实现尚未开始”的状态。

## 最小可行发布策略

在 `CMP-4` 完成后，发布链路先采用最小 CI matrix，而不是复杂发布系统：

### CI matrix

- `ubuntu-latest`
- `macos-latest`
- `windows-latest`

### 每个平台必须执行

1. 安装稳定 Rust toolchain
2. `cargo build --release`
3. 执行一次 CLI 基础 smoke：
   - `<binary> --help`
   - 可选：`<binary> --version`
4. 打包 release artifact
5. 生成 SHA256 checksum

## 建议的 artifact 规则

在 CLI 名称最终确定前，先使用占位命名规则，避免后续分发混乱：

- Linux: `<cli-name>-<version>-x86_64-unknown-linux-gnu.tar.gz`
- macOS: `<cli-name>-<version>-x86_64-apple-darwin.tar.gz`
- Windows: `<cli-name>-<version>-x86_64-pc-windows-msvc.zip`
- checksum: `<artifact-name>.sha256`

如后续引入 ARM 构建，新增架构后缀，不复用旧命名。

## smoke 边界

当前阶段的 smoke 分两层：

### Level 1：发布前置 smoke

- CLI 可启动
- `--help` 可返回 0
- `--version` 可读取（若已实现）

### Level 2：功能 smoke

依赖 `CMP-13` 的最小 fixtures / runbook，至少覆盖：

- connect
- inspect
- query
- export

在 `CMP-13` 未完成前，不应把 Level 2 写成强制发布门槛。

## 回滚说明

V1 不涉及服务部署，回滚按“产物回滚”处理：

1. 保留上一个已验证 release artifact 与 checksum
2. 若新版本 smoke 失败或 QA 验收失败，停止分发新产物
3. 重新指向上一个可验证版本
4. 在发布记录中标注失败原因、影响平台、是否为构建问题或运行时问题

## 当前阻塞与依赖

- 主阻塞：`CMP-4` 未完成，当前不存在可编译 Rust workspace
- 次阻塞：`CMP-13` 尚在进行中，功能 smoke 输入未稳定
- 风险：若在 CLI 参数与二进制名未稳定前过早固化 workflow，后续会出现大量仅因命名变化产生的流水线噪音

## 建议的后续执行顺序

1. `CMP-4` 先交付可编译 workspace 与可启动 CLI
2. 在仓库中落地 `.github/workflows/release-smoke.yml`
3. 先接入 `--help` / `--version` smoke
4. 等 `CMP-13` 产出 fixtures 后，再把功能 smoke 接入 CI
5. 待命令面稳定后，再评估是否需要 `cargo-dist`