# 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 方案，再进入实现。