188 行
16 KiB
Markdown
188 行
16 KiB
Markdown
# 测试规约与回归门禁
|
||
|
||
**文档状态**：当前测试事实源。
|
||
**适用范围**：hyb-oa MVP 首轮开发 A3-A8，以及后续所有非微小改动。
|
||
**路线口径**：WFOC/DBWFOC/WFDG/WDRG/WEGOV1/WROAD2 后，HR/考勤员工日常审批优先复用企业微信成熟能力，OA 做自建留存、按域镜像、人工接管、恢复回写、财务闭环和审计中台；报销、采购、合同、项目、PDF OCR、付款批次、AP 台账、代账交接和高敏附件继续由 OA 主办；企业微信只做脱敏消息和 OA deeplink；飞书不进入当前路线。后续企微/OA 运行时迁移前必须先读 [企微优先开发路线图](./企微优先开发路线图.md)，再做对应 POC。WEGOV1 后，WAPC2/WCBK1 不能直接进入 `wecom_attendance_approval_mirror_v1`；WACP3、WREAD1、WADM1、WARCH1 和 WARCH2 已完成请假/补卡补偿、可读性、模型设计、最小历史留存和正式只读查询。WROAD2+OPS 先做测试账号 3 天每日巡检，完整镜像仍需 WARCH3、WCHECK1、WEXT1 和单独合同。WPROC2 后先跑 `check-process-contract` process gate；缺配置或权限时记录 `NEEDS_CONFIG` 或 `SKIP/BLOCKED_BY_EXTERNAL_CONFIG`，不得伪造成通过。
|
||
|
||
本文回答“什么时候测试、测什么、怎么判定通过、怎么记录跳过”。具体业务验收仍以主 PRD、模块规约和当前 Trellis task PRD 为准；历史 Issue CSV 只作追溯或外部导出兼容材料。
|
||
|
||
## 1. 基本原则
|
||
|
||
- 测试不是 A8 才开始；每个 Trellis task 完成开发后必须立即按 `Test Plan` 验证。
|
||
- A8 是总回归和试运行门禁，用来证明 A2-A7 组合后仍然可用。
|
||
- 自动化优先，自动化无法覆盖时必须写清人工步骤、执行人、环境和结论。
|
||
- 测试失败不得假通过；必须先归类为代码问题、测试桩问题、环境问题、数据问题或人工配置问题。
|
||
- 涉及公网、企业微信真机、真实 OCR、真实凭据时，只能在条件真实可用后给通过结论；缺配置必须标 `SKIP`。
|
||
- 企微审批类测试默认禁止自审；自动化样件必须预检申请人和审批人不是同一 OA 员工、不是同一企微 userid。
|
||
|
||
## 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. Trellis task 内测试时机
|
||
|
||
| 时机 | 必做动作 |
|
||
| --- | --- |
|
||
| 开发前 | 确认 Trellis task PRD 已写清 `Acceptance`、`Test Plan`、依赖和回滚说明 |
|
||
| 后端改完 | 跑 Prisma 校验、相关 `node --check`、相关单测或回归脚本 |
|
||
| 前端改完 | 跑 `typecheck`、`build`，涉及页面时跑相关 Playwright |
|
||
| UI 或入口改完 | 做 PC、移动或企业微信 UA 视觉验证 |
|
||
| Review 前 | 确认 diff 只包含当前 Trellis task 范围，失败测试已修复或明确阻塞 |
|
||
| 回填 DONE 前 | `Test Plan` 已执行并通过，或有明确 SKIP 证据 |
|
||
| Commit 前 | `git diff --check` 通过，Trellis task 状态和检查记录已反映真实结果 |
|
||
|
||
Trellis task `status=completed` 表示开发、复核、回归和归档已完成；历史 Issue CSV 的 `Dev_Status=DONE`、`Review1_Status=DONE`、`Regression_Status=DONE` 仅按旧审计口径解释。
|
||
|
||
### 3.1 企微工程化测试门禁
|
||
|
||
WPROC1 后，企微 HR/考勤相关 Issue 在测试层面同步执行三层门禁：
|
||
|
||
| 门禁 | 测试要求 |
|
||
| --- | --- |
|
||
| 路线门禁 | 测试前核对路线图，确认没有跳过 WAPC2F、WCBK1、WEGOV1、WACP3、WREAD1、WADM1、WARCH1 等前置阶段。 |
|
||
| 能力门禁 | runner 必须输出真实 `PASS`、`NEEDS_CONFIG` 或 `SKIP/BLOCKED_BY_EXTERNAL_CONFIG`，不能把缺 Secret、权限、可信 IP、模板、回调或可见范围写成通过。 |
|
||
| 实现门禁 | Trellis task PRD、静态检查、单测、回归、公网验证、检查记录和中文提交必须按 `Test Plan` 闭环。 |
|
||
|
||
WPROC2 把上述要求固化为自动化 process gate：
|
||
|
||
- 基线门禁：`node scripts/qa/check-process-contract.mjs --baseline`，已接入 `scripts/check-minimal.sh`。
|
||
- 历史/外部 CSV 兼容门禁：`node scripts/qa/check-process-contract.mjs --issue <csv> --profile <profile> --json`，仅在当前任务明确包含 legacy/export CSV 时使用。
|
||
- WAPC2F 必须使用 `wecom-approval-fixture` profile；后续企微高风险合同至少使用 `wecom` profile。
|
||
|
||
Definition of Ready：
|
||
|
||
- Trellis task PRD 已写清主流程、异常流程、权限、外部配置和脱敏报告边界。
|
||
- 已明确 API、Secret、可信 IP、模板、回调、测试账号、申请人、审批人和自审校验。
|
||
- live 写入必须有显式 CLI 参数和环境开关；默认 dry-run 或只读。
|
||
|
||
Definition of Done：
|
||
|
||
- `Test Plan` 全部执行并记录实际结果。
|
||
- 自动化能覆盖的样件生成、复跑、只读拉取、脱敏检查和错误分类已自动化执行。
|
||
- 人工只保留批准、密钥/回调配置、企微后台不可 API 化配置、真机确认和风险拍板。
|
||
- 若面向公网或企微可测，必须有 `/ready`、runtime smoke、public bundle scan 或对应 live runner 证据。
|
||
|
||
高风险企微能力的 POC 顺序固定为：WAPC2F 自动样件 -> WAPC2FLIVE live 创建与 WAPC2 自动复跑 -> WCBK1 回调只读 POC -> WEGOV1 企微主办治理与自建留存路线修正 -> WACP3/WACP3R 补偿拉取 POC -> WREAD1 审批可读性与误审批防护门禁 -> WADM1 自建留存/镜像数据模型设计 -> WARCH1 最小自建历史留存实现 -> WARCH2 正式只读历史查询 -> WROAD2/WARCH3/WCHECK1 受控巡检和打卡摘要 -> WROAD2-BIZ1 三天业务冒烟 -> WAPPR1 审批规则规范化 -> WRULE1 审批链校验器 POC -> WAUTO1 自动证据汇总 -> WEXT1LD 外出/加班 live 前 dry-run -> WFULLSMOKE1 三天全域最终目标测试 -> WROUTE2 测试号收口到最小镜像路线锁定 -> WTCLOSE2/WTCLOSE2F 远端可信 IP 执行口径修正 -> WREMOTE1/WFULLSMOKE2 远端收口 -> WEXT1-FORMAL 正式模板外出/加班测试 -> WREAL1 小范围真实试用（首批 1 名真实员工 + 1 名审批人/管理员观察） -> `wecom_attendance_approval_mirror_v1` 最小完整镜像。当前 WAPC2FLIVE、WCBK1、WACP3R、请假/补卡 WREAD1、WADM1、WARCH1、WARCH2、WARCH3/WCHECK1/WEXT1/WOPS1 均已完成；后续不得跳过三天业务冒烟、审批规则门禁、远端收口、正式模板外出/加班测试、真实试用等独立门禁直接做完整镜像。真实回调必须先证明验签、解密、幂等和重复投递；补偿拉取必须先证明按时间窗口拿到审批单号并可拉详情；可读性门禁必须确认审批消息、列表、详情页和快捷同意/驳回误操作风险；审批规则门禁必须确认申请人不能任意选择审批人、审批人自动带出且非自审；镜像实现前必须先有字段、状态机、幂等键、索引和隐私保留边界设计。
|
||
|
||
WEGOV1 后的企业微信测试环境口径：不假设自建应用有完整隔离 sandbox。自动化优先覆盖 API、回调、补偿拉取、脱敏报告和 OA 留存校验；人工只确认后台不可 API 化配置、真机收到/点击、审批详情是否看得清、正式写入和应急风险拍板。
|
||
|
||
## 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 <validate_issues_csv.py-path> <issue.csv>` | 仅当当前任务包含 legacy/export CSV 时校验通过 |
|
||
| 前端基础 | `cd client && npm run typecheck`、`cd client && npm run build` | 类型和构建通过，Vite chunk warning 不单独阻断 |
|
||
| UI 规则脚本 | `node scripts/qa/check-ui-design-rules.mjs --strict` | 当前 UI 静态规则 0 findings；视觉与交互裁决以 `frontend-design` 为准 |
|
||
| 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 可用。三类不得混用，缺哪一类就写清缺口。
|
||
|
||
QAOPS8 之后，当前门禁台账按四类读取：
|
||
|
||
| 门禁类别 | 当前用途 | 当前状态口径 |
|
||
| --- | --- | --- |
|
||
| 本地门禁 | 代码、mock、隔离库、构建和 Playwright 基线 | 可由自动化证明，但不代表公网或真机通过 |
|
||
| 公网匿名 | `/ready`、public bundle、匿名页面和公网移动矩阵 | 证明部署入口和前端资源可用，不读取凭据 |
|
||
| 带凭据 | live smoke、真实 OCR、角色账号和受保护接口 | 缺凭据、样票或授权时只能记录 `SKIP` |
|
||
| 企业微信真机 | 入口、绑定、免登、deeplink、WebView 和代表设备体验 | 必须有人工或代表设备证据，自动化 UA 不能替代 |
|
||
|
||
### 5.2 历史专项分类
|
||
|
||
| 专项 | 当前归类 | 处理规则 |
|
||
| --- | --- | --- |
|
||
| R108/R109 移动视觉专项 | 历史证据和待修测试初始化 | 不是当前 R7E 硬门禁；初始化 API 不可用时只能记录 `SKIP`，不得写成视觉通过 |
|
||
| R6/MUD6/WCM6 移动专项 | 当前移动基础回归 | MIF7/MIF7T 后仍需保持可运行，用于防止基础移动体验回退 |
|
||
| MIF7/MIF7T 移动整改专项 | 已收口证据和当前矩阵参考 | 作为新移动变更的回归参考，不能替代新增真机验收 |
|
||
| 其他历史专项 | 历史证据 | 重新进入当前门禁前，必须先更新当前 Trellis task 的 `Test Plan` 和验收口径；如需回填历史 CSV，另按 legacy/export 兼容门禁校验 |
|
||
|
||
## 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、提交和交付变更”。
|