补齐发票验真测试覆盖（05-28-oa-test-coverage-gap-fill）

2026-05-28 08:45:19 +08:00
@@ -0,0 +1,8 @@
+{"file": ".trellis/spec/hyb-oa/project-governance.md", "reason": "Verify Trellis flow, scope control, approval, and commit rules."}
+{"file": ".trellis/spec/hyb-oa/backend-fastify-prisma.md", "reason": "Verify backend checks, route/service tests, and Prisma validation."}
+{"file": ".trellis/spec/hyb-oa/frontend-react-vite-design.md", "reason": "Verify frontend typecheck/build and Playwright expectations for UI test changes."}
+{"file": ".trellis/spec/hyb-oa/reimbursement-invoice-ocr.md", "reason": "Verify invoice/OCR boundary and no real invoice evidence leakage."}
+{"file": ".trellis/spec/hyb-oa/security-privacy.md", "reason": "Verify no secrets, raw payloads, full accounts, or invoice originals are captured."}
+{"file": ".trellis/spec/hyb-oa/docs-and-evidence.md", "reason": "Verify evidence references and task notes stay privacy-safe."}
+{"file": ".trellis/tasks/05-28-oa-test-coverage-gap-fill/research/coverage-inspection.md", "reason": "Verify implementation addressed the identified coverage gaps."}
+{"file": ".trellis/tasks/archive/2026-05/05-27-oa-test-coverage-matrix/research/test-coverage-matrix.md", "reason": "Verify scope remains aligned to the prior coverage matrix."}
@@ -0,0 +1,8 @@
+{"file": ".trellis/spec/hyb-oa/project-governance.md", "reason": "Trellis task flow, approval-before-code, scoped commits, and stop conditions."}
+{"file": ".trellis/spec/hyb-oa/backend-fastify-prisma.md", "reason": "Backend Fastify/Prisma validation and focused route/service test expectations."}
+{"file": ".trellis/spec/hyb-oa/frontend-react-vite-design.md", "reason": "Frontend test and Playwright expectations if invoice pool UI E2E is extended."}
+{"file": ".trellis/spec/hyb-oa/reimbursement-invoice-ocr.md", "reason": "Invoice/OCR boundaries, PDF-only maintained path, and sensitive invoice evidence restrictions."}
+{"file": ".trellis/spec/hyb-oa/security-privacy.md", "reason": "No secrets, raw payloads, real invoice originals, or full accounts in tests/reports."}
+{"file": ".trellis/spec/hyb-oa/docs-and-evidence.md", "reason": "Evidence/report privacy and repo-relative references."}
+{"file": ".trellis/tasks/05-28-oa-test-coverage-gap-fill/research/coverage-inspection.md", "reason": "Current coverage findings and first-batch testing gaps."}
+{"file": ".trellis/tasks/archive/2026-05/05-27-oa-test-coverage-matrix/research/test-coverage-matrix.md", "reason": "Source matrix that identified invoice verification as a high test gap."}
@@ -0,0 +1,36 @@
+# 实施说明
+
+## Recommended Batch
+
+先做“发票验真自动化测试补齐”这一批。理由是：
+
+- 代码已存在，测试可以低风险补齐，不需要真实 provider。
+- 它直接对应上一轮矩阵里的高缺口。
+- 能提高后续付费 API POC 的安全边界：即使 provider 未配置、失败或被关闭，系统也能给出可解释结果。
+
+## Planned Changes After Approval
+
+1. 后端测试
+   - 新增 `server/tests/unit/routes/invoicePool.verification.test.js`，覆盖触发、禁用、pending、冷却和重试保护。
+   - 新增或扩展 job/service 测试，覆盖 flag 关闭、非 pending、provider error 的降级写库。
+   - 若发现重复/过宽断言，收紧现有 `verification.*.test.js`，不做无关重构。
+
+2. 前端测试
+   - 扩展 `client/tests/e2e/pc-finance-admin-visual-wave4.spec.ts` 或新增 focused spec。
+   - 用 route mock 验证“发起辅助核验”“重新核验”和错误文案，不访问真实后端。
+
+3. 质量门禁
+   - 后端 focused Vitest + `prisma:validate`。
+   - 前端 `typecheck`、`build`，以及 focused Playwright。
+   - Trellis task validate、governance gate、`git diff --check`。
+
+## Boundaries
+
+- 不新增真实验真 provider。
+- 不读取或上传真实票据。
+- 不部署、不写生产配置、不调用公网接口。
+- 不改付款、企业微信、OCR provider、备份恢复和试运行主任务。
+
+## Rollback
+
+本批主要是测试代码。若测试实现暴露夹具不稳定，优先收窄为后端 route/service focused tests；必要时回退前端 E2E 扩展，只保留后端自动化覆盖。
@@ -0,0 +1,112 @@
+# 业务流程测试覆盖缺口补齐
+
+## 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
+
+- [x] 新增或扩展后端 focused tests，覆盖发票验真触发、重试、禁用、pending、冷却、次数上限和 job 降级场景。
+- [x] 新增或扩展前端 focused Playwright 测试，覆盖票据中心辅助核验按钮、重新核验按钮和可解释错误提示。
+- [x] 所有测试使用 mock/stub 或隔离 fixture，不调用真实外部验真、OCR、企业微信或生产 API。
+- [x] 错误测试只断言脱敏业务码和用户文案，不快照完整 raw payload。
+- [x] 任务验证命令通过，或按测试规约记录明确 `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
+
+```text
+[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: 无阻塞问题。
+```
@@ -0,0 +1,42 @@
+# 测试覆盖调研摘要
+
+## Existing Signals
+
+- `server/package.json` 提供 `npm test`、`npm run prisma:validate` 和 Vitest。
+- `client/package.json` 提供 `npm run typecheck`、`npm run build` 和 Playwright。
+- 现有发票验真代码集中在：
+  - `server/src/services/verification/index.js`
+  - `server/src/services/verification/tax.js`
+  - `server/src/routes/invoicePool/verification.js`
+  - `server/src/jobs/verificationJob.js`
+  - `client/src/pages/invoice-pool/InvoiceDetailPanel.tsx`
+- 现有测试已经覆盖：
+  - provider 归一化基础行为。
+  - mock/tax/unsupported provider 的基础返回。
+  - feature flag env hard off 和部门 allowlist 基础判断。
+  - Wave4 页面 mock 数据能展示核验记录。
+
+## Gaps
+
+- 后端路由缺少 focused coverage：
+  - POST `/api/invoice-pool/:id/verify`
+  - GET `/api/invoice-pool/:id/verification`
+  - POST `/api/invoice-pool/:id/verification/retry`
+  - disabled、already pending、too frequent、attempts exceeded 等业务保护。
+- job 缺少覆盖：
+  - 记录不存在、发票不存在、状态非 pending、feature flag 关闭、provider error。
+- 前端缺少动作覆盖：
+  - 点击“发起辅助核验”是否请求 verify API。
+  - 点击“重新核验”是否请求 retry API。
+  - API 返回禁用/频控/次数上限时是否展示用户可理解文案。
+
+## Recommended First Implementation
+
+1. 用 Fastify injection + Prisma stub 新增后端路由测试。
+2. 用 Vitest stub 覆盖 `runVerificationForRecord` 降级行为。
+3. 扩展 Wave4 Playwright mock API，覆盖两个按钮动作和错误文案。
+
+## Safety Notes
+
+- 不调用真实 provider，不读取真实票据，不写生产数据库。
+- 只记录相对路径、业务码和脱敏结论。
@@ -0,0 +1,26 @@
+{
+  "id": "oa-test-coverage-gap-fill",
+  "name": "oa-test-coverage-gap-fill",
+  "title": "业务流程测试覆盖缺口补齐",
+  "description": "补齐业务流程自动化测试覆盖矩阵中的第一批缺口，聚焦发票验真 trigger/retry/provider/降级和票据中心动作测试。",
+  "status": "in_progress",
+  "dev_type": null,
+  "scope": "server,client,qa",
+  "package": null,
+  "priority": "P2",
+  "creator": "shunli",
+  "assignee": "shunli",
+  "createdAt": "2026-05-28",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}