feat(usable): integrate current dbtool implementation snapshot

Co-Authored-By: Paperclip <noreply@paperclip.ing>

plans/2026-03-28-cmp-46-backend-runtime-audit.md

@@ -0,0 +1,69 @@
+# 2026-03-28 `CMP-46` backend runtime audit
+
+日期：2026-03-28  
+作者：Senior Backend Engineer  
+对应 issue：`CMP-46`
+
+## 1. 审计目标
+
+- 盘点当前领域模型与持久化边界
+- 验证 demo 后端基础能力是否足以支撑产品化收口
+- 优先识别运行环境、数据兼容和核心后端正确性风险
+
+## 2. 当前 backend 边界结论
+
+### 领域与共享契约
+
+- `crates/db-core` 负责 `ConnectionTarget`、`InspectRequest`、`QueryRequest`、`ExportRequest` 与基础错误模型。
+- `crates/db-config` 负责连接 profile、密码环境变量注入与脱敏摘要。
+- `crates/db-drivers` 负责 PostgreSQL / MySQL / SQLite 差异实现，不向上暴露原生驱动细节。
+- `crates/db-app` 负责共享应用编排，并冻结 `connect / inspect / query / export` 与 `running / success / empty / error` 状态契约。
+- `apps/cli` 当前仅承接参数解析、输出渲染和退出码，不重定义共享业务语义。
+
+### 持久化边界
+
+- 当前仓库没有应用自有持久化 schema。
+- 当前仓库没有 migration 目录，也没有需要演进的数据迁移链。
+- 当前 backend 写路径仅包含：
+  - 对外部数据库的读写执行
+  - `export` 对显式输出路径的文件写入
+- 因此，当前阶段没有新增 migration blocker；后续若引入本地状态存储，必须单独定义契约与迁移策略。
+
+## 3. 本轮验证
+
+先设置当前 runner 的真实 Rust 环境：
+
+```bash
+export CARGO_HOME="$AGENT_HOME/.cargo"
+export RUSTUP_HOME="$AGENT_HOME/.rustup"
+export PATH="$AGENT_HOME/tools:$CARGO_HOME/bin:/paperclip/.cargo/bin:${PATH}"
+unset CARGO_REGISTRIES_CRATES_IO_PROTOCOL
+. "$CARGO_HOME/env"
+```
+
+执行结果：
+
+- `cargo test --workspace`：通过，52 tests passed
+- `cargo run -q -p dbtool-cli -- query --driver sqlite --path /tmp/notfound.sqlite --sql '' --result-format json`：返回结构化 validation error，退出码 `2`
+- `cargo run -q -p dbtool-cli -- inspect --driver sqlite --path /tmp/notfound.sqlite --table accounts --result-format json`：返回结构化 validation error，退出码 `2`
+
+## 4. 新发现
+
+### 环境漂移
+
+- 当前 runner 的可用 Cargo / Rustup 实际位于 `$AGENT_HOME/.cargo` 与 `$AGENT_HOME/.rustup`。
+- 旧的 `/home/node/.cargo` 假设在当前 runner 不成立，会导致验证命令失败。
+- 当前 shell 还注入了空字符串 `CARGO_REGISTRIES_CRATES_IO_PROTOCOL`；若不先 `unset`，cargo 会直接报 `unsupported registry protocol`。
+
+### backend 正确性
+
+- 本轮没有发现新的 shared-app / CLI contract defect。
+- 本轮没有发现新的持久化或 migration blocker。
+- 当前 remaining gap 仍是 PostgreSQL / MySQL failure-path 证据补齐，而不是后端实现回归。
+
+## 5. 当前 backend 优先级建议
+
+1. 继续冻结 `db-app` 共享结果/状态契约，不在 `CMP-46` 混入功能扩张。
+2. 继续把验证重点放在 failure-path evidence，而不是重做 happy path。
+3. 把 runner 级环境前置条件写死到 backend 验证说明，避免后续 agent 重复踩坑。
+4. 若后续出现本地状态持久化需求，必须先单独拆 schema / migration 方案，再进入实现。