hyb-oa/.trellis/tasks/05-28-oa-test-coverage-gap-fill/prd.md

业务流程测试覆盖缺口补齐

Goal

补齐上一轮业务流程测试覆盖矩阵中“可以自动化、风险低、不会触碰真实生产写入”的缺口。第一批聚焦发票验真，因为现有系统已经有服务骨架、feature flag、票据中心入口和部分基础单测，但触发、重试、限流、禁用降级和页面动作还缺少 focused 覆盖。

Background

• 真实 7 天试运行任务继续并行推进，本任务不替代真实员工样本、Day 7 Go/No-Go、企业微信真机或公网带凭据证据。
• 审查矩阵结论显示：登录、报销、审批、付款/AP、采购/合同已有较多自动化覆盖；高缺口集中在发票验真 provider POC、制度签收、用印台账、真实闭环证据和备份恢复。
• 制度签收、用印台账和备份恢复需要更明确的产品/运维决策，不适合塞进本批测试补齐。
• 发票验真当前是“辅助核验”定位，不能在本任务中接真实付费 API，也不能把 mock 或占位 provider 说成真实验真通过。

Scope

In Scope

• 后端发票验真相关自动化测试：
  • provider 选择、未配置 provider、unsupported provider 的稳定结果。
  • feature flag / env hard off / department allowlist 的启停判断。
  • 触发验真路由创建 pending 记录、写入审计、携带最小安全 request payload。
  • 禁用、已有 pending、冷却时间、重试上限等业务保护返回可解释错误。
  • 验真 job 在 flag 关闭、记录缺失、非 pending、provider 异常时的降级行为。
• 前端票据中心 focused E2E：
  • 有 invoice.verify 权限时，详情面板可触发辅助核验并请求 /api/invoice-pool/:id/verify。
  • failed/error 记录可显示“重新核验”动作并请求 retry API。
  • 后端返回禁用/频控/重试上限时，页面展示业务可理解错误文案。
• 测试报告和命令记录写入当前任务，不记录真实票据、完整账号、Secret、原始 payload 或完整本地路径。

Out of Scope

• 接入真实税局、第三方验真或任何付费 API。
• 写入生产配置、生产数据库、企业微信后台、真实付款、真实 OCR 样票。
• 开发制度签收、用印台账、备份恢复演练功能。
• 关闭或归档 05-26-oa-seven-day-trial-live-ops。
• 大范围重构票据中心 UI 或发票验真架构。

Acceptance Criteria

• 新增或扩展后端 focused tests，覆盖发票验真触发、重试、禁用、pending、冷却、次数上限和 job 降级场景。
• 新增或扩展前端 focused Playwright 测试，覆盖票据中心辅助核验按钮、重新核验按钮和可解释错误提示。
• 所有测试使用 mock/stub 或隔离 fixture，不调用真实外部验真、OCR、企业微信或生产 API。
• 错误测试只断言脱敏业务码和用户文案，不快照完整 raw payload。
• 任务验证命令通过，或按测试规约记录明确 SKIP/BLOCKED 原因。

Test Plan

Backend

• cd server && npm run prisma:validate
• cd server && npx vitest run tests/unit/verification.access.test.js tests/unit/verification.provider.test.js tests/unit/services/verification.test.js
• 若新增 route/job 测试：
  • cd server && npx vitest run tests/unit/routes/invoicePool.verification.test.js tests/unit/jobs/verificationJob.test.js
• 如触及服务/路由实现：
  • cd server && node --check src/services/verification/index.js
  • cd server && node --check src/routes/invoicePool/verification.js
  • cd server && node --check src/jobs/verificationJob.js

Frontend

• cd client && npm run typecheck
• cd client && npm run build
• 若新增或扩展 Playwright：
  • cd client && npx playwright test tests/e2e/pc-finance-admin-visual-wave4.spec.ts --workers=1 --reporter=list

Governance

• python3 ./.trellis/scripts/task.py validate 05-28-oa-test-coverage-gap-fill
• node scripts/qa/check-trellis-governance.mjs
• git diff --check

Implementation Notes

• 优先补测试，不为了测试重写业务代码；只有发现真实 bug 时才做最小修复。
• 后端 route 测试复用现有 Fastify injection + Prisma stub 模式。
• 前端 E2E 复用现有 Wave4 mock API 和权限 fixture，避免启动真实后端或真实数据库。
• 发票验真真实 provider 仍保持后续 POC，当前只证明系统在开关、占位 provider 和失败降级下行为可控。

Execution Results

• Added backend focused tests:
  • server/tests/unit/routes/invoicePool.verification.test.js
  • server/tests/unit/jobs/verificationJob.test.js
• Extended frontend focused E2E:
  • client/tests/e2e/pc-finance-admin-visual-wave4.spec.ts
• Commands and results:
  • cd server && npx vitest run tests/unit/routes/invoicePool.verification.test.js tests/unit/jobs/verificationJob.test.js -> 2 files / 12 tests passed.
  • cd server && npm run prisma:validate -> schema valid.
  • cd server && npx vitest run tests/unit/verification.access.test.js tests/unit/verification.provider.test.js tests/unit/services/verification.test.js tests/unit/routes/invoicePool.verification.test.js tests/unit/jobs/verificationJob.test.js -> 5 files / 24 tests passed.
  • cd client && npx playwright test tests/e2e/pc-finance-admin-visual-wave4.spec.ts --workers=1 --reporter=list -> 3 tests passed.
  • cd client && npm run typecheck -> passed.
  • cd client && npm run build -> passed; Vite build completed and PWA files generated.
  • python3 ./.trellis/scripts/task.py validate 05-28-oa-test-coverage-gap-fill -> passed.
  • node scripts/qa/check-trellis-governance.mjs -> passed.
  • git diff --check -> passed.
• Non-blocking command correction:
  • cd server && npx vitest run ... --reporter=list failed at startup because this Vitest setup does not resolve reporter list; reran with default reporter and passed.

Testing State Capsule

[Testing State Capsule]
Goal: 补齐审查矩阵中可自动化的业务流程测试缺口，第一批聚焦发票验真。
Repo signals: Backend Vitest/Fastify injection/Prisma validate; Frontend Playwright/Vite typecheck/build; Trellis governance.
Unit command(s): `npm run prisma:validate`; focused Vitest 5 files / 24 tests passed.
Integration command(s): focused Playwright Wave4 3 tests passed; client typecheck/build passed.
Env/deps: 不需要生产配置、付费 API、真实票据、真实付款、企业微信写入或 DB reset。
Assumptions: 发票验真当前为辅助核验和 provider skeleton，本任务只补 mock/stub 自动化。
Last result: 后端 route/job 测试与前端票据中心动作 E2E 已补齐，Trellis/governance/diff checks passed.
Next action: 提交本任务改动并归档任务。
Open questions: 无阻塞问题。