dbtool-cli-v1/FAILURE_PATH_EVIDENCE_TEMPLATE.md

# PostgreSQL / MySQL Failure-Path Evidence Template

日期：2026-03-28  
作者：Senior Backend Engineer  
用途：`dbtool-usable-v1` 在 PostgreSQL / MySQL failure-path 上补齐可审计证据，供 QA / CTO 直接复用。

配套样例：`FAILURE_PATH_EVIDENCE_SAMPLE.md`

## 1. 适用范围

- 当前仅覆盖 `connect`、`query` 的 failure-path。
- 目标是把 release gate 中“PostgreSQL / MySQL failure-path 仍缺可审计执行证据”这条 blocker 收口为可执行清单。
- 不扩展产品范围，不引入新能力，不替代 `SMOKE_RUNBOOK.md` 的 happy-path 验证。

## 2. 执行前置

- 执行环境：Docker-capable 宿主机（当前 QA runner 仍缺 `docker`）。
- 已完成：
  - `docker compose -f docker-compose.demo.yml up -d postgres mysql`
  - `./examples/scripts/bootstrap-postgres.sh`
  - `./examples/scripts/bootstrap-mysql.sh`
- CLI 可执行：
  - 推荐 `./target/release/dbtool`
  - 或 `cargo run -q -p dbtool-cli -- <args>`
- 若想减少人工整理，可直接运行：

```bash
scripts/qa/run-failure-path-evidence.sh ./target/release/dbtool all ./tmp/failure-path-evidence
```

脚本会为 6 个场景分别生成 `.out` 与 `.md` 证据文件，便于直接贴回 issue 评论。
当前 helper 还会把可检测到的密码泄露模式直接判成 `fail`：

- 错误密码场景：对原始密码值做精确匹配
- 真实密码场景：检查常见泄露模式，例如 `password=<value>`、`"password":"<value>"`、`:<value>@`
- 若 `Binary Version`、`Commit SHA`、`Branch`、`Host` 等 traceability 字段缺失或退化为 `unknown-*`，helper 也会直接判成 `fail`

若执行环境不是宿主机直连，而是 sidecar container / 自定义网络路径，可覆盖默认 host / port：

```bash
DBTOOL_POSTGRES_HOST=postgres \
DBTOOL_POSTGRES_PORT=5432 \
DBTOOL_MYSQL_HOST=mysql \
DBTOOL_MYSQL_PORT=3306 \
scripts/qa/run-failure-path-evidence.sh ./target/release/dbtool all ./tmp/failure-path-evidence
```

若当前 QA runner 只能通过 Docker daemon + sidecar 网络接入数据库，也可直接运行：

```bash
scripts/qa/run-failure-path-evidence-sidecar.sh ./target/release/dbtool ./tmp/failure-path-evidence
```

该脚本会：

- 重新导入 PostgreSQL / MySQL demo 数据
- 创建 sidecar container 加入 `dbtool-cli-v1_default`
- 在 sidecar 内调用 `scripts/qa/run-failure-path-evidence.sh`
- 将生成的 `.out` / `.md` 证据包复制回本地输出目录
- 继承宿主发起侧的 host / binary / version / commit / branch 标签，避免 sidecar 与 host-run 两条路径出现双口径 traceability

## 3. 追溯字段（每条证据都要填）

- Date (UTC):
- Operator:
- Host:
- Execution Path:
- Binary Path:
- Binary Version (`--version`):
- Commit SHA:
- Branch:
- Driver:
- Scenario ID:
- Command:
- Exit Code:
- Key Output:
- Verdict (`pass` / `fail`):

说明：

- helper 当前会自动生成并校验这些字段中的大部分内容。
- 若生成结果出现 `unknown-version`、`unknown-commit`、`unknown-branch`、`unknown-host` 或空值，应视为 traceability 不完整。
- `Execution Path` 推荐使用：
  - `host`
  - `sidecar`

如需先确认 helper 与 sidecar wrapper 的离线夹具回归仍通过，可直接运行：

```bash
scripts/qa/test-failure-path-fixtures.sh
```

