mini-openclaw/docs/project-process/06-validation.md

# 阶段 ⑥ 验证与质量门（Validation & Quality Gates）

> **定义**：用**最小且与最终改动相关**的检查验证结果：每个改动映射到覆盖其行为/不变量/风险的检查并实际执行；失败必须可复现、可定位、有因果诊断；修复后**同一检查**复验。验证在真实交付边界之外只算"局部证据"。
> **输入**：⑤ 的实现产物（diff + 自测结果）+ ① 的验收标准（AC 映射）。
> **输出**：验证记录（检查身份 + argv/cwd + 结果 + 覆盖的不变量）、审查结论。
> **进入下一阶段（⑦ 交付与发布）**：全部质量门通过、审查无阻塞项。

---

## 1. 要求（Requirements）

### 1.1 进入条件
- 实现已满足 ⑤ 的 DoD（自测全绿、变更矩阵已同步）。

### 1.2 完成条件（DoD）
- [ ] 每个实质改动映射到最小且覆盖它的项目检查（单测/契约/集成/E2E/视觉/迁移/打包之一），并在最后一次编辑后运行
- [ ] 验证失败按"复现 → 定位（可归因的诊断）→ 因果假设 → 最小 owner 修复"链处理；重试不加诊断 ≠ 修复证据
- [ ] 修复后在最终状态上**重跑同一检查**（或记录等价性理由）
- [ ] 评审（正确性/一致性/安全/测试四维）完成：正确性/一致性/安全/测试，无未解决的阻塞项
- [ ] 门禁结果与最终修订绑定（不是"跑过"而是"这个 revision 过了"）

---

## 2. 规则（Rules）

### 2.1 验证选择

| 编号 | 规则 |
|---|---|
| R-6.1 | **相关验证**：最终改动必须被最小且直接覆盖其行为的检查验证；跑一个无关的大套件或陈旧结果不算（旧结果、全量套件、agent 一句"done"都不是验证证据）。 |
| R-6.2 | **分层选择**：按"快/慢、便宜/昂贵"分层（lint/typecheck/单测 → 契约/集成 → E2E → 打包冒烟），agent 能按改动选择正确层；慢 e2e 本身不坏，坏的是它成为唯一反馈。 |
| R-6.3 | **失败的顺序链**：`failure → reproduction → diagnosis → bounded repair`，缺一不可；一条重试就过了但没有诊断的修复，不构成修复证据。 |
| R-6.4 | **修复后复验**：同一检查（或证明覆盖同一行为与范围的等价检查）在修复后的最终状态重跑；无失败无修复则记 `N/A` 并附相关验证结果。 |
| R-6.5 | **验证是机器事实**：命令身份（argv/cwd）、fixture、修订号、结果、覆盖的不变量都要保留；CI 身份与本地等价性记录在案。 |

### 2.2 质量门（Quality Gates）

| 编号 | 规则 |
|---|---|
| R-6.6 | **机制强制优先于文档**：架构/安全/schema/迁移/生成物漂移等规则用测试与静态检查强制（architecture test、契约 diff、迁移 lint、生成物 drift check），只写进文档不算门禁。 |
| R-6.7 | **门禁与修订绑定**：必须过的检查（lint/typecheck/单测/关键 E2E/构建）在合并前对最终修订全绿；绕过门禁必须有记录的理由。 |
| R-6.8 | **测试断言真实行为**：测试断言行为与不变量，不只是冒烟（跑通≠通过）；live/真实设备用例必须有 skip 守卫，禁止依赖本机路径/凭据。 |
| R-6.9 | **UI 验证裁判独立**：驱动与观察分离；同一模型驱动又目测自己的截图不算 pass（详见 [04-ui-spec.md](04-ui-spec.md) §4）。 |

### 2.3 评审

| 编号 | 规则 |
|---|---|
| R-6.10 | 评审顺序：正确性（边界/错误处理/并发/资源泄漏）→ 一致性（风格/命名/契约同步）→ 安全（注入面/密钥落日志）→ 测试（新行为有测试锁定）。 |
| R-6.11 | 只报有证据的问题，按严重度分组（阻塞/建议/可选），每条带 `文件:行号` 与可执行建议；没有问题的维度明确说"未发现问题"。 |

---

## 3. 输出规范

### 3.1 验证记录模板

```text
改动（diff/修订号）
  检查清单：  检查身份 | 命令(argv/cwd) | 覆盖的不变量 | 结果 | 时间
失败记录：    失败检查 → 复现步骤 → 诊断/日志身份 → 因果 → 修复 diff → 复验结果
残余风险：    未覆盖范围、跳过守卫的用例、需人工确认项
```

### 3.2 验证分层与实际入口

| 层 | 内容 | 触发 |
|---|---|---|
| L0 静态 | git diff --check；npm run build包含类型检查；文档链接/编号/事实检查 | 对应改动后 |
| L1 单测 | 在backend工作目录用其venv执行python -m unittest discover -s . -p test_*.py -v；建议由verify统一执行 | 后端行为修改 |
| L2 契约/守卫 | backend/test_assistant_components.py等已有测试与scripts/test_*.cjs；按新契约增加反例 | 契约/权限/页面规则修改 |
| L3 集成 | API + services + 临时测试数据库/fixtures，禁依赖真实客户库 | 主链路 |
| L4 E2E | 真实浏览器按本批用例操作并断言，记录实际入口/环境；当前未确认统一E2E套件 | 关键用户流 |
| L5 打包冒烟 | Docker Compose config；获授权后独立资源上运行verify.py --docker，另做目标环境验收 | 发布前 |

> 实际总入口为 `scripts/verify.py`：项目backend/venv执行，日志在test-evidence。当前没有package.json中的typecheck、test或test:e2e脚本，不得写成已执行。新版测试规划见 [v2验证](../v2/06-validation.md)。行为修改必须跑总入口，纯文档可用相关链接/编号/路径/diff检查。

### 3.3 交付物清单
- 验证记录（含失败→修复→复验链）
- 审查结论（四维逐项记录；独立评审未完成须说明，不能自称已获他人批准）
- 测试覆盖增量说明（新增测试对应的 AC/BR/E）

---

## 4. 反模式

- **陈旧/无关验证**：拿旧结果或全量套件当"这次改动"的证据。
- **只重试不诊断**：失败重跑过了就提交，没有定位因果。
- **修完不复验**：修复可见，但最终修订上没有任何同一检查的重跑。
- **把本地测试当交付证据**：真实接受边界（CI/合并/发布）未被打开时，用 `Unobserved` 而非编造缺失的 PR/部署。
- **裁判即选手**：模型目测自己生成/操作的 UI。

---

## 5. 轻量路径（小改动）

- 小行为修复：对应测试 + scripts/verify.py，保留完整日志；纯文档：链接、编号、事实与diff检查。
- 任何改动都不得跳过 R-6.3/R-6.4（诊断与复验）与 R-6.7（门禁）。

---

## 6. 相关文档

- 输入：阶段 ⑤ [05-implementation.md](05-implementation.md)、规格 [01-requirement.md](01-requirement.md) 的 AC
- UI 验证细则：阶段 ④ [04-ui-spec.md](04-ui-spec.md) §4
- 通过后进入：阶段 ⑦ [07-delivery.md](07-delivery.md)

变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。