droboticflow/docs/agents/verification.md

56 lines
6.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 分层验证
适用于日常功能开发、修复及本批改动交付。发布仍使用 [release.py 流程](../release/README.md)。
## 工作步骤
1. 开工时用几句话确定业务结果、兼容范围、任务基线和风险。普通小改动不另写长计划;在已授权范围内连续完成实现、验证、修正。
2. `npm run verify:plan -- --base <任务起点提交>` 查看范围。默认 `HEAD` 只包含未提交改动;交付已提交任务时必须指定任务起点,不能用干净树的空计划证明已提交代码通过。
3. 编辑过程中运行 `npm run verify:quick -- --base <任务起点提交>`。相关单元测试被合并、去重执行;不默认启动浏览器、Mongo 或长时压测。
4. 本批完成后运行 `npm run verify:task -- --base <任务起点提交>`,集中验证受影响的真实业务流程。失败只修复并重跑有关部分;新改动影响其他范围时扩大验证。
5. 跨模块集成或公共依赖变化时运行 `verify:integration`。最终报告列出通过、失败、待验证和日志路径;部署单独执行发布门禁。
命令支持 `--plan`(不执行)及 `--budget-seconds N`。默认执行预算:quick 180 秒、task 600 秒、integration 3600 秒;预算耗尽会停止进程组并报告待验证,不自动重跑或改成通过。冷编译、安装依赖和机器负载会影响耗时,预算不是延迟承诺。
## 风险与完成标准
| 变更 | 开发检查 | 本批完成还需确认 |
| --- | --- | --- |
| 文档、纯样式 | 差异/格式检查 | 界面样式实际查看正常与错误状态;文案遵循现有最简规则 |
| 交互、状态和页面切换 | 类型、有关单元回归 | 一条覆盖进入、操作、退出的真实浏览器流程 |
| 领取、权限、保存、校验、返工 | 相关接口和规则回归 | 隔离存储、冲突、失败恢复及旧数据兼容 |
| 查询、轮询、缓存 | 结果等价回归 | 相同代表性规模的查询量、扫描量、耗时、取消及并发对照 |
| 工作流、迁移、资源或容量 | 专项验证 | 在途任务、回退和恢复;生产写入按具体授权执行 |
风险取决于行为和影响面,不按行数判断。共享工作台页面可能同时影响多个流程,脚本会扩大映射;确认只是文案/样式时可记录实际差异与人工检查,执行有关检查并说明未运行项,不把整批列为全通过。
120 人完整作业、8 小时运行、媒体容量和节点故障属于专项验收:容量承诺、相关架构或资源变更时执行,不绑定每次普通功能提交。发布基础门禁未因本规则减少。
## 选择与兜底
- 映射的唯一配置为 `scripts/verification-scopes.json`;当前覆盖审查切换、源校验/个人池、搜索分页、标注编辑、审核决定和统计面板。
- Git 检测包含起点以来提交、暂存、未暂存、未跟踪文件,重命名检查新旧路径。改动的前端测试和 Go 同名测试自动加入。CSS 不因单纯样式修改启动全套类型/业务测试。
- 未映射的前端代码扩大到前端基线门禁,未映射 Go 实现扩大到所属包;浏览器流程仍需人工核对。其他未映射行为报告待验证,补充映射或专项证据后才算交付完成。
- 退出码 0 仅表示所选检查通过;1 表示检查失败;2 表示超时、跳过、未映射、执行中源码变化或入口异常。报告中的 deferred/notCovered 始终保留,不把快速通过解释成完整通过。
- 遇到已有测试债务,使用既有 `test:frontend:gate` / `test:go:gate` 比较具体用例。不因失败而扩大 known-failures 基线,不手工忽略断言。
## 检查选择与环境初始化
标准开发入口与本地验证先检查并补齐当前 worktree 的 Husky wrappers,复用依赖目录也执行该步骤。自定义 hooksPath 保持原样并报告冲突;CI、导出源码和显式 HUSKY=0 保留原有行为。
快速 Go 检查按包内实际用例展开范围规则,交互预览、Mongo、浏览器及容量用例由专项入口处理。任务映射显式声明所需 opt-in 环境;执行器清理继承的测试开关,避免误连外部服务。领取池 Mongo 等价和大载荷回归在任务级执行,也由 CI 的隔离 Mongo 服务执行。
独立检查在其他项失败或跳过后继续执行,报告保留每一项结果;依赖检查仅在前置检查通过后执行。例如构建失败时,生产产物启动检查标为未运行,避免读取旧 dist。预算耗尽仍停止后续执行,失败和未完成仍决定最终退出码。
浏览器门禁共用解析器:优先 BROWSER_EXECUTABLE,兼容 BROWSER_PATH;Mac 优先使用已安装的 Edge/Chrome,其余环境优先使用已安装的 Playwright Chromium,再查找本机 Chromium 浏览器。显式路径无效会报错。倍速回归默认创建并清理临时本地 Vite 服务,也支持显式指定本地测试 URL。
## 减少重复与环境准备
- 同一批同一输入只做一次成功验证;优先复用已有 npm 测试组、Go 编译/测试缓存和本地隔离 Mongo 服务,不为每次小改动重装依赖、重建镜像或重启整套副本。
- 浏览器/数据库测试串行运行,继续使用各自独立合成数据和清理机制。共享服务不等于共享业务状态;公司集群和 BOS 不用于这些写入测试。
- 日志及 JSON 报告写入忽略目录 `local-data/test-results/verify-*`,包含命令、基线、源码摘要、环境摘要、工具版本、安装锁文件摘要、耗时和未覆盖项。原始环境值不写入报告。
- 同任务内复用记录前,核对源码/测试/夹具、依赖安装、配置、工具版本、测试环境均未变化。源码摘要和环境摘要不是依赖安装或外部数据状态的证明。此入口不做跨运行的自动“免测缓存”;Go 自有缓存正常使用。浏览器、数据库和生产证据按各自环境重新核验。
- 更换依赖、修复失败、修改夹具、出现新问题或范围扩大时,重跑相关检查。测试报错、跳过和未启动永远不是可复用的成功证据。
此流程不增加日常审批。普通本地修改、测试及本地提交持续推进;推送、PR、公司部署、生产数据和资源修改仍遵循 `AGENTS.md` 的授权边界。