完成OA治理审查矩阵（05-27-oa-product-flow-test-policy-audit）

2026-05-28 00:32:54 +08:00
@@ -2,7 +2,7 @@

 ## Planning 口径

-本子任务先保持 planning。总任务完成后，再启动发票验真 API POC。
+本子任务已完成“POC 方案与采购决策”审查。真实 API 联调不在本轮执行，需另起实施任务并获得样票授权和预算确认。

 ## 后续执行方式

@@ -16,3 +16,9 @@
 - 不采购、充值或开通生产付费能力。
 - 不上传未经授权的真实发票。
 - 不保存真实票面、税号、银行账号、二维码或完整敏感字段。
+
+## 完成记录
+
+- 已明确首选腾讯云、百度备选，华为云和百望/诺诺暂不进首轮。
+- 已明确官方税务查验平台不能作为自动化生产接口来源。
+- 已明确验真失败或 API 不可用时不阻断报销提交，转财务人工复核。
@@ -19,10 +19,10 @@

 ## Acceptance Criteria

- [ ] 输出发票验真 API 对比矩阵。
- [ ] 输出推荐供应商和备选供应商。
- [ ] 输出 POC 流程、样票授权边界、测试命令和验收标准。
- [ ] 明确发票验真失败、超限、欠费、API 不可用时的业务降级策略。
+- [x] 输出发票验真 API 对比矩阵。
+- [x] 输出推荐供应商和备选供应商。
+- [x] 输出 POC 流程、样票授权边界、测试命令和验收标准。
+- [x] 明确发票验真失败、超限、欠费、API 不可用时的业务降级策略。

 ## Out of Scope

@@ -44,3 +44,7 @@ git diff --check
 - Reimbursement rules: `docs/报销发票附件规则.md`
 - Invoice/OCR spec: `.trellis/spec/hyb-oa/reimbursement-invoice-ocr.md`
 - Security/privacy spec: `.trellis/spec/hyb-oa/security-privacy.md`
+
+## Completion Note
+
+2026-05-27：本轮完成供应商调研、合规边界和最小 POC 方案设计；未采购、未充值、未上传真实发票、未接入生产 provider。真实 API POC 需另起实施任务并获得样票授权和预算确认。
@@ -0,0 +1,76 @@
+# 发票验真 API POC 与采购决策
+
+## Conclusion
+
+hyb-oa 已经有发票验真能力的骨架：`invoice_verification` feature flag、`verificationProvider`、验真 job、票据中心 `/verify` 路由、权限 `invoice.verify` 和 mock/tax provider 测试。但真实 provider 当前未配置，`tax` provider 只是返回 `tax_provider_not_configured`。下一步应做供应商 POC，而不是直接启用生产。
+
+## Official Boundary
+
+国家税务总局全国增值税发票查验平台说明显示：
+
+- 可查验最近 5 年内相关发票。
+- 每天每张发票可在线查询次数为 5 次。
+- 平台提供票面信息查验结果；有疑议需持发票原件至税务机关鉴定。
+
+因此系统不应爬取官方查验平台作为生产能力；应接合规 API 或保留人工查验。
+
+## Vendor Matrix
+
+| 候选 | 公开信息 | 适配性 | 风险 | 建议 |
+| --- | --- | --- | --- | --- |
+| 腾讯云 OCR 增值税发票核验 | 官方价格页显示首次开通 50 次免费资源包，页面可见阶梯单价 | 现有系统已用腾讯 OCR SDK 和腾讯凭据配置，接入成本最低 | 需要开通付费能力、费用限额和异常降级 | 首选 POC |
+| 百度智能云财务票据 OCR | 产品页声明支持 10 余类票据结构化识别和增值税发票验真 | 可作为第二候选 | 价格和购买方式需控制台/商务确认 | 备选 POC |
+| 华为云发票识别与验真 | 本轮资料访问触发安全验证，未取得稳定公开价格页 | 需要另行确认产品状态和价格 | 信息可得性不足 | 不作为首选 |
+| 百望/诺诺类平台 | 更偏财税平台和发票生命周期服务 | 可能适合规模化发票管理 | 采购、合同、数据边界和集成成本较高 | 后续询价，不进首轮 |
+
+## Recommended POC
+
+首选腾讯云，理由：
+
+1. 现有 OCR provider 已是腾讯链路，凭据和 SDK 管理成本最低。
+2. 供应商数量少，运维和采购复杂度低。
+3. 可用现有 `verificationProvider` 抽象扩展为 `tencent` 或明确命名的 `tencent_tax` provider。
+
+POC 范围：
+
+- 仅使用授权样票别名，不保存真实票面或敏感字段。
+- 仅在测试/受控环境开启 `INVOICE_VERIFICATION_ENABLED=true` 和 feature flag。
+- 对一张已 OCR 的 PDF 发票执行验真，保存状态、resultCode、resultMessage、provider、尝试次数和脱敏摘要。
+- API 不可用、超限、欠费、查无结果时不阻断提交，只进入财务人工复核。
+
+POC 验收标准：
+
+- provider adapter 单测覆盖成功、查无结果、信息不匹配、超限/欠费、provider 未配置和网络错误。
+- 验真任务重复触发受最大尝试次数、冷却时间和权限控制约束。
+- 票据中心动作 E2E 覆盖管理员/财务可触发、普通员工不可越权触发。
+- 日志、审计和 UI 摘要均不得保存完整税号、银行账号、二维码、真实票面或原始接口响应。
+- provider 不可用时，报销提交链路继续可用并进入财务人工复核。
+
+后续实施命令建议：
+
+```bash
+cd server && npm run prisma:validate
+cd server && npm test -- --runInBand --testPathPattern=verification
+cd client && npm run typecheck && npm run build
+cd client && npx playwright test tests/e2e/invoice-ocr-flow.spec.ts
+```
+
+## Product Decision
+
+- 首批真实试运行仍采用 `OCR + 查重 + 财务人工复核`。
+- 发票验真上线后作为“财务复核增强”，不是自动报销通过条件。
+- 验真失败分为：信息不匹配、查无结果、接口错误、超限/欠费、provider 未配置。
+- 发票验真结果不得替代原始 PDF、审批记录、付款证据和财务判断。
+
+## Implementation Notes For Later
+
+- 新增 provider 前先更新 `server/src/config.js` 和 `deploy/trialrun/.env.example`。
+- 增加 provider 单测、错误分类单测、job 单测和票据中心动作 E2E。
+- 验真 payload 和报告不得存完整税号、完整票面、二维码、银行账号或原始接口响应。
+- 费用控制：默认关闭；按部门 allowlist 或管理员手动触发；冷却时间和最大尝试次数继续沿用现有配置。
+
+## References
+
+- 国家税务总局全国增值税发票查验平台说明：`https://inv-veri.chinatax.gov.cn/fpcysm.html`
+- 腾讯云 OCR 价格页：`https://buy.cloud.tencent.com/price/ocr`
+- 百度智能云财务票据文字识别：`https://cloud.baidu.com/product/OCR/finance.html`