# 前端验证矩阵

运行时验证前加载本参考。

## 验证层

只选择适用的验证层，但跳过时必须说明原因。

| 验证层 | 证据 | 常见检查 |
|---|---|---|
| 契约/Schema | 生成 Diff 或校验器输出 | OpenAPI/GraphQL/Schema 生成、序列化、必填/可选字段 |
| 静态检查 | 退出码和诊断 | Format、Lint、Typecheck、禁止模式扫描 |
| 单元/组件 | 测试报告 | 业务规则、Hooks、组件、错误映射、竞态和取消 |
| 构建 | 退出码和构建输出 | 生产 Bundle、SSR/RSC 边界、生成路由和资源 |
| 集成/E2E | 浏览器报告或 Trace | 用户路径、鉴权、路由、Mutation 和缓存失效 |
| 视觉 | 稳定截图 Diff 或审查清单 | Token、间距、字体、溢出和响应式布局 |
| 无障碍 | 自动报告 + 人工结果 | 名称、角色、Label、焦点、键盘、对比度、播报和减少动画 |
| 性能 | 实测 Trace 或预算结果 | Bundle 变化、长任务、请求瀑布、渲染和相关 Core Web Vitals |
| 安全/隐私 | 审查证据 | XSS、授权、PII、密钥、不安全 URL/上传和第三方变化 |

## 运行时状态矩阵

每个相关用户动作按需覆盖：

- 初始和加载；
- 成功；
- 空数据和无权限；
- 校验错误和服务端错误；
- 部分数据和过期数据；
- 慢网、离线和超时；
- 重试和取消；
- 双击、快速导航和重复提交；
- 前进/后退和刷新；
- Session 过期或权限变化；
- 长文本、本地化、大列表和图片失败；
- 相关的移动端、桌面端、缩放和方向变化。

## 浏览器验证流程

1. 使用基于 Role、Label 和可见意图的稳定选择器；只有界面完全没有语义替代时才用坐标点击。
2. 断言用户可观察结果，不要断言实现细节。
3. 保存控制台错误、未处理 Promise、失败请求、响应状态和关键请求体；敏感字段必须脱敏。
4. 失败时或首次重试时保存 Trace（工具支持时）。
5. 截图基线必须使用一致的操作系统、浏览器、字体和运行环境；环境不同就做语义视觉审查，并披露无法确定像素差异。
6. 只有支持策略要求时才运行 Chromium、Firefox 和 WebKit；模拟不同 Viewport 不等于覆盖不同浏览器引擎。

## 无障碍验证流程

自动化只能发现部分问题，还必须结合：

1. 纯键盘流程和可见焦点；
2. Dialog、Drawer、错误、路由变化和删除后的合理焦点；
3. 有意义的名称、角色、状态和错误关联；
4. 异步更新的屏幕阅读器播报策略；
5. 200% 缩放和文字重排；
6. 减少动画；
7. 对比度和非颜色提示；
8. 触控目标和指针替代方式。

## 失败分类

- `IMPLEMENTATION`：产品代码违反契约或运行预期。在当前范围内修复。
- `SPECIFICATION`：来源冲突或验收未定义。停止受影响行为并请求决定。
- `TEST`：选择器、Fixture、时序、断言或基线错误。修测试，但不要弱化需求。
- `ENVIRONMENT`：缺服务、凭证、浏览器、种子数据或支持平台。保留证据并报告精确前置条件。

不要为了让 `TEST` 或 `ENVIRONMENT` 问题消失而修改产品实现。