## 4. 场景矩阵

| Scenario ID | Driver | Command | Failure Type | JSON Expectation |
| --- | --- | --- | --- | --- |
| `PG-CONN-AUTH-001` | postgres | `connect` | 错误密码 | `status=error`, `state=error`, `error.kind=authentication` |
| `PG-CONN-NET-001` | postgres | `connect` | 不可达端口 | `status=error`, `state=error`, `error.kind=connection` |
| `PG-QUERY-SQL-001` | postgres | `query` | 坏 SQL / 不存在对象 | `status=error`, `state=error`, `error.kind=query` |
| `MY-CONN-AUTH-001` | mysql | `connect` | 错误密码 | `status=error`, `state=error`, `error.kind=authentication` |
| `MY-CONN-NET-001` | mysql | `connect` | 不可达端口 | `status=error`, `state=error`, `error.kind=connection` |
| `MY-QUERY-SQL-001` | mysql | `query` | 坏 SQL / 不存在对象 | `status=error`, `state=error`, `error.kind=query` |

说明：

- `status` 是 envelope 级结果（`success` / `error`）。
- `state` 是共享状态映射（失败路径应为 `error`）。

## 5. 命令模板

先设置正确密码，再按场景覆盖：

```bash
export DBTOOL_PASSWORD=dbtool
```

### PostgreSQL

错误密码：

```bash
export DBTOOL_PASSWORD=wrong-password
./target/release/dbtool connect --driver postgres --host 127.0.0.1 --port 55432 --database dbtool_demo --username dbtool --password-env DBTOOL_PASSWORD --result-format json
```

网络不可达：

```bash
export DBTOOL_PASSWORD=dbtool
./target/release/dbtool connect --driver postgres --host 127.0.0.1 --port 59999 --database dbtool_demo --username dbtool --password-env DBTOOL_PASSWORD --result-format json
```

坏 SQL：

```bash
export DBTOOL_PASSWORD=dbtool
./target/release/dbtool query --driver postgres --host 127.0.0.1 --port 55432 --database dbtool_demo --username dbtool --password-env DBTOOL_PASSWORD --file examples/sql/postgres/failing_query.sql --result-format json
```

### MySQL

错误密码：

```bash
export DBTOOL_PASSWORD=wrong-password
./target/release/dbtool connect --driver mysql --host 127.0.0.1 --port 53306 --database qa_demo --username dbtool --password-env DBTOOL_PASSWORD --result-format json
```

网络不可达：

```bash
export DBTOOL_PASSWORD=dbtool
./target/release/dbtool connect --driver mysql --host 127.0.0.1 --port 59998 --database qa_demo --username dbtool --password-env DBTOOL_PASSWORD --result-format json
```

坏 SQL：

```bash
export DBTOOL_PASSWORD=dbtool
./target/release/dbtool query --driver mysql --host 127.0.0.1 --port 53306 --database qa_demo --username dbtool --password-env DBTOOL_PASSWORD --file examples/sql/mysql/failing_query.sql --result-format json
```

## 6. 证据记录模板

````md
### <Scenario ID>

- Date (UTC):
- Operator:
- Host:
- Binary Path:
- Binary Version:
- Commit SHA:
- Branch:
- Command:
- Exit Code:

Output (excerpt):
```json
{
  "status": "error",
  "operation": "connect",
  "state": "error",
  "error": {
    "kind": "authentication"
  }
}
```

Verdict:
- Expected:
- Actual:
- Result: pass | fail
````

## 7. 收口标准

- 上述 6 个场景每个至少一条可审计记录。
- 每条记录都包含追溯字段和命令输出摘要。
- `USABLE_EVIDENCE_LEDGER.md` 的 PostgreSQL / MySQL failure-path 行更新为 `verified` 或明确保留 `blocked` 原因。
- `USABLE_RELEASE_GATE.md` 的对应 blocker 条目同步更新。
- 若使用 `scripts/qa/run-failure-path-evidence.sh`，仍需人工确认生成的 `Result`、traceability 字段与场景归类是否与实际执行一致，再回填到共享台账。