10 KiB
10 KiB
测试规约与回归门禁
文档状态：当前测试事实源。 适用范围：hyb-oa MVP 首轮开发 A3-A8，以及后续所有非微小改动。 路线口径：hyb-oa 是唯一业务主系统和唯一审批中心；企业微信只做入口、身份、通知和打卡原始采集；飞书和企业微信原生审批不进入当前路线。
本文回答“什么时候测试、测什么、怎么判定通过、怎么记录跳过”。具体业务验收仍以主 PRD、模块规约和最新 Issue CSV 为准。
1. 基本原则
- 测试不是 A8 才开始；每个 Issue 完成开发后必须立即按
Test_Method验证。 - A8 是总回归和试运行门禁，用来证明 A2-A7 组合后仍然可用。
- 自动化优先，自动化无法覆盖时必须写清人工步骤、执行人、环境和结论。
- 测试失败不得假通过；必须先归类为代码问题、测试桩问题、环境问题、数据问题或人工配置问题。
- 涉及公网、企业微信真机、真实 OCR、真实凭据时，只能在条件真实可用后给通过结论；缺配置必须标
SKIP。
2. 测试分层
| 层级 | 目标 | 典型手段 | 通过口径 |
|---|---|---|---|
| 静态检查 | 证明代码和配置可解析 | prisma:validate、node --check、typecheck、build、git diff --check |
命令退出码为 0 |
| 单元测试 | 证明局部规则正确 | Vitest route/service/unit tests | 相关用例通过，新增规则有覆盖 |
| 脚本回归 | 证明后端业务链路可跑通 | regression-workflow-actions.sh、regression-dedup.sh、regression-ocr.sh、regression-all.sh |
脚本成功，失败项可追溯 |
| E2E | 证明真实页面流程可用 | Playwright PC、mobile、WeCom UA | 主流程完成，页面状态和接口状态一致 |
| 视觉验证 | 证明页面可用且不割裂 | Playwright 截图、DOM 指标、人工审查 | 无桌面页误入手机、无明显遮挡和溢出 |
| 真机 / 公网 smoke | 证明部署环境可用 | /ready、前端资源、企业微信真机、真实 OCR |
真实条件可用且记录证据；缺条件标 SKIP |
| 人工验收 | 证明业务角色认可 | 员工、审批人、财务、管理员按清单操作 | 验收人确认或记录遗留问题 |
3. Issue 内测试时机
| 时机 | 必做动作 |
|---|---|
| 开发前 | 确认 Issue CSV 已写清 Acceptance、Test_Method、依赖和回滚说明 |
| 后端改完 | 跑 Prisma 校验、相关 node --check、相关单测或回归脚本 |
| 前端改完 | 跑 typecheck、build，涉及页面时跑相关 Playwright |
| UI 或入口改完 | 做 PC、移动或企业微信 UA 视觉验证 |
| Review 前 | 确认 diff 只包含当前 Issue 范围，失败测试已修复或明确阻塞 |
| 回填 DONE 前 | Test_Method 已执行并通过，或有明确 SKIP 证据 |
| Commit 前 | git diff --check 通过，Issue 状态和 Notes 已反映真实结果 |
Dev_Status=DONE 表示开发完成且基础检查通过；Review1_Status=DONE 表示自查或 review 无阻断；Regression_Status=DONE 表示业务流程级验证通过或明确 SKIP。
4. MVP 首轮测试矩阵
| Issue | 自动化测试 | 视觉 / 入口验证 | 备注 |
|---|---|---|---|
| A3 报销发票 OCR 主链路 | regression-dedup.sh、regression-ocr.sh、报销主流程 E2E、发票 OCR E2E |
PC 报销详情、移动报销、上传/OCR 状态、重复提示、付款/导出入口 | OCR 真实 provider 缺配置时标 SKIP，mock 只证明本地链路 |
| A4 企业微信入口绑定通知回 OA | wecom auth 单测、notification dispatcher 单测、WeCom 入口 E2E | 登录页、未绑定提示、移动入口、WeCom UA deeplink | 真机企业微信验证留到 A8 |
| A5 请假补卡外出加班与考勤口径 | leave route 语法、请假流程 E2E、团队日历 E2E | PC 请假、移动请假、团队状态或日历 | 不接企业微信打卡 API，不重造定位和人脸 |
| A6 P1 采购合同项目最小可用 | procurement 回归、采购/项目 E2E、合同台账人工或 E2E | 采购申请、合同台账、项目详情 | 不扩展预算、ERP、AI、复杂招采 |
| A7 权限导航与备用模块护栏 | typecheck、build、权限导航 E2E |
员工、主管、财务、管理员入口对比 | 前端隐藏不能替代服务端权限 |
| A8 总回归门禁 | regression-all.sh、前端 build、web gates、live smoke env check |
PC、移动、企业微信 UA 组合截图 | 未部署不得告知用户可公网或真机测试 |
5. 视觉验证规则
涉及 PC、手机或企业微信 WebView 的页面改动，默认补视觉验证。截图建议放在 output/playwright/<issue-id>/，文件名包含页面、角色和视口。
| 场景 | 视口和入口 | 必查项 |
|---|---|---|
| PC | 1440x960，普通浏览器 | 导航清晰、主流程入口可见、信息密度合适、无内部码值主展示 |
| 手机 | 390x844，普通移动浏览器 | 无桌面宽表、无横向滚动、底部导航不遮挡、按钮可点 |
| 企业微信 UA | iPhone + wxwork UA |
默认进入 /mobile，deeplink 回 OA，未绑定提示可理解 |
| 弹窗 / 表单 | PC 和移动至少各一次 | 文字不截断、不遮挡、不会默认弹键盘影响首屏 |
移动端硬性检查：
scrollWidth <= viewportWidth + 2。- 不出现 PC 侧边栏或桌面表格主体验。
- 不把 UUID、内部状态码、技术错误作为主要展示文案。
- 上传、提交、审批、付款等关键按钮状态清楚。
- 异常提示能指导用户下一步操作。
5.1 当前最小回归组合
R7E 前和后续非微小改动至少从以下组合中按风险选择；进入 R7E Go/No-Go 时必须全部覆盖并记录证据：
| 类别 | 命令或证据 | 口径 |
|---|---|---|
| CSV 合同 | python3 /home/shunli/.codex/skills/plan/scripts/validate_issues_csv.py <issue.csv> |
所有当前 Issue CSV 校验通过 |
| 前端基础 | cd client && npm run typecheck、cd client && npm run build |
类型和构建通过，Vite chunk warning 不单独阻断 |
| 设计规则 | node scripts/qa/check-ui-design-rules.mjs --strict |
当前 UI 设计规则 0 findings |
| MIF7 移动矩阵 | cd client && npx playwright test tests/e2e/dg7-mobile-information-dedupe.spec.ts --workers=1 --reporter=list |
首页、进度/审批、通知、三类详情和财务首页通过；公网时设置 E2E_BASE_URL=https://oa.hyinda.com |
| R6/MUD6/WCM6 移动回归 | r6-mobile-responsive-system-hotfix、r6-mobile-unified-design-rollout、r6-wecom-mobile-rendering-hardening |
旧移动矩阵用于防止信息架构整改破坏基础移动体验 |
| 公网匿名 | /ready、check-public-bundle-copy.mjs |
/ready 成功且 public bundle findings=0 |
| 带凭据 live readiness | LIVE_SMOKE_BASE_URL=https://oa.hyinda.com QA_ISSUE_ID=<id> bash scripts/qa/run-live-smoke-readiness.sh |
live smoke 和真实 OCR 不含 SKIP；pending OCR 可按规则非阻断 SKIP |
| 核心业务流 | BUSINESS_FLOW_GROUPS=reimbursement,approval,leave,procurement,governance bash scripts/qa/run-business-flow-gates.sh local |
工具会话无法稳定承载长组合时，可按相同 groups 分段执行并在报告中引用各分段 PASS 目录 |
门禁分为三类：本地门禁证明代码和 mock/隔离库可用；公网匿名门禁证明部署入口和前端资源可用；带凭据门禁证明真实账号、live smoke 和真实 OCR 可用。三类不得混用，缺哪一类就写清缺口。
5.2 历史专项分类
- R108/R109 移动视觉专项目前归为历史证据和待修测试初始化，不是当前 R7E 硬门禁；若初始化 API 不可用，只能记录
SKIP，不得写成视觉通过。 - 旧 R6/MUD6/WCM6 专项仍作为当前移动基础回归，MIF7/MIF7T 后需继续保持可运行。
- 任一历史专项若重新进入当前门禁，必须先更新对应 Issue CSV 的
Test_Method和验收口径。
6. SKIP 规则
只有确实缺少外部条件时才能标 SKIP。SKIP 不是通过，必须写清原因和后续补测条件。
| 场景 | 可 SKIP 条件 | 必须记录 |
|---|---|---|
| 企业微信真机 | 缺 CorpID、AgentID、可信域名、回调域名、可见范围或手机企业微信账号 | 缺哪个配置、自动化已覆盖哪些、A8 何时补 |
| 真实 OCR | 缺腾讯 OCR 凭据、网络或真实样票授权 | 当前 provider、mock 覆盖范围、真实 OCR 补测步骤 |
| 公网 smoke | 未部署或公网域名不可用 | 本地验证结果、部署前置条件 |
| 生产数据验证 | 无授权、无脱敏样本或存在数据风险 | 不执行原因、需要谁批准 |
7. 失败处理
测试失败后先分类，再决定修复方式：
| 分类 | 处理方式 |
|---|---|
| 代码问题 | 当前 Issue 内修复并重跑相关测试 |
| 测试桩问题 | 修测试夹具或 mock，不能降低真实验收口径 |
| 环境问题 | 记录环境差异，必要时重启本地服务或切换隔离测试库 |
| 数据问题 | 使用 seed、隔离测试库或清理本轮产生的数据；不得直接重置生产库 |
| 人工配置问题 | 记录缺失配置，A8 或部署阶段补测 |
如果失败暴露出超出当前 Issue 的业务缺口，不能顺手扩大实现，应记录到 Notes 或新 Issue。
8. 回填和证据
Issue 状态回填必须基于证据：
Dev_Status=DONE：实现完成，静态检查或对应基础测试通过。Review1_Status=DONE：自查或 review 已确认无阻断风险。Regression_Status=DONE：流程级测试通过，或按 SKIP 规则记录不可执行原因。
最终回复和 commit 前至少说明：
- 改了什么，对应哪个 Issue。
- 跑了哪些命令，结果如何。
- 哪些测试 SKIP，原因是什么。
- 是否部署；未部署时不得引导用户去公网或企业微信真机测试。
9. 与其他文档的关系
- 主 PRD 回答“做什么、为什么、如何验收”。
- 本文回答“如何测试和何时可过门禁”。
docs/试运行与自动化验证手册.md回答“本地、公网、企业微信、真实 OCR 怎么操作”。docs/开发交付与变更管理规约.md回答“如何 review、提交和交付变更”。