126 行
10 KiB
Markdown
126 行
10 KiB
Markdown
# 交互规范 Chromium 浏览器回归补跑
|
||
|
||
## Goal
|
||
|
||
补齐 `08-05-interaction-pattern-unification` 归档时因 Chromium 安装/沙箱条件不足而暂停的渲染层证据，证明已交付的交互统一在真实浏览器 DOM、布局、键盘焦点和移动固定动作条上没有回退。结果只用于本地回归和 OpenClaw 验收提词，不代表已部署、公网可测或企业微信真机通过。
|
||
|
||
## Background
|
||
|
||
- 低风险统一子任务的源码合同、`typecheck`、`build`、聚焦 source-contract Playwright 和 Trellis 门禁已经通过；归档记录将需要 Chromium 的浏览器回归明确标为 `PAUSED`。
|
||
- 本次补跑只验证既有实现，不新增业务行为。测试数据、登录态和 API 响应使用现有 E2E 合成夹具或页面路由 mock，不接触真实账号、真实票据或生产数据。
|
||
- 适用事实源为 `docs/测试规约与回归门禁.md`、`docs/试运行与自动化验证手册.md`、`.trellis/spec/hyb-oa/frontend-react-vite-design.md` 和归档子任务的 `prd.md`/`implement.md`。
|
||
- `frontend-design` 是视觉裁决入口；本环境未提供该 skill 时，本任务只依据现有共享组件、已有断言和事实源做保守的渲染验证，不建立新视觉规则。
|
||
|
||
## Scope
|
||
|
||
本任务仅补浏览器级证据，覆盖以下已完成需求触点：
|
||
|
||
- R1/R6：未知 `StatusBadge` 显示“未知状态”，员工在职阶段和 Todo 状态显示自然中文，不把技术枚举作为普通用户主文案。
|
||
- R4：WelcomeDialog 按用户权限/能力过滤入口；无审批权限的合成员工不看到“待我审批”。
|
||
- R9：Portal 区域失败持久显示自然中文、保留输入/页面状态并提供可聚焦的重试入口。
|
||
- R10：`MobileStickyActionBar` 在移动审批、移动报销及 `BusinessEditTemplate` 消费点保持固定底部、安全区、内容留白、主次动作层级、pending/disabled 表达和可点击尺寸；移动详情最后内容不被动作条遮挡。
|
||
- R11：登录、Portal、PC 审批详情、PC/移动报销详情的关键控件可通过键盘到达，焦点可见，label/按钮语义可识别。
|
||
- R14：直接打开 `/travel-requests` 且未显式选择记录时不自动写入第一条 `id`；显式选择的既有查询参数详情行为不在本任务扩展。
|
||
|
||
浏览器矩阵：
|
||
|
||
- PC：至少 `1440x960`；审批详情另覆盖 `1100x768` 与 `1280x800` 的壳层/双栏断点。
|
||
- 移动：`320x568`、`360x740`、`375x667`、`390x844`、`393x873`、`414x896`、`430x932`；至少包含普通移动 UA、iOS/Android 企业微信 UA 模拟。
|
||
- 浏览器引擎：优先仓库 Playwright Chromium；若使用系统 Chromium，必须记录可执行文件、启动参数和结果，不把环境替代方案写成产品证据。
|
||
|
||
## Requirements
|
||
|
||
- RBR1：所有行为测试在 loopback HTTP origin 运行，服务端/前端使用合成数据；禁止公网写入、真实凭据、真实企业微信授权和生产数据库。
|
||
- RBR2：每条测试记录最终 URL、页面主标题或关键 `data-testid`、角色/UA、视口、页面错误计数和关键几何指标（横向溢出、动作条底部间隙、按钮最小高度、焦点目标）。
|
||
- RBR3：移动布局必须满足 `document.documentElement.scrollWidth <= viewportWidth + 2`，详情页隐藏底部 Tab，固定动作条底部间隙不超过 2px，关键按钮高度至少 44px（既有断言允许的 43.5px 下限只作为兼容记录）。
|
||
- RBR4：截图只写入 `output/playwright/08-07-interaction-pattern-browser-regression/`；不得复用或覆盖历史任务证据目录。截图文件名包含页面、角色/UA 和视口。
|
||
- RBR5：键盘回归至少验证登录字段顺序、Portal 主入口与重试按钮、审批转审字段/提交按钮、移动/PC 报销材料查看按钮的焦点移动；焦点环不可因 `outline: none` 或低对比度而不可见。
|
||
- RBR6：测试失败先分类为代码、夹具、环境、数据或人工配置问题；环境缺失只能标 `PAUSED`/`BLOCKED`，不得将未启动浏览器写成 PASS，也不得因环境失败修改业务代码。
|
||
- RBR7：Playwright/企业微信 UA 仅证明普通浏览器模拟行为；代表性 iPhone/Android 企业微信 WebView 仍单独保留为 `PAUSED` 或后续真机任务，不得合并为本任务 PASS。
|
||
|
||
## Acceptance Criteria
|
||
|
||
- [x] A1：Chromium 可启动且本地 Vite/loopback 页面可访问；本轮目标断言使用原始或等价临时 runner 均以退出码 0 完成。R6/R111 未修改的历史 spec 各有一条测试断言问题，已在 `implement.md` 分类并保留失败证据，不归因于产品实现。
|
||
- [x] A2：Portal 员工/管理员合成角色的首屏顺序、WelcomeDialog 权限过滤、区域失败中文提示与重试、键盘焦点均有浏览器证据；页面不显示内部错误 code、接口路径或原始 payload。
|
||
- [x] A3：PC 审批详情的通过/驳回/退回后果说明、转审至少 10 字禁用原因与键盘焦点均通过；取消确认不会调用动作接口。
|
||
- [x] A4：移动审批/报销详情在七个视口完成无横溢、无桌面表格、固定动作条可见、安全区/底部留白和按钮触控尺寸检查；iOS 与 Android 企业微信 UA 模拟均通过。R6/R111 使用未提交临时 runner 仅隔离测试断言问题。
|
||
- [x] A5：PC/移动报销详情材料区、查看按钮焦点、回到审批详情的返回链路和 1440px/1100px/1280px 代表布局通过；截图已写入当前任务目录。
|
||
- [x] A6：差旅直接入口不会自动把第一条记录写入 URL；该结果只证明缺陷已消除，不意味着差旅模块解冻或恢复能力。
|
||
- [x] A7：`client` typecheck/build、任务 validate、流程合同、文档审计、Trellis governance、`git diff --check` 均在本任务收尾时通过；浏览器模拟之外的真机/公网证据按边界保留 `PAUSED`。
|
||
|
||
> 验收证据边界：上述 PASS 仅指本地 Chromium 和企业微信 UA 模拟。代表性企业微信真机 WebView、部署后公网检查和真实账号路径仍保持 `PAUSED`，不能据此告知用户线上或真机可测。
|
||
|
||
## Out of Scope
|
||
|
||
- 不修改 `client/src`、`server/`、API、URL、数据库、权限模型、审批/付款状态机、生产配置或依赖版本。
|
||
- 不新增或迁移业务 E2E 夹具以外的产品能力；不修复发现的超范围业务缺口。
|
||
- 不执行公网部署、真实企业微信登录/消息点击、真实账号/票据/OCR、真实付款或生产数据库操作。
|
||
- 不把现有历史截图目录改名、覆盖、清理或回填为本任务证据。
|
||
- 不把企业微信 UA 自动化、系统 Chromium 或 OpenClaw 结果表述为代表性真机 WebView 通过。
|
||
|
||
## Test Plan
|
||
|
||
### 1. 前置与环境记录
|
||
|
||
1. `command -v npx`、`node --version`、`npm --version`、`npx playwright --version`。
|
||
2. 检查仓库 Playwright Chromium；缺失时仅在获准本地环境执行 `npx playwright install chromium`，记录下载/启动结果。
|
||
3. 启动本地 Vite（或使用 `scripts/qa/run-local-candidate.sh focused` 提供的 loopback 服务），确认 `/login` 可访问；不使用带凭据公网 URL。
|
||
4. 建立并只使用 `output/playwright/08-07-interaction-pattern-browser-regression/` 证据目录。
|
||
|
||
### 2. 聚焦浏览器用例
|
||
|
||
按顺序、单 worker 运行以下既有用例；具体 grep 以测试标题为准，避免把历史专项的无关长流程混入本轮：
|
||
|
||
```bash
|
||
cd client
|
||
npx playwright test tests/e2e/login-portal-ux.spec.ts \
|
||
--grep 'Portal 员工视角优先显示今日动作顺序|Portal 加载失败持久显示自然中文并可重新加载|Portal 新员工只显示轻量欢迎入口' \
|
||
--workers=1 --reporter=list
|
||
npx playwright test tests/e2e/workflow-action-confirm-ui.spec.ts \
|
||
--grep 'PC 审批详情通过、驳回、退回都先解释动作后果' \
|
||
--workers=1 --reporter=list
|
||
npx playwright test tests/e2e/r6-mobile-responsive-system-hotfix.spec.ts \
|
||
--grep '关键移动页面跨视口自适应且首页宫格不挤压' \
|
||
--workers=1 --reporter=list
|
||
npx playwright test tests/e2e/r111-invoice-reimbursement-guard.spec.ts \
|
||
--grep '企业微信手机端保持移动布局，发票和附件能力与 PC 一致' \
|
||
--workers=1 --reporter=list
|
||
npx playwright test tests/e2e/pc-detail-mobile-visual-wave3.spec.ts \
|
||
--grep 'Wave3 移动关键页视觉截图|Wave3 PC 详情和通知中心视觉截图' \
|
||
--workers=1 --reporter=list
|
||
```
|
||
|
||
`r6` 的七个视口和 `r111` 的企业微信 UA 是本任务的移动矩阵主证据；若既有 spec 将截图写向历史目录，执行方必须改用不污染历史证据的临时运行副本或等价 OpenClaw 流程，并把结果收口到当前任务目录，不得直接覆盖历史文件。
|
||
|
||
### 3. OpenClaw 人工/浏览器提词
|
||
|
||
测试提词保存在同目录 `openclaw-test-prompt.md`，要求 OpenClaw：
|
||
|
||
- 使用合成账号/接口 mock 和 loopback 地址；先记录环境，再逐场景执行。
|
||
- 每个场景回报角色、UA、视口、起始/最终 URL、H1 或关键 test id、PASS/FAIL/PAUSED、截图相对路径和发现项。
|
||
- 逐项验证 Portal 权限/重试、审批确认与焦点、移动固定动作条/安全区/溢出、报销材料焦点、差旅不自动选中。
|
||
- 遇到浏览器沙箱、缺失 Chromium、网络或真机条件阻塞时立即停止该场景并写 `PAUSED`，说明重试前置；不得用 DOM 静态读取或源码测试冒充渲染通过。
|
||
|
||
### 4. 收口门禁
|
||
|
||
```bash
|
||
cd client && npm run typecheck && npm run build
|
||
python3 ./.trellis/scripts/task.py validate 08-07-interaction-pattern-browser-regression
|
||
node scripts/qa/check-process-contract.mjs --baseline --json
|
||
node scripts/qa/audit-docs.mjs --check-registry
|
||
node scripts/qa/check-trellis-governance.mjs --json
|
||
git diff --check
|
||
```
|
||
|
||
收口报告必须分开列出：本地源码/静态证据、Chromium 浏览器证据、企业微信 UA 模拟证据、代表性真机证据、公网/部署证据。只有前两类在本任务范围内；后两类缺失时不得把父任务的完成数解释为真机已验收。
|
||
|
||
## Risks and Deferred Items
|
||
|
||
- 当前已知风险是 Chromium 可执行文件或沙箱策略仍可能不可用；处理为 `PAUSED`，不改产品代码，不降低验收条件。
|
||
- 移动固定动作条的视觉层和键盘/可达性行为仍需代表性真机确认；OpenClaw/Playwright 只能补浏览器模拟证据。
|
||
- 若浏览器回归发现实现缺陷，先记录最小复现和归属；超出低风险子任务范围的修复另建 Trellis task，不在本回归任务中顺手扩大范围。
|
||
|
||
## Open Questions
|
||
|
||
无。范围、证据边界、移动视口、截图目录和 `PAUSED` 判定均已确认。
|