feat(usable): package gui-host validation snapshot
Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Paperclip CTO
196
FAILURE_PATH_EVIDENCE_TEMPLATE.md
Normal file
196
FAILURE_PATH_EVIDENCE_TEMPLATE.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# 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`
|
||||
|
||||
## 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 字段与场景归类是否与实际执行一致，再回填到共享台账。
|
||||
Reference in New Issue
Block a user