--- name: devlab-web-deep-acceptance description: "存量 Web 系统深度功能验收方法论（L1-L4）。registry 功能点驱动 + 唯一入口执行器 + 假成功嗅探 + 三对齐审计，覆盖盘点建模、用例固化、失败五分类路由、多会话认领协作。与 devlab-web-test-e2e（绿field 用例生成）分工：本技能面向已有系统的全功能点深度验收与回归资产管理。实战陷阱全量清单见 references/REFERENCE-PITFALLS.md。触发词：深度测试、深度验收、功能验收、L1-L4、registry、三对齐、假成功、deep acceptance" --- # devlab-web-deep-acceptance — 存量系统深度功能验收 ## Purpose 对一个**已经存在、功能繁多、质量未知**的 Web 系统做"每个页面、每个按钮、每个接口贯通"的深度验收， 并沉淀**可重放的回归资产**（功能点 registry + 用例文件 + 报告 + 全局 dashboard）。 与 `devlab-web-test-e2e` 的分工：绿field 新项目用例从零生成走前者；存量系统"先盘点登记再分级深测" 走本技能。两者可先后衔接（先用本技能验收存量，新增功能走前者增量生成）。 **实证规模**：本方法论在某 30+ 模块微前端系统落地，登记 689 功能点（pass 64%/blocked 28%）， 实战陷阱 72 条全量收录于 `references/REFERENCE-PITFALLS.md`（执行遇阻先查它）。 ## 适用条件 - 被测系统有浏览器 UI + 后端 HTTP API（SPA / 微前端 / 传统 MPA 均可）； - 可拿到前端源码（盘点要逐按钮读视图代码）与后端数据访问通道（直连 DB 或只读查询代理）； - 执行环境可跑 Node ≥ 18 + Playwright（Chromium）； - 允许在测试库造数（写操作前缀隔离，如 `AUTOTEST_`）。 ## 核心设计（为什么是这套结构） 1. **registry 是唯一事实源**：功能点状态（todo/pass/fail/blocked）+ 根因 reason + 执行注注释全部登记在 `registry/.yaml`，执行器回写、报告生成、dashboard 聚合都从它出发。权威信息绝不写在 会被覆盖的生成物（SUMMARY）里。 2. **唯一入口七模式**：`node run.js [--dry-run|--precheck|--seed|--case|--all|--audit|--cleanup]`， 新增模块零改执行器——只加 registry + cases。 3. **HTTP 200 ≠ 业务成功**：后端代理吞异常返 200+空/null 是存量系统最常见假成功，框架内置 响应体六态分诊与假成功嗅探（只观测不改判定，由用例结合语义判读）。 4. **探索一次即固化**：每个 pass/fail 功能点必须有 `.case.js` 可重放，收尾 `--audit` 三对齐审计 （status × 用例文件 × 报告）防"探索后漏固化"静默混过。 5. **blocked 是一等公民**：不可修问题不判 fail，走五分类根因 + pending-issues 闭环，registry 标 blocked 写清解锁条件，释放执行流继续推进。 ## 目录结构规范 ``` test/e2e/ ├── run.js # 唯一入口执行器（scripts/ 拷贝） ├── e2e.config.js # 环境配置（baseUrl/凭据/API 前缀/DB 通道/豁免表） ├── registry/ │ ├── modules.yaml # 模块总账（多会话认领制） │ └── .yaml # 功能点唯一事实源 ├── cases//.case.js # 用例（探索即固化） ├── cases//_helpers.js # 模块专属原语（噪声表/页面适配） ├── lib/ # 框架库（browser/session/assert/report/precheck/api-common） ├── data/factory/.js # 造数工厂（--seed 调用） ├── reports// # 功能点报告 + SUMMARY.md + PRECHECK.md ├── tools/ # 一次性探针 probe-*（结论固化后移 _archive/）与可复用工具 └── docs/pending-issues.md # 跨功能点问题闭环（P0-P3 分级） ``` ## 七阶段工作流 ### Phase 0 — 系统画像盘点（不写任何用例） 1. **范围核验（强制）**：验证范围以"实际部署的后端服务"为准（如 Git 追踪的模块清单）。 前端有入口但后端未部署的模块标 `out_of_scope`，否则会产出永远修不好的 FAIL。 2. 摸清系统形态：SPA 还是微前端（子应用按需注册？路由挂载检测怎么做）、登录机制 （表单/SSO/Token）、前端路由清单来源（源码 routers 目录）、后端 API 前缀 （如 `/emas/ms//`）、DB 通道（直连 JDBC / 只读 HTTP 代理）。 3. 建立 `e2e.config.js`（从 `scripts/e2e.config.example.js` 拷贝改值）。 4. 产出：系统画像笔记 + modules.yaml 初稿（模块清单 + 路由线索 + 优先级 P0-P3）。 ### Phase 1 — registry 建模（盘点 > 写码） 1. 读前端路由源码拿 route → component 映射（模块 id 与路由文件名不一定对应，找不到用中文标题 grep）。 2. **逐按钮读 Vue/React 视图源码**：每个 button/link/tab/树交互、每个 v-if 守卫、每个 API 调用 列成功能点；不要按"表格思维"预设功能点（无表格页按真实形态等价替换）。 3. 静态排雷：盘点期跑"视图→API 模块"死调用比对（复制残留页的 mounted 死调用 L1 必炸， 不用等运行期）；标注路由参数驱动页（`$route.params` 刷新即空，必须链式导航进入）。 4. 写入 `registry/.yaml`（schema 见 `references/REFERENCE-REGISTRY-SCHEMA.md`）： 顶层 `app:` 锚点、`backend_mappers`（预检输入）、pages[].features[]（id 带页面缩写前缀保证 模块内全局唯一）、`# 执行注:` 注释承载关键事实。 5. **用户抽查确认后开测**——registry 质量决定全盘质量。 ### Phase 2 — 预检（不拉浏览器的静态/DB 检查） ```bash node run.js --precheck ``` 从 `backend_mappers` 扫 mapper/SQL 文件，四段检查（退出码 0 全过 / 3 有缺失项 / 2 通道故障）： 1. **方言静态扫描**：目标 DB 不支持的方言形态（如 PG→Oracle：`over(partition by)` 缺 order by、 `::` 强转、`limit`、`ilike`），高置信计入退出码。空表时这些缺陷被短路不求值，造数后才爆雷。 2. **表存在性批扫**：FROM/JOIN 抽取物理表 ↔ `all_objects` 比对。缺表 → 接口呈"200+空假成功"， 预判 blocked，**不要误判"数据空需造数"白跑造数**。 3. **自定义函数存在性**：`f_/fn_` 前缀引用 ↔ FUNCTION/PROCEDURE/PACKAGE。 4. **列存在性**：`alias.col` ↔ `all_tab_columns`（仅无歧义别名直连物理表，宁漏勿误报）。 报告落 `reports//PRECHECK.md`；DB 通道不可用时降级为仅静态段并注明。 详见 `references/REFERENCE-FALSE-SUCCESS.md` 第三节。 ### Phase 3 — 分级执行 ```bash node run.js --dry-run # 必先行：登录+导航+路由挂载检测+功能点清单 node run.js # 默认执行 fail/blocked/todo（跳过 pass） node run.js --case # 单点调试 node run.js --all # 全量回归（自动保护带 reason 的终态 fail 不被间歇覆写） ``` - **L1→L4 逐功能点**（分级硬条件见 `references/REFERENCE-GRADING.md`）； - **探索一次即固化 `.case.js`**——用例文件按 `cases//.case.js` 映射； - 案例级重试：`--retry N`（默认 2）仅对 fail 重跑，重试成功判 pass 并注记 "环境重试N次后通过"（间歇抖动兜底，持续失败仍 FAIL）； - FAIL 自动截图 `reports//-fail.png`； - 破坏性用例排在依赖它的用例之后（registry 声明顺序即执行顺序）； - 高危操作（不可逆审批/设备下发）：硬闸拦截 + 降级到弹窗/表单层验证；🔒 HUMAN-DECISION [HD-1] ——只有用户显式批准后，才允许对 `AUTOTEST_` 前缀记录真实提交（细节见陷阱 26/27）。 ### Phase 4 — 假成功甄别（贯穿执行全程） - monitor 内置**假成功嗅探**：业务 API（`config.businessApiPattern` 匹配的 JSON 响应） HTTP 2xx 但 body `code!=200` 或 `result:null` 时记入 `collect().swallowed`，自动附到报告 `[假成功嗅探]` 段——**只观测不改判定**（result:null 对部分写接口是合法空返回）。 - 依赖查询结果的用例必须**主动解析响应体**（六态分诊 `bodyVerdict`： no-hit / http:N / code:500 / result:null / empty / data），不能指望 HTTP 状态码兜底。 - 完整分诊决策树（含统计页 200+空三分法、入库断链判定）见 `references/REFERENCE-FALSE-SUCCESS.md`。 ### Phase 5 — 三对齐审计（收尾必跑） ```bash node run.js --audit # 纯文件操作不拉浏览器；违规退出码 3 ``` 规则：pass/fail 必须有 `.case.js`（可重放）与报告；blocked 必须有 reason（五分类标签+解锁命令）； todo 不查。再人工**四对齐核数**：registry 终态 × SUMMARY × 总账 progress 三方数字一致 （历史终态可能只存在于旧 SUMMARY，以带日期的 SUMMARY 为事实源回填 registry 并加执行注）。 ### Phase 6 — 报告回写与全局视图 - 执行器自动**文本级回写** registry（就地替换 status/last_run/reason，**不用 yaml.dump 重写**—— 注释是经验载体；写回前 js-yaml 回验，失败放弃落盘 + 醒目告警 + 退出码 3）； - SUMMARY 从**回写后的 registry 终态聚合**（本轮执行过的用本轮结果，未执行的用终态补齐注明来源）； - 总账 modules.yaml 回写 progress + 释放认领；全局覆盖率看 `docs/e2e-dashboard.md` （`node tools/dashboard.js` 自动生成，勿手改）； - 不可修问题登记 `docs/pending-issues.md`（格式见 `references/REFERENCE-BLOCKED-TAXONOMY.md`）。 ## 失败五分类路由表 | 根因类 | 判定依据 | 处置 | |--------|---------|------| | 前端 | JS 报错/组件未挂载/请求体拼错 | 修视图/API 层 → 部署 → 重跑该功能点 | | 后端-SQL | API 500 + SQL 异常（方言/缺列缺表） | 修 mapper（可配 devlab-dao-sql-compat）→ 部署 → 重跑 | | 后端-逻辑 | 500/400 非 SQL | 修 service 或登记 pending-issues 标 blocked | | 数据 | 200 但空/脏/缺前置 | 先按三分法甄别（断链/缺表/日期组织域）→ 造数工厂补造 | | 环境 | 服务 down/网关不通/间歇抖动 | 停下上报等恢复；间歇重试成功入豁免表（须写明"为什么不是本页缺陷"） | 约束：同一功能点修复**最多 3 轮**，超过登记 pending-issues 标 blocked 继续下一个，不死磕。 ## 用例编写模式 ```js const H = require('./_helpers'); module.exports = { async run({ page, monitor, assert, session, feature }) { await H.gotoPage(page, session, feature.page.route); monitor.reset(); // 注意：L1 用例 reset 勿放在导航后，会清掉 mounted 期错误 // ...交互与断言... if (!precondition) throw new Error('BLOCKED:数据类——缺XX，解锁命令：node tools/xxx.js'); assert.noErrors(monitor.collect()); return '一句话结论'; }, }; ``` - **BLOCKED: 协议**：`Error('BLOCKED:<五分类>——<原因+解锁命令>')` 不计失败，回写 blocked； - 同构用例用"规格表工厂 + 薄存根"（`_specs.js` 导出 makeXxx，`.case.js` 只留一行存根）， 复杂用例（L3 写链路/探索型）单独写，别硬塞工厂； - 依赖易耗数据的用例开头自愈补数，保证 `--all` 可重复。 ## 多会话协作（modules.yaml 认领制） - **认领**：挑 `status: todo` 且 `claimed_by: null` 的模块写 `claimed_by/claimed_at` 改 in_progress， commit 即抢占确认；冲突时后提交者换模块。 - **僵尸接管**：`claimed_at` 超 2 天未更新可强制接管（覆写并注明）。 - **接管前残留检查**：`ls cases//` + `git status --short` 看前会话草稿；既有 `_helpers.js` **禁止整文件覆盖**，用增量编辑。 - **编号防撞**：pending-issues 与陷阱追加一律"模块前缀编号/追加前重新取最大号"，禁看会话早期快照。 - 完整协议见 `references/REFERENCE-REGISTRY-SCHEMA.md` 第四节。 ## 环境故障处置（固定规则） 环境故障（dev server 崩溃/后端服务 down/网关不通）🔒 HUMAN-DECISION [HD-2] ——默认 **停下上报等用户恢复，禁止会话自行重启共享服务**（多会话竞相重启已实锤互相冲突）。执行器内置前端 preflight 探活 fail-fast（退出码 2）， 看到 `Fatal: 前端未就绪` 按本条处置。等待期间做不依赖环境的工作（写用例/盘点/报告）。 唯一例外：代码修复后的部署走 CI 流水线，不属于环境问题。 ## Human Decisions | ID | 决策点 | 触发条件 | 默认 | |----|--------|----------|------| | HD-1 | 高危写操作真实提交 | 用例涉及不可逆审批/设备下发/批量写 | 必问（默认硬闸拦截，降级到弹窗/表单层验证） | | HD-2 | 环境故障是否协助重启 | preflight 探活失败/共享服务 down | 停下上报等恢复（禁止会话自行重启共享服务） | 结构化同源定义见 `decisions.yaml`。 ## References | 文件 | 内容 | 何时读 | |------|------|--------| | `references/REFERENCE-GRADING.md` | L1-L4 分级定义与硬条件、等价替换规则 | Phase 1 建模 / Phase 3 写用例 | | `references/REFERENCE-FALSE-SUCCESS.md` | 假成功六态分诊、200+空三分法、入库断链、precheck 机制 | Phase 2/4 必读 | | `references/REFERENCE-REGISTRY-SCHEMA.md` | registry/modules.yaml 完整 schema、回写规范、多会话协议 | Phase 1/6 | | `references/REFERENCE-BLOCKED-TAXONOMY.md` | 五分类路由、blocked reason 规范、pending-issues 闭环 | Phase 3/6 | | `references/REFERENCE-PITFALLS.md` | 72 条实战陷阱（五段式），按主题分组 | 执行遇阻先查 | | `references/REFERENCE-INDEX.md` | references 导航索引 | 找文档入口 | ## Scripts 与 Templates - `scripts/run.js` + `scripts/lib/*` + `scripts/tools/dashboard.js` + `scripts/e2e.config.example.js`： 拷贝到项目 `test/e2e/` 即得执行器骨架（通用化版本，环境差异全部走 e2e.config.js）。 - `templates/`：registry-module / modules / case / SUMMARY / pending-issues / dashboard 六件套模板。