chore: bootstrap independent git workflow

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-03-26 03:49:06 +00:00
commit 7424491944
60 changed files with 7793 additions and 0 deletions
--- a/plans/2026-03-25-cli-release-smoke-baseline.md
+++ b/plans/2026-03-25-cli-release-smoke-baseline.md
@@ -0,0 +1,100 @@
+# 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`
--- a/plans/2026-03-25-cmp-9-desktop-gui-foundation-plan.md
+++ b/plans/2026-03-25-cmp-9-desktop-gui-foundation-plan.md
@@ -0,0 +1,46 @@
+# CMP-9 Future Desktop GUI Foundation Plan
+
+日期：2026-03-25  
+作者：Senior Frontend Engineer
+
+## Goal
+
+在不进入完整桌面产品实现的前提下，为 `dbtool-cli-v1` 产出可交付的未来 GUI 基线，供 CTO 和 PM 用于后续项目拆分、契约澄清和范围控制。
+
+## Current Assessment
+
+- 当前仓库没有前端入口、`package.json`、React 应用、桌面壳或任何展示层代码。
+- 当前前端最合适的交付物不是“桌面应用实现”，而是共享信息架构文档、组件边界说明和一个最小可见原型。
+- GUI 必须复用 CLI 已定义的产品概念：连接目标、schema browser、query editor、result set、export action。
+
+## Planned Steps
+
+1. 确认当前仓库没有现成前端基线，并记录约束
+2. 定义桌面端信息架构、主工作区布局和页面边界
+3. 识别 GUI 需要的核心数据契约与状态模型
+4. 交付一个静态可预览的工作台原型，验证布局与信息密度方向
+5. 补充查看方式和界面验收点，方便 CTO / PM / QA 复核
+
+## Output Boundaries
+
+本任务输出：
+
+- GUI 信息架构
+- 主工作区布局方向
+- 组件清单
+- 契约需求清单
+- 静态原型
+- 运行与验收说明
+
+本任务不输出：
+
+- Electron / Tauri 工程初始化
+- React + shadcn/ui 真正应用代码
+- 可连接真实数据库的 GUI
+- 新增或修改后端契约实现
+
+## Validation Rule
+
+- 原型必须可以本地直接预览
+- 文档必须明确“当前无前端基线”的事实
+- 文档必须让后续 GUI 项目可直接拆成页面、组件和契约任务
--- a/plans/2026-03-25-dbtool-cli-v1-delivery-tracking.md
+++ b/plans/2026-03-25-dbtool-cli-v1-delivery-tracking.md
@@ -0,0 +1,92 @@
+# dbtool-cli-v1 里程碑、依赖图与交付跟踪
+
+日期：2026-03-25  
+作者：CTO
+
+## 1. 当前真实状态
+
+- 项目工作区现已存在，但仓库内仍只有产品、QA、计划和 backlog 文档。
+- 当前尚未落地 Rust workspace、`Cargo.toml`、CLI 二进制入口、demo、seed、smoke 或 CI 发布资产。
+- 因此当前阶段不是“实现中后期”，而是“需求和执行顺序已明确，代码基线尚未开始”。
+
+## 2. 里程碑建议
+
+| 里程碑 | 目标 | 对应 issue | 当前状态 | 说明 |
+| --- | --- | --- | --- | --- |
+| M0 | 范围与架构收敛 | `CMP-2`, `CMP-3` | 已完成 | 产品边界和 Rust 架构都已形成共享文档 |
+| M1 | 工程基线可启动 | `CMP-4` | 未开始 | 必须先产出可编译 workspace 和可运行 CLI |
+| M2 | 首个数据库 happy path | `CMP-5` | 未开始 | 先用 PostgreSQL 验证 connect / inspect / query 主链路 |
+| M3 | QA 输入与发布前置基线 | `CMP-10`, `CMP-12`, `CMP-13` | `CMP-10` blocked / `CMP-12` blocked / `CMP-13` in progress | QA 和发布资产可先建文档与 runbook，但受代码基线约束 |
+| M4 | 多数据库覆盖 | `CMP-6`, `CMP-7` | 未开始 | 在统一抽象上补齐 MySQL、SQLite |
+| M5 | 导出闭环与首发准备 | `CMP-8` | 未开始 | 形成可验收的 export 能力并衔接 smoke |
+| M6 | 未来 GUI 准备 | `CMP-9` | 未开始 | 保持 gated，不进入 CLI v1 关键路径 |
+
+## 3. 依赖关系图
+
+### 逻辑依赖
+
+```text
+CMP-2 + CMP-3
+        ↓
+      CMP-4
+        ↓
+      CMP-5
+     ↙     ↘
+CMP-13     CMP-6
+   ↓         ↓
+CMP-10     CMP-7
+     ↘     ↙
+      CMP-8
+        ↓
+      CMP-12
+
+CMP-9 独立存在，但不进入 CLI v1 主路径
+```
+
+### 当前执行关键路径
+
+在当前 owner 分布下，真正会拖慢交付的不是文档依赖，而是后端实现集中度：
+
+`CMP-4` → `CMP-5` → `CMP-6` → `CMP-7` → `CMP-8`
+
+说明：
+
+- `CMP-4` 未完成前，`CMP-12` 只能停留在发布设计层。
+- `CMP-13` 可以先产出 runbook，但没有 CLI 基线时无法形成真实 smoke 输入。
+- `CMP-10` 已有首版验收文档，但真实验证仍依赖后续功能实现。
+
+## 4. 关键风险
+
+### P0
+
+- 代码基线仍为空，当前没有任何可运行、可测试、可发布资产。
+- `CMP-4` 到 `CMP-8` 集中在同一位后端工程师名下，形成天然串行风险。
+
+### P1
+
+- `CMP-10` 和 `CMP-12` 已先进入 blocked，说明 QA 与发布链路会早于功能被卡住。
+- 如果 `CMP-9` 过早推进，会挤占 CLI 主路径注意力并制造范围噪音。
+
+### P2
+
+- 目前缺 demo、seed、smoke、Docker、README 运行说明，后续每个功能 issue 都容易因缺验证入口而返工。
+
+## 5. 各角色第一轮职责
+
+- 后端：先完成 `CMP-4`，再按 `CMP-5` → `CMP-6` → `CMP-7` → `CMP-8` 推进。
+- QA：继续完成 `CMP-13` 的样例与 runbook，并把 `CMP-10` 保持为“文档先行、实测待代码”的状态。
+- 前端：仅推进 `CMP-9` 的未来 GUI 信息架构，不进入 CLI 实现路径。
+- CTO：维护关键路径、阻塞升级、issue 排序和跨角色依赖收敛。
+
+## 6. 状态同步节奏
+
+- 日常节奏：每次 heartbeat 只同步真实状态变化，不做“空刷新”。
+- 里程碑节奏：每完成一个里程碑，立即更新本跟踪文档和 backlog 判断。
+- 阻塞节奏：出现阻塞时，同一 heartbeat 内更新 issue 状态、阻塞原因和上游 owner。
+- 向 CEO 汇报的固定项：当前关键路径、P0 风险、owner 负载集中度、是否需要调整优先级。
+
+## 7. 当前管理判断
+
+- 当前不建议扩编。真实瓶颈仍是“代码基线未启动”，不是“人手已经证明不足”。
+- 当前最该做的是尽快让 `CMP-4` 开工并交付最小可编译 CLI。
+- 在 `CMP-4` 完成前，不应把 blocked 的 `CMP-10` / `CMP-12` 误判为执行不力，它们属于合理前置文档工作后遇到的依赖阻塞。
--- a/plans/2026-03-25-dbtool-cli-v1-rust-architecture-plan.md
+++ b/plans/2026-03-25-dbtool-cli-v1-rust-architecture-plan.md
@@ -0,0 +1,264 @@
+# dbtool-cli-v1 Rust 架构方案与执行计划
+
+日期：2026-03-25  
+作者：CTO
+
+## 1. 当前真实落地情况
+
+- Paperclip 中已经建立项目 `dbtool-cli-v1`，并已创建第一批工程 issue。
+- 配置中的项目根目录是 `/workspace/repo/dbtool-cli-v1`，但截至今天该目录原本并不存在，说明代码仓库尚未真正初始化。
+- 当前没有可验证的 Rust workspace、可执行 CLI、demo 数据、测试链路、发布链路或跨平台产物。
+- 因此本阶段的真实状态不是“已有实现等待扩展”，而是“需求和任务已经拆出，但代码基线仍未落地”。
+
+## 2. V1 工程目标
+
+V1 只交付 CLI，不交付 GUI。CLI 必须覆盖：
+
+- 连接 PostgreSQL、MySQL、SQLite
+- 浏览 schema / table / column
+- 执行临时查询
+- 执行脚本
+- 导出 CSV / JSON
+
+当前阶段明确 gated：
+
+- 完整桌面 GUI
+- 插件系统
+- 多进程或服务化架构
+- 复杂 ORM / migration 编排
+
+## 3. 推荐 Rust workspace 结构
+
+```text
+dbtool-cli-v1/
+  Cargo.toml
+  Cargo.lock
+  README.md
+  plans/
+  backlog/
+  apps/
+    dbtool-cli/
+      Cargo.toml
+      src/
+  crates/
+    db-core/
+      Cargo.toml
+      src/
+    db-drivers/
+      Cargo.toml
+      src/
+    db-config/
+      Cargo.toml
+      src/
+  examples/
+    fixtures/
+    scripts/
+  .github/
+    workflows/
+```
+
+### crate 边界
+
+#### `apps/dbtool-cli`
+
+- 命令行入口
+- 参数解析
+- 表格/文本输出
+- 调用 `db-core` 用例
+- 初期先承载导出命令编排，避免过早拆出额外 crate
+
+#### `crates/db-core`
+
+- 领域模型：连接配置、schema 树、查询请求/响应、导出请求
+- 通用错误模型
+- 驱动能力 trait
+- 应用层用例：connect、inspect、query、run-script、export
+
+#### `crates/db-drivers`
+
+- PostgreSQL / MySQL / SQLite 的具体实现
+- 对 `db-core` trait 的适配
+- feature flag 控制三类数据库依赖
+- 统一管理连接池、SQL 方言差异和 introspection SQL
+
+#### `crates/db-config`
+
+- 连接 profile
+- DSN 解析
+- 本地配置文件读写
+- 环境变量覆盖逻辑
+
+## 4. 驱动抽象策略
+
+V1 不做插件化驱动系统，也不做单独驱动进程。采用“核心 trait + 三个内建实现”的最小可行方案。
+
+### 建议抽象
+
+- `DatabaseKind`
+- `ConnectionProfile`
+- `DatabaseDriver`
+- `CatalogIntrospector`
+- `QueryExecutor`
+
+### 设计原则
+
+- `db-core` 只定义能力和标准化返回结构，不依赖具体数据库类型。
+- `db-drivers` 内部按 `postgres`、`mysql`、`sqlite` 模块实现，但对上层暴露统一入口。
+- 不使用过度抽象的通用连接层来抹平所有数据库差异；差异应在驱动层显式处理并记录。
+- 不把 CLI 输出格式、表格渲染、交互提示放进核心 crate。
+
+### 技术选型
+
+- 异步运行时：`tokio`
+- CLI 参数：`clap`
+- 数据库访问：优先采用 `sqlx`，因为它原生覆盖 PostgreSQL、MySQL、SQLite，能减少多套驱动栈带来的维护成本
+- TLS：默认 `rustls`
+
+备注：`sqlx` 当前官方仓库明确覆盖 PostgreSQL、MySQL、SQLite；打包链路可在仓库稳定后再接入 `cargo-dist`，当前不建议先引入额外发布复杂度。
+
+## 5. 依赖关系与推进顺序
+
+### Phase 0：建基线
+
+1. 初始化 Rust workspace
+2. 跑通 CLI 二进制和 `--help`
+3. 建立基础 README、开发说明、样例目录
+
+### Phase 1：建公共能力
+
+1. 定义 `db-core` trait 与标准返回结构
+2. 完成 `db-config`
+3. 建立驱动 contract test 基座
+
+### Phase 2：按数据库逐个接入
+
+1. PostgreSQL
+2. MySQL
+3. SQLite
+
+顺序理由：先做服务型主路径，再覆盖文件型数据库差异。
+
+### Phase 3：补全导出与稳定性
+
+1. CSV / JSON 导出
+2. demo fixtures
+3. smoke runbook
+4. 跨平台打包
+
+## 6. 测试策略
+
+### 单元测试
+
+- `db-config`：profile 解析、环境变量覆盖、路径处理
+- `db-core`：查询参数、错误转换、导出请求校验
+
+### contract test
+
+- 对三种数据库复用同一组行为测试：
+  - 连接成功
+  - 连接失败
+  - schema 列举
+  - table 描述
+  - 简单查询
+  - 参数化查询
+  - 导出
+
+### 集成测试
+
+- PostgreSQL / MySQL：使用容器启动测试实例
+- SQLite：使用临时文件数据库
+
+### CLI smoke test
+
+- `dbtool connect`
+- `dbtool inspect`
+- `dbtool query`
+- `dbtool export`
+
+CLI 输出建议用 snapshot 测试保护，但只用于稳定文本输出，不替代行为测试。
+
+## 7. 打包与发布策略
+
+当前不需要“部署”，需要的是“发布可执行 CLI”。
+
+### 第一阶段
+
+- 先用 CI matrix 生成 macOS、Linux、Windows release binary
+- 每个平台至少执行一次 `--help` smoke test
+- 产出压缩包和 checksum
+
+### 第二阶段
+
+- 当命令面稳定后，再接入 `cargo-dist` 统一发布描述和产物整理
+
+这个顺序比一开始就引入复杂发布工具更稳妥。
+
+## 8. 前后端与 QA 第一轮职责
+
+### 后端
+
+- 初始化 workspace
+- 定义核心抽象
+- 按 PostgreSQL → MySQL → SQLite 顺序交付驱动
+- 落地导出能力
+- 建立打包流水线
+
+### 前端
+
+- 不做 GUI 实现
+- 产出未来桌面端信息架构
+- 明确连接管理、schema browser、query editor、results table 的交互边界
+- 提前识别未来 GUI 对 CLI / core 层的契约要求
+
+### QA
+
+- 建立跨数据库验收矩阵
+- 落地 demo fixtures 与 smoke runbook
+- 对 connect / inspect / query / export 建可重复回归路径
+
+## 9. 与现有 issue 的对应关系
+
+### 已有 issue
+
+- `CMP-4`：初始化 Rust workspace
+- `CMP-5`：PostgreSQL
+- `CMP-6`：MySQL
+- `CMP-7`：SQLite
+- `CMP-8`：CSV / JSON 导出
+- `CMP-9`：未来 GUI 信息架构
+- `CMP-10`：跨数据库验收矩阵
+- `CMP-11`：里程碑、依赖图和交付跟踪
+
+### 已补充的 issue
+
+- `CMP-12`：CLI 打包、发布与跨平台 smoke 流水线
+- `CMP-13`：demo 数据库、样例脚本与 smoke runbook
+
+## 10. 当前关键风险
+
+### P0
+
+- 项目路径之前不存在，说明仓库尚未初始化，`CMP-4` 是所有实现工作的真实前置
+
+### P1
+
+- 产品范围文档 `CMP-2` 尚未完成前，部分命令细节和验收文字仍需与 PM 对齐
+- 当前只有一名后端工程师，驱动接入和发布链路都压在同一人身上，关键路径较长
+
+### P2
+
+- 没有 demo fixtures 时，QA 和后续 smoke automation 难以尽早稳定
+
+## 11. 招聘建议
+
+当前先不建议立即扩编。
+
+原因：
+
+- 现阶段瓶颈是仓库初始化、架构收敛和第一条实现链路，不是人手数量
+- 在 PostgreSQL 主链路和 CI/发布链路跑通前，新增工程师的边际收益有限
+
+触发招聘的条件：
+
+- `CMP-4` 到 `CMP-5` 跑通后，后端仍被 MySQL / SQLite / release pipeline 长时间阻塞
+- 或 GUI 方向从“设计基线”升级为并行实现项目
--- a/plans/2026-03-25-pm-v1-sequencing.md
+++ b/plans/2026-03-25-pm-v1-sequencing.md
@@ -0,0 +1,15 @@
+# dbtool-cli-v1 PM Sequencing
+
+## Recommended Delivery Order
+
+1. bootstrap an empty but runnable Rust CLI workspace
+2. establish a shared connection and inspection model
+3. ship PostgreSQL happy path for connect, inspect, and query
+4. reach MySQL parity on the same workflow
+5. reach SQLite parity with documented structural differences
+6. add CSV and JSON export on top of query results
+7. validate the cross-database acceptance matrix before any GUI follow-on
+
+## Sequencing Rule
+
+Do not start GUI execution work until the CLI acceptance path is stable enough to validate the product workflow end to end.
--- a/plans/2026-03-25-qa-cmp-13-demo-runbook-plan.md
+++ b/plans/2026-03-25-qa-cmp-13-demo-runbook-plan.md
@@ -0,0 +1,20 @@
+# CMP-13 QA Demo / Smoke Plan
+
+日期：2026-03-25
+
+## Goal
+
+为 `dbtool-cli-v1` 提供可重复的 demo 数据、样例 SQL 输入和 smoke runbook，并明确当前不可执行的阻塞点。
+
+## Planned Steps
+
+1. 盘点当前仓库与共享 QA 基线
+2. 设计跨数据库最小样例数据
+3. 落地 PostgreSQL / MySQL / SQLite seed 资产
+4. 落地本地 bootstrap 与 Docker demo 路径
+5. 落地 smoke runbook 与预期断言
+6. 记录阻塞并同步 CTO / PM
+
+## Exit Rule
+
+如果 CLI 可执行入口和命令契约仍未落地，则本任务输出共享 QA 资产后进入阻塞状态，不伪造“已通过”。
--- a/plans/2026-03-26-cmp-18-git-repo-bootstrap-plan.md
+++ b/plans/2026-03-26-cmp-18-git-repo-bootstrap-plan.md
@@ -0,0 +1,51 @@
+# CMP-18 Git 仓库与 agent 提交推送机制计划
+
+日期：2026-03-26  
+作者：CTO
+
+## 目标
+
+让 `dbtool-cli-v1` 从“已有工作区但没有 Git 边界”切换为“有独立仓库、有远程、有提交规则、有后续可复用 push 机制”的项目。
+
+## 阶段拆解
+
+### Phase 0：仓库边界落地
+
+- 在项目根目录初始化独立 Git 仓库
+- 设定默认分支 `main`
+- 配置远程 `origin`
+- 完成首次受控 commit
+
+### Phase 1：提交与推送治理
+
+- 明确推荐认证方案：HTTPS + bot token
+- 提供最小 `GIT_ASKPASS` 脚本
+- 明确 commit、branch、push、review 规则
+- 明确前端、后端、QA、集成类 issue 的提交责任边界
+
+### Phase 2：平台化复用
+
+- 将本仓库的 Git 工作流沉淀为模板
+- 未来在前端、后端、全栈项目中复用同一认证注入与 branch 规则
+
+## 第一轮职责
+
+- CTO：完成仓库 bootstrap、治理文档、认证方案定稿
+- 后端：按 issue 独立提交后端改动，不再等待“统一代提交”
+- 前端：未来 GUI / Web 项目沿用同一 branch 与 review 规则
+- QA：验证受保护分支下的 smoke / CI gate 是否满足合并要求
+
+## 风险与约束
+
+- 当前未注入 Gitea 写权限凭据，因此本次只验证本地 commit，不验证远程 push
+- 若未来允许 agent push，则必须先在 Gitea 启用 protected branch
+- 若未来一个 issue 涉及多人协作，必须先明确最终集成 owner，避免“都能改、没人收口”
+
+## 完成定义
+
+满足以下条件即可认为 `CMP-18` 达成：
+
+- 本地已是独立 Git 仓库
+- 远程仓库 URL 已明确并配置
+- 共享文档已写清推荐认证与治理规则
+- agent 已完成一次受控 commit
--- a/plans/2026-03-26-qa-runtime-smoke-environment.md
+++ b/plans/2026-03-26-qa-runtime-smoke-environment.md
@@ -0,0 +1,37 @@
+# dbtool-cli-v1 PostgreSQL / MySQL runtime smoke 环境计划
+
+日期：2026-03-26
+
+## 背景
+
+- 当前仓库已具备 `docker-compose.demo.yml`、PostgreSQL / MySQL bootstrap 脚本、fixtures 与 `SMOKE_RUNBOOK.md`
+- QA 已完成 Linux 本地 SQLite smoke，但 PostgreSQL / MySQL runtime smoke 仍因当前 runner 无 Docker 而阻塞
+- 当前问题的根因是**执行宿主缺失**，不是产品功能缺失
+
+## 决策
+
+采用**宿主机执行 + Docker Compose 临时数据库**作为当前标准方案。
+
+- 推荐说明见 `QA_RUNTIME_ENVIRONMENT.md`
+- 不采用长期宿主机数据库作为主路径
+- 不在当前阶段为 `local-db-codex` 增加 Docker runtime
+
+## 第一轮职责
+
+- 后端：保持 compose / seed / SQL 输入稳定
+- QA：在 Docker-capable host 执行 PostgreSQL / MySQL smoke 并回填证据
+- CTO：完成方案裁决、任务拆解与阻塞升级
+- 前端：保持 gated，不进入当前执行链路
+
+## 完成标准
+
+- QA 能按 `QA_RUNTIME_ENVIRONMENT.md` 与 `SMOKE_RUNBOOK.md` 完成 PostgreSQL smoke
+- QA 能按 `QA_RUNTIME_ENVIRONMENT.md` 与 `SMOKE_RUNBOOK.md` 完成 MySQL smoke
+- 若执行仍失败，阻塞必须明确归因到宿主、Docker、二进制或产品缺陷之一
+
+## 2026-03-26 当前执行记录
+
+- 当前 QA runner 已验证存在预编译 `target/release/dbtool`，且 `--help` / `--version` 正常
+- 当前 QA runner 可通过 `examples/scripts/bootstrap-sqlite.sh` 复核 SQLite happy path
+- 当前 QA runner 不存在 `docker`，因此无法拉起 `docker-compose.demo.yml`
+- 当前 QA runner 不存在 `cargo`，因此宿主机执行时需提前准备 Rust toolchain 或直接分发预编译二进制