107 lines
6.3 KiB
Markdown
107 lines
6.3 KiB
Markdown
# 阶段 ⑥ 验证与质量门（Validation & Quality Gates）
|
||
|
||
> **定义**：用**最小且与最终改动相关**的检查验证结果：每个改动映射到覆盖其行为/不变量/风险的检查并实际执行；失败必须可复现、可定位、有因果诊断；修复后**同一检查**复验。验证在真实交付边界之外只算"局部证据"。
|
||
> **输入**：⑤ 的实现产物（diff + 自测结果）+ ① 的验收标准（AC 映射）。
|
||
> **输出**：验证记录（检查身份 + argv/cwd + 结果 + 覆盖的不变量）、审查结论。
|
||
> **进入下一阶段（⑦ 交付与发布）**：全部质量门通过、审查无阻塞项。
|
||
|
||
---
|
||
|
||
## 1. 要求（Requirements）
|
||
|
||
### 1.1 进入条件
|
||
- 实现已满足 ⑤ 的 DoD（自测全绿、变更矩阵已同步）。
|
||
|
||
### 1.2 完成条件（DoD）
|
||
- [ ] 每个实质改动映射到最小且覆盖它的项目检查（单测/契约/集成/E2E/视觉/迁移/打包之一），并在最后一次编辑后运行
|
||
- [ ] 验证失败按"复现 → 定位（可归因的诊断）→ 因果假设 → 最小 owner 修复"链处理；重试不加诊断 ≠ 修复证据
|
||
- [ ] 修复后在最终状态上**重跑同一检查**（或记录等价性理由）
|
||
- [ ] 评审（dk-review 四维）完成：正确性/一致性/安全/测试，无未解决的阻塞项
|
||
- [ ] 门禁结果与最终修订绑定（不是"跑过"而是"这个 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 静态 | typecheck（`npm run typecheck`：tsc --noEmit + 双 tsconfig） | 每次提交 |
|
||
| L1 单测 | 组件/工具/逻辑（vitest，colocated `*.test.ts`，`npm test`） | 每次提交 |
|
||
| L2 契约/守卫 | 跨进程契约对齐（`src/main/ipc-alignment.test.ts`）、迁移守卫（`migrations.test.ts`）、架构守卫（`architecture-guardrails.test.ts`）、docs 基线 | 触碰共享层/迁移 |
|
||
| L3 集成 | 主进程+渲染、宿主装配 | 主链路 |
|
||
| L4 E2E | `npm run test:e2e`（playwright，需先构建） | 关键用户流/发布前 |
|
||
| L5 打包冒烟 | `build/ci-local.ps1`（Windows）/ `build/ci-local.sh`（macOS/Linux）：干净安装+全量门禁+安装包+启动冒烟 | 发布前 |
|
||
|
||
> 本仓测试体系单一事实源：`docs/architecture/testing-architecture.md`；E2E 执行线见 `docs/e2e/e2e-architecture-and-automation.md`。验证要求按此落地，发现矩阵缺口在阶段 ⑧ 反馈。
|
||
|
||
### 3.3 交付物清单
|
||
- 验证记录（含失败→修复→复验链）
|
||
- 审查结论（dk-review 输出，阻塞项清零）
|
||
- 测试覆盖增量说明（新增测试对应的 AC/BR/E）
|
||
|
||
---
|
||
|
||
## 4. 反模式
|
||
|
||
- **陈旧/无关验证**：拿旧结果或全量套件当"这次改动"的证据。
|
||
- **只重试不诊断**：失败重跑过了就提交，没有定位因果。
|
||
- **修完不复验**：修复可见，但最终修订上没有任何同一检查的重跑。
|
||
- **把本地测试当交付证据**：真实接受边界（CI/合并/发布）未被打开时，用 `Unobserved` 而非编造缺失的 PR/部署。
|
||
- **裁判即选手**：模型目测自己生成/操作的 UI。
|
||
|
||
---
|
||
|
||
## 5. 轻量路径（小改动）
|
||
|
||
- 一行修复：对应单测 + 全量 typecheck + 该模块相关测试，记录即可。
|
||
- 任何改动都不得跳过 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)
|