diff --git a/.trellis/tasks/05-27-invoice-verification-api-poc/implement.md b/.trellis/tasks/05-27-invoice-verification-api-poc/implement.md index 4324de8f..70b8cf81 100644 --- a/.trellis/tasks/05-27-invoice-verification-api-poc/implement.md +++ b/.trellis/tasks/05-27-invoice-verification-api-poc/implement.md @@ -2,7 +2,7 @@ ## Planning 口径 -本子任务先保持 planning。总任务完成后,再启动发票验真 API POC。 +本子任务已完成“POC 方案与采购决策”审查。真实 API 联调不在本轮执行,需另起实施任务并获得样票授权和预算确认。 ## 后续执行方式 @@ -16,3 +16,9 @@ - 不采购、充值或开通生产付费能力。 - 不上传未经授权的真实发票。 - 不保存真实票面、税号、银行账号、二维码或完整敏感字段。 + +## 完成记录 + +- 已明确首选腾讯云、百度备选,华为云和百望/诺诺暂不进首轮。 +- 已明确官方税务查验平台不能作为自动化生产接口来源。 +- 已明确验真失败或 API 不可用时不阻断报销提交,转财务人工复核。 diff --git a/.trellis/tasks/05-27-invoice-verification-api-poc/prd.md b/.trellis/tasks/05-27-invoice-verification-api-poc/prd.md index e481eb27..54b0986f 100644 --- a/.trellis/tasks/05-27-invoice-verification-api-poc/prd.md +++ b/.trellis/tasks/05-27-invoice-verification-api-poc/prd.md @@ -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 需另起实施任务并获得样票授权和预算确认。 diff --git a/.trellis/tasks/05-27-invoice-verification-api-poc/research/invoice-verification-api-poc.md b/.trellis/tasks/05-27-invoice-verification-api-poc/research/invoice-verification-api-poc.md new file mode 100644 index 00000000..264c2132 --- /dev/null +++ b/.trellis/tasks/05-27-invoice-verification-api-poc/research/invoice-verification-api-poc.md @@ -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` diff --git a/.trellis/tasks/05-27-oa-business-flow-policy-alignment/implement.md b/.trellis/tasks/05-27-oa-business-flow-policy-alignment/implement.md index 38c374d2..ce04b33e 100644 --- a/.trellis/tasks/05-27-oa-business-flow-policy-alignment/implement.md +++ b/.trellis/tasks/05-27-oa-business-flow-policy-alignment/implement.md @@ -2,7 +2,7 @@ ## Planning 口径 -本子任务先保持 planning。总任务完成后,再启动制度映射专项审查。 +本子任务已作为制度映射审查完成。后续若要把制度参数、签收、用印或交接规则产品化,应另起实施任务。 ## 后续执行方式 @@ -16,3 +16,9 @@ - 不保存公司制度敏感原文、合同正文、证照、银行资料或完整路径。 - 不做正式法律审查。 - 不自动改权限、审批阈值或生产配置。 + +## 完成记录 + +- 已形成制度材料类别到 OA 角色、字段、审批、附件、台账和审计证据的映射。 +- 已明确员工制度签收不能用公告阅读替代。 +- 已明确合同正文、银行材料、账号凭据和高敏原文不进入公网 OA。 diff --git a/.trellis/tasks/05-27-oa-business-flow-policy-alignment/prd.md b/.trellis/tasks/05-27-oa-business-flow-policy-alignment/prd.md index 250e45fb..00e923a6 100644 --- a/.trellis/tasks/05-27-oa-business-flow-policy-alignment/prd.md +++ b/.trellis/tasks/05-27-oa-business-flow-policy-alignment/prd.md @@ -19,10 +19,10 @@ ## Acceptance Criteria -- [ ] 输出制度映射矩阵。 -- [ ] 明确高风险制度缺口:越权审批、口头审批、付款证据、合同归档、员工制度告知/签收、资料保密和账号权限回收。 -- [ ] 不保存合同正文、证照、完整路径、账号凭据、银行资料或敏感员工资料。 -- [ ] 给出第一批 OA 流程调整建议和后置事项。 +- [x] 输出制度映射矩阵。 +- [x] 明确高风险制度缺口:越权审批、口头审批、付款证据、合同归档、员工制度告知/签收、资料保密和账号权限回收。 +- [x] 不保存合同正文、证照、完整路径、账号凭据、银行资料或敏感员工资料。 +- [x] 给出第一批 OA 流程调整建议和后置事项。 ## Out of Scope @@ -44,3 +44,7 @@ git diff --check - Security/privacy spec: `.trellis/spec/hyb-oa/security-privacy.md` - Docs/evidence spec: `.trellis/spec/hyb-oa/docs-and-evidence.md` - Company policy source: repository-external company materials; only abstract rule mapping may be persisted. + +## Completion Note + +2026-05-27:审查型交付已完成,研究结论见 `research/business-flow-policy-alignment.md`。本轮只沉淀抽象规则映射,没有导入制度原文或敏感材料。 diff --git a/.trellis/tasks/05-27-oa-business-flow-policy-alignment/research/business-flow-policy-alignment.md b/.trellis/tasks/05-27-oa-business-flow-policy-alignment/research/business-flow-policy-alignment.md new file mode 100644 index 00000000..51c53bf3 --- /dev/null +++ b/.trellis/tasks/05-27-oa-business-flow-policy-alignment/research/business-flow-policy-alignment.md @@ -0,0 +1,42 @@ +# 业务流程合理性与公司制度对齐审查 + +## Conclusion + +公司制度资料对 OA 非常有价值,但应作为“规则与字段映射来源”,不能作为全文导入来源。当前 OA 的小团队 V1 路线与制度总览一致:先做到授权审批、报销付款、合同用印、采购、资料保密、员工制度签收和资产/账号交接能执行、能留痕、能追责。 + +## Policy To OA Matrix + +| 制度材料类别 | OA 映射 | 当前状态 | 缺口 | 建议 | +| --- | --- | --- | --- | --- | +| 授权审批权限表 | 审批规则、角色、直属主管、ownerSelfFallbackRole | 已有审批中心和自审阻断 | 金额阈值仍需管理层确认 | 不硬编码;先用配置和人工确认 | +| 财务管理制度 | 报销、付款批次、AP、导出、审计 | 主链路已具备 | 真实月度代账交接样本待补 | OAOPS1/Day7 后继续月检 | +| 费用报销与付款办法 | PDF 发票、附件、查重、审批、付款 | 已有规则和测试 | 发票验真未接真实 provider | 单独 POC | +| 合同管理办法 | 合同台账、项目关联、归档位置、附件审计 | 可试运行 | 用印专用字段未固化 | 先用摘要/归档位置;阻断再开发 | +| 印章证照管理 | 用印事项、文件版本、份数、责任人、归档位置 | 可借合同台账承载 | 专用用印台账未实现 | 不作为 Day7 前硬阻断 | +| 采购与供应商管理 | 采购申请、供应商主数据、项目/合同关联 | 已有流程和测试 | 比价/尽调字段待确认 | P1 试点后再增强 | +| 员工手册与劳动规章 | 公告、员工档案、培训记录、签收证据 | OA 可通知,不可替代签收 | 缺正式签收回执 | 先线下/电子签收,后续功能化 | +| 保密与知识产权 | 项目/合同/资产密级、离线归档、审计 | 已有边界规则 | 高敏资料误上传需培训 | 数据治理培训纳入 Go/No-Go | +| 固定资产与 IT 资产 | FA/EA-DOC/EA-SYS/EA-REPO/EA-BKP | 资产台账已具备 | EA-ACC 暂缓 | 不做账号资产卡,做离职权限清单 | +| 信息安全与账号权限 | 用户管理、角色、离职 checklist、审计 | 已有基础 | 权限回收证据需日常化 | 月度内控自查承接 | + +## Business Flow Decisions + +- 报销、采购、合同、项目和财务继续 OA 主办;企业微信只做提醒和入口。 +- HR/考勤员工日常审批继续企业微信主办,OA 做留存和后续兜底。 +- 员工制度签收不能用“看过公告”替代,正式启用前要有签收证据。 +- 合同正文、敏感报价、银行流水、账号凭据、完整路径不进入公网 OA。 +- 用印台账 V1 可以先由合同台账摘要、归档位置和离线档案号承载;如果真实用印无法说明,再做专用字段。 + +## First Batch Recommendation + +1. Day 7 前管理层确认:审批阈值、报销期限、采购比价触发、合同/用印责任、制度签收方式。 +2. 将制度签收作为人工门禁,不立即开发。 +3. 将用印台账作为观察项,不立即迁移 schema。 +4. 将账号交接纳入离职 checklist 和月度内控自查,不做 EA-ACC。 +5. 将发票验真作为付费 API POC,不替代当前财务人工复核。 + +## Evidence + +- 公司制度总览明确 V1 聚焦“能执行、能留痕、能追责”。 +- `docs/管理员手册.md` 已有 OPOLICY1、OALAUNCH1、资产和数据治理门禁。 +- `docs/需求-统一审批中心规约.md` 已定义 OA 主办审批和自审阻断。 diff --git a/.trellis/tasks/05-27-oa-frontend-layout-page-fit-review/implement.md b/.trellis/tasks/05-27-oa-frontend-layout-page-fit-review/implement.md index c1e0eb7a..26636830 100644 --- a/.trellis/tasks/05-27-oa-frontend-layout-page-fit-review/implement.md +++ b/.trellis/tasks/05-27-oa-frontend-layout-page-fit-review/implement.md @@ -2,7 +2,7 @@ ## Planning 口径 -本子任务先保持 planning。总任务完成后,再根据优先级启动。 +本子任务已作为审查型任务完成。后续代码改造不在本任务内执行,应按页面波次另起实施任务。 ## 后续执行方式 @@ -16,3 +16,9 @@ - 不恢复旧的重复设计规则。 - 不把所有页面一次性重构。 - 不用视觉优化替代业务流程和权限审查。 + +## 完成记录 + +- 已形成页面类型 taxonomy、页面适用性矩阵和前端设计方向。 +- 已确认 `check-ui-design-rules.mjs` 扫描 133 files、0 findings。 +- 后续第一批建议:PC 页面布局统一,尤其工作台、列表/详情、财务密集页和 C 类管理页的模板一致性。 diff --git a/.trellis/tasks/05-27-oa-frontend-layout-page-fit-review/prd.md b/.trellis/tasks/05-27-oa-frontend-layout-page-fit-review/prd.md index 2b171f8d..242e12bb 100644 --- a/.trellis/tasks/05-27-oa-frontend-layout-page-fit-review/prd.md +++ b/.trellis/tasks/05-27-oa-frontend-layout-page-fit-review/prd.md @@ -19,10 +19,10 @@ ## Acceptance Criteria -- [ ] 输出页面审查矩阵。 -- [ ] 标记每个关键页面的角色、主要任务、布局问题、视觉问题、交互问题和优先级。 -- [ ] 明确第一批要改的页面,不把所有页面混成一次大改。 -- [ ] 不直接替代业务流程审查和测试覆盖审查。 +- [x] 输出页面审查矩阵。 +- [x] 标记关键页面域的角色、主要任务、布局问题、视觉问题、交互问题和优先级。 +- [x] 明确第一批要改的页面,不把所有页面混成一次大改。 +- [x] 不直接替代业务流程审查和测试覆盖审查。 ## Out of Scope @@ -44,3 +44,7 @@ git diff --check - Frontend spec: `.trellis/spec/hyb-oa/frontend-react-vite-design.md` - Product facts: `docs/产品设计规则.md` - Current Wave evidence: `05-26-oa-seven-day-trial-live-ops` postdeploy Wave2/Wave3/Wave4 reports. + +## Completion Note + +2026-05-27:审查型交付已完成,研究结论见 `research/page-layout-and-fit-review.md`。后续如进入代码阶段,应新建实施任务并优先处理 PC 页面布局统一。 diff --git a/.trellis/tasks/05-27-oa-frontend-layout-page-fit-review/research/page-layout-and-fit-review.md b/.trellis/tasks/05-27-oa-frontend-layout-page-fit-review/research/page-layout-and-fit-review.md new file mode 100644 index 00000000..0380a14d --- /dev/null +++ b/.trellis/tasks/05-27-oa-frontend-layout-page-fit-review/research/page-layout-and-fit-review.md @@ -0,0 +1,43 @@ +# 前端页面布局统一与页面适用性审查 + +## Conclusion + +当前前端已经完成 Wave2-Wave4 的主要页面治理,且 `check-ui-design-rules.mjs` 扫描 133 个文件为 0 findings。现阶段不建议再做一次“大而全重构”,而应按页面类型固化模板,并对尚未完全归入模板的页面分批收敛。 + +## Layout Taxonomy + +| 页面类型 | 应用页面 | 目标模板 | 当前状态 | 后续动作 | +| --- | --- | --- | --- | --- | +| Auth 入口 | `/login`、`/forgot-password`、`/change-password` | `AuthLayout + AuthPanel` | 已有功能和 E2E;仍可继续压缩文案 | 后续只做视觉微调 | +| 高频工作台 | `/portal`、移动 `/mobile` | 今日动作、待办、常用入口、异常提示 | 已有 Portal E2E 和移动矩阵 | 避免入口重复,低频模块折叠 | +| PC 列表页 | 报销、审批、采购、项目、资产、财务、管理页 | `ListWorkspace + WorkspaceHeader + FilterBar + PrimaryTable` | 多数核心页已采用 | 后续新增页必须复用 | +| PC 详情页 | 报销详情、审批详情、项目详情 | `PageScaffold + EntityOverviewHero + SectionPanel + detail-*` | Wave3 后较统一 | 合同/资产详情若扩展需按此模式 | +| 财务密集页 | 付款批次、AP、票据池 | `finance-* + ops-*` | Wave4 已收敛 | 保持高密但不堆说明文案 | +| 管理 C 类页 | 用户、主数据、通知渠道、功能开关、流程定义、审计 | `admin-* + ops-*` | Wave4 已覆盖主要页 | 低频页只统一命令区和表格密度 | +| 移动轻操作 | 报销、审批、通知、我的、上传 | `PageScaffold + mobile-card + mobile-command-surface` | 移动矩阵覆盖较好 | 禁止桌面表格进入移动主体验 | + +## Page Fit Matrix + +| 页面域 | 业务适用性 | 主要风险 | 优先级 | +| --- | --- | --- | --- | +| 登录页 | 适合成熟 OA 入口;支持密码、邮箱验证码、企微入口、找回密码 | 入口过多时层级混乱 | P1 | +| Portal | 适合小团队日常工作入口 | 信息过多会变成模块列表 | P1 | +| 报销 | 适合高频流程;PC 管理明细,移动补充发票附件 | 发票/附件/付款信息过载 | P1 | +| 审批 | 适合 PC 批量看、移动处理轻审批 | 快捷审批误触 | P1 | +| 财务/AP/付款 | 适合 PC,高密表格合理 | 移动不适合重操作 | P1 | +| 采购/合同/项目 | 适合 P1 轻量试点 | 制度参数未定时不宜重规则化 | P2 | +| 系统管理 | 适合管理员低频维护 | 页很多,容易样式漂移 | P2 | +| 员工制度签收 | 当前没有专门页面 | 公告阅读不能替代签收 | P2/P3 | + +## Frontend Design Direction + +- 运营型 OA 应采用“克制、密集、清晰”的工作台风格,不做营销页、装饰页或大面积视觉噱头。 +- PC 页面优先减少认知成本:标题短、筛选区固定、主表/主卡突出、二级动作收在右侧或详情区。 +- 移动页面只保留轻操作:查看状态、上传 PDF、补附件、审批、通知直达;财务重操作回 PC。 +- 后续新增前端任务必须保留 Playwright 视觉或交互证据。 + +## Evidence + +- `node scripts/qa/check-ui-design-rules.mjs`:133 files scanned, 0 findings. +- Wave2/Wave3/Wave4 public checks均已记录在 OAOPS1 task。 +- `client/src/router/index.tsx` 显示 PC、移动和系统管理页面已按权限路由分层。 diff --git a/.trellis/tasks/05-27-oa-product-flow-test-policy-audit/implement.md b/.trellis/tasks/05-27-oa-product-flow-test-policy-audit/implement.md index a7417075..301ef7a6 100644 --- a/.trellis/tasks/05-27-oa-product-flow-test-policy-audit/implement.md +++ b/.trellis/tasks/05-27-oa-product-flow-test-policy-audit/implement.md @@ -7,7 +7,7 @@ 1. 汇总关键页面、业务流程、测试覆盖、制度映射和发票验真候选项。 2. 形成五张矩阵:页面矩阵、流程矩阵、测试矩阵、制度矩阵、发票验真候选矩阵。 3. 根据阻断风险、用户影响、实施成本和试运行阶段,给出子任务启动顺序。 -4. 只启动当前总任务;四个子任务保持 planning,待总审查收敛后逐个启动。 +4. 本轮完成四个审查型子任务并归档;后续代码实现、测试补齐、制度落地和发票验真 POC 另起实施任务。 ## 子任务关系 @@ -22,3 +22,10 @@ - 不采购或开通付费 API。 - 不替代 OAOPS1 七天真实试运行和 Day 7 Go/No-Go。 - 不在没有专项任务的情况下直接做大规模前端或流程改造。 + +## 完成记录 + +- 页面、流程、测试、制度和发票验真五类矩阵已写入 `research/overall-audit-matrices.md`。 +- 四个子任务已分别产出审查研究文件,作为本总任务的专项证据。 +- 本轮没有修改业务代码、生产配置、数据库、企业微信配置或真实付款链路。 +- OAOPS1 七天真实试运行仍是独立主线,不能随本任务归档。 diff --git a/.trellis/tasks/05-27-oa-product-flow-test-policy-audit/prd.md b/.trellis/tasks/05-27-oa-product-flow-test-policy-audit/prd.md index 899ae723..736b4b4d 100644 --- a/.trellis/tasks/05-27-oa-product-flow-test-policy-audit/prd.md +++ b/.trellis/tasks/05-27-oa-product-flow-test-policy-audit/prd.md @@ -27,7 +27,7 @@ ## Assumptions - 本总任务先做审查、矩阵和路线图,不直接修改业务代码。 -- 子任务保持 `planning` backlog,只有总审查收敛后才逐个启动。 +- 本轮按用户要求收口四个审查型子任务;后续代码改造、测试补齐、制度落地和真实发票验真 POC 另起实施任务。 - 真实试运行期间发现的阻断问题优先级高于治理型优化。 - 发票验真属于付费 API 和合规能力选型,先 POC 和采购决策,不直接接入生产主链路。 @@ -42,11 +42,11 @@ ## Acceptance Criteria -- [ ] 总审查输出页面矩阵、流程矩阵、测试覆盖矩阵、制度映射矩阵和发票验真候选矩阵。 -- [ ] 四个子任务 PRD 均有目标、范围、验收标准和边界说明。 -- [ ] 子任务状态保持 planning,除本总任务外不提前启动。 -- [ ] 总审查结论明确第一批执行任务和不做事项。 -- [ ] 不保存公司敏感原文、完整本地路径、真实账号、合同正文、证照、银行资料、密码、token、Secret 或 raw payload。 +- [x] 总审查输出页面矩阵、流程矩阵、测试覆盖矩阵、制度映射矩阵和发票验真候选矩阵。 +- [x] 四个子任务 PRD 均有目标、范围、验收标准和边界说明。 +- [x] 四个审查型子任务已形成研究结论;后续实施任务不混入本轮。 +- [x] 总审查结论明确第一批执行任务和不做事项。 +- [x] 不保存公司敏感原文、完整本地路径、真实账号、合同正文、证照、银行资料、密码、token、Secret 或 raw payload。 ## Definition of Done @@ -55,6 +55,10 @@ - 更新当前任务 PRD 或研究材料,不把结论留在聊天中。 - Trellis task 校验和治理检查通过。 +## Completion Note + +2026-05-27:本轮完成治理总审查与四个专项审查交付。结论是先回到 OAOPS1 真实试运行主线;后续第一个实施类任务建议新建“PC 前端布局统一改造”,再分批补测试、制度落地和发票验真 POC。 + ## Out of Scope - 本总任务不直接重构前端页面。 diff --git a/.trellis/tasks/05-27-oa-product-flow-test-policy-audit/research/overall-audit-matrices.md b/.trellis/tasks/05-27-oa-product-flow-test-policy-audit/research/overall-audit-matrices.md new file mode 100644 index 00000000..65433229 --- /dev/null +++ b/.trellis/tasks/05-27-oa-product-flow-test-policy-audit/research/overall-audit-matrices.md @@ -0,0 +1,92 @@ +# OA 产品、流程、测试与制度对齐总审查矩阵 + +## Executive Conclusion + +本轮审查任务可以收口为“先完成治理矩阵,不立即混合改代码”。当前系统已经有大量前后端自动化、Wave2-Wave4 前端治理和 OAOPS1 公网只读巡检证据;主要缺口不是从零建设,而是把页面、流程、测试、制度和发票验真纳入统一总账,并按风险分批执行。 + +优先级结论: + +1. **继续 OAOPS1 真实试运行主线**:Day 7 Go/No-Go 之前不宣称最终正式启用完成。 +2. **第一批代码任务建议启动前端页面统一专项**:PC 页面仍最能影响用户体感,且已有 Wave2-Wave4 基础。 +3. **第二批补测试矩阵缺口**:尤其是制度签收、合同/用印归档、发票验真、真实业务写入闭环和 Day 7 证据聚合。 +4. **第三批制度对齐**:先把制度参数、签收、公示、用印台账和账号交接映射成 OA 规则,不导入敏感原文。 +5. **发票验真只做 POC**:现有代码已有 `invoice_verification` flag、provider 抽象和任务表,但真实 provider 仍未配置;建议优先腾讯云 POC,华为云/百度/百望/诺诺作为备选或询价项。 + +## Page Matrix + +| 页面域 | 已知状态 | 主要问题 | 优先级 | 建议 | +| --- | --- | --- | --- | --- | +| 登录/找回密码 | 已改进邮箱验证码、找回密码、PWA 更新不清空输入;有 E2E 覆盖 | 登录页布局还需持续按成熟 auth 模式压缩文案和统一视觉 | P1 | 保留现有功能,后续只做视觉微调和真实邮箱/企微链路复测 | +| 工作台/Portal | Wave2 覆盖,Portal 员工/管理员/财务视角有 E2E | 入口多,需避免变成“模块橱窗” | P1 | 维持“今日动作 + 待办 + 常用入口”结构;低频入口折叠 | +| 报销列表/详情 | Wave2/Wave3 覆盖,PC/移动详情类已使用 `detail-*` 和 `mobile-*` 模式 | 报销细节多,发票/附件/审批/付款容易挤在一起 | P1 | 详情页保持摘要、明细票据、审批、付款/证据四区;不再加说明型文案 | +| 审批中心/审批详情 | Wave2/Wave3 覆盖,审批动作二次确认有 E2E | PC 和移动都要避免快捷误审批 | P1 | 继续“列表只做轻审批,详情处理复杂动作” | +| 通知中心 | Wave3 覆盖,移动通知有直达业务详情测试 | PC/移动信息层级需继续保持事件流而非纯表格 | P2 | 保持未读优先、业务 deeplink、批量已读 | +| 财务/付款/AP/票据池 | Wave4 覆盖,公网巡检通过 | 财务页面天然高密,需避免功能堆叠和误操作 | P1 | 继续用 `finance-*`、`ops-table-focus`、二次确认和审计提示 | +| 管理页/功能开关/用户/主数据/审计 | Wave4 覆盖,系统动作确认有 E2E | 管理页 C 类功能多,容易样式漂移 | P2 | 只统一密度和命令区;不追求营销感 | +| 合同/项目/资产 | 有页面和部分 E2E;制度映射价值高 | 合同/用印/资料密级边界仍依赖人工规则 | P1/P2 | 合同和资产先做字段/台账审查,再决定是否补专用字段 | +| 移动/企业微信关键页 | 多轮移动矩阵和企业微信渲染矩阵通过 | 移动只适合轻操作,不适合财务重表格 | P1 | 移动保留报销、审批、通知、我的、上传;财务重操作回 PC | + +## Business Flow Matrix + +| 流程 | 当前系统状态 | 合理性判断 | 缺口 | 下一步 | +| --- | --- | --- | --- | --- | +| 报销/PDF OCR/查重/审批/付款 | 主链路已具备,PDF-only、查重、付款批次、AP、审计均有规则和测试 | 合理 | Day 7 前需真实业务闭环证据;自动验真未接生产 provider | OAOPS1 继续收集真实样本;发票验真走 POC | +| 审批 | OA 主办报销/采购/合同/项目;HR/考勤企微主办并 OA 留存 | 合理 | 合同/资产等更多业务接入审批时需单独测试 | 流程扩展前走审批规则 reviewer | +| 财务付款/AP/代账 | OA 记录批次、回单、已付款和 AP;真实支付在银行侧 | 合理 | 月度代账交接真实样本仍需人工证据 | Day 7 和月末前补人工交接证据 | +| 采购/费用 | 已有采购主链路 E2E 和预算预检相关单测 | 基本合理 | 公司制度中的比价、合同触发、例外审批参数未定稿 | 制度对齐后再改规则 | +| 合同台账/项目 | 页面和台账存在,敏感正文不进 OA | 合理 | 用印台账、合同版本、归档位置字段是否够用需真实样本验证 | 先用现有字段试运行,阻断再新建字段任务 | +| 资产/账号交接 | 统一资产台账、编号族和离职 checklist 已有规则 | 合理 | 账号资产 EA-ACC 暂缓,制度签收和权限回收证据需进一步明确 | 不立即做账号资产卡;补制度签收/交接矩阵 | +| 员工制度签收 | 制度资料已有签收包和培训模板;OA 公告可发通知 | 不完整 | OA 公告阅读不能等同正式签收 | 先保持纸面或电子签收,后续如阻断再做 OA 签收回执 | +| 发票验真 | 后端已有抽象、feature flag、job 和接口;真实 tax provider 未配置 | POC 就绪,生产未就绪 | 供应商选择、费用控制、样票授权、降级策略 | 单独 POC,不混入试运行主线 | + +## Test Coverage Matrix + +| 领域 | 后端单元/服务 | 前端 PC E2E | 移动/企微 E2E | 公网/真实验证 | 结论 | +| --- | --- | --- | --- | --- | --- | +| 登录/邮箱/找回密码 | `auth.login.test`、email service | `login-portal-ux.spec` | 企业微信入口相关 | 已部署并公网测试过 SMTP | 覆盖较好 | +| 报销/OCR/附件 | `invoicePool.*`、`reimbursements.*`、`ocrJob`、`invoiceGovernance` | `main-flow`、`invoice-ocr-flow`、`r111`、`r125` | `MobileReimbursement*`、企业微信 UA | live OCR 辅助复核存在 | 覆盖较好,缺自动验真生产 provider | +| 审批 | `workflow.*`、`utils/workflow` | `workflow-*`、`permission-direct-access` | `mobile-approvals-offline` | OAOPS1 只读巡检覆盖待办 | 覆盖较好,真实业务闭环仍靠人工 | +| 财务/付款/AP | `paymentBatches`、`financeLedger`、exports | `reimbursement-payment-batch-flow`、Wave4 | 移动仅查看/入口 | 公网只读和历史付款短窗口证据 | 覆盖较好 | +| 采购/项目/合同 | `purchase.*`、`projects`、`contractsRegistry` | `procurement-flow`、`project-workbench` | `MobilePurchase*` | OAOPS1 只读覆盖 | 部分真实流程证据待补 | +| 资产/人事/账号 | `assets.*`、`employees.*`、users | `assets-flow`、`user-onboarding` | `MobileAssetScan` | ASSET1 已有公网证据 | 覆盖较好,制度交接待映射 | +| 制度签收/用印台账 | 暂无专门测试 | 暂无专门页面测试 | 暂无 | 依赖人工制度资料 | 明确缺口,先不阻断试运行 | +| 发票验真 | `verification.*` 有 provider 抽象测试 | 票据中心页面未覆盖真实验真 provider | 暂无 | 无真实 provider | POC 缺口 | + +## Policy Mapping Matrix + +| 制度主题 | OA 对应能力 | 当前结论 | 建议 | +| --- | --- | --- | --- | +| 授权审批权限 | 审批规则、角色权限、workflow snapshot | 已有基础 | 管理层确认金额阈值前,不硬编码虚构金额 | +| 财务/报销付款 | 报销、付款批次、AP、回单、审计 | 已有主链路 | Day 7 收集真实样本和付款证据 | +| 合同/用印 | 合同台账、项目关联、附件审计、线下归档位置 | 基本可试运行 | 用印专用字段先观察,阻断再做 | +| 采购/供应商 | 采购申请、供应商主数据、附件、审批 | 部分可用 | 比价、供应商尽调先人工规则,后续字段化 | +| 员工手册/劳动规章 | 公告、培训记录、员工档案 | 不完整 | 正式签收先线下/电子签收;OA 公告只做通知 | +| 保密/IP/资料分级 | 合同/项目/资产密级、离线归档、敏感边界 | 有规则 | 禁止高敏正文进公网 OA;只记录摘要和编号 | +| 固定资产/IT 资产 | 资产台账、编号族、领用归还调拨盘点 | 已有基础 | 账号资产 EA-ACC 暂缓 | +| 信息安全/账号权限 | 用户管理、角色、离职 checklist、审计 | 已有基础 | 离职权限回收证据纳入 Day 7/后续月检 | + +## Invoice Verification Matrix + +| 候选 | 公开信息 | 集成判断 | 采购/风险 | 建议 | +| --- | --- | --- | --- | --- | +| 国家税务总局查验平台 | 官方说明支持最近 5 年、每张发票每日 5 次在线查验 | 不适合作为系统自动化生产接口 | 有频次和人工查验边界 | 只作为人工复核依据,不爬取 | +| 腾讯云 OCR 增值税发票核验 | 官方价格页显示首次 50 次免费资源包,阶梯价可见 | 与现有腾讯 OCR SDK 和凭据体系最贴近 | 需开通付费、限流、费用控制 | **推荐 POC 首选** | +| 百度智能云财务票据 OCR | 产品页声明支持 10 余类票据和增值税发票验真 | 可做替代方案 | 价格需控制台或商务确认 | 备选 | +| 华为云发票识别与验真 | 本轮公开资料访问需要安全验证,未纳入价格决策 | 接入需重新确认产品延续性 | 信息可得性不足 | 待二次确认 | +| 百望/诺诺类财税平台 | 更接近发票生命周期/财税平台 | 能力可能更完整,接入和采购更重 | 询价、合同和数据边界成本高 | 暂不作为首选 POC | + +## Execution Roadmap + +1. **本轮已完成**:创建任务总账、五张矩阵和四个子任务专项结论。 +2. **下一步主线**:回到 OAOPS1,继续 Day 3-Day 7 只读巡检和人工真实业务反馈。 +3. **第一批实施**:新建 PC 前端布局统一改造任务,优先工作台、列表/详情、财务密集页和 C 类管理页,不碰流程规则。 +4. **第二批实施**:新建测试缺口补齐任务,补制度签收、合同/用印、发票验真和真实闭环测试缺口。 +5. **第三批实施**:新建制度规则落地任务,将制度参数、签收、公示、交接和用印规则变成可执行清单。 +6. **第四批实施**:新建发票验真 provider POC 任务,仅在样票授权和预算确认后做真实联调。 + +## 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` +- 当前 OAOPS1 证据:`.trellis/tasks/05-26-oa-seven-day-trial-live-ops/research/` diff --git a/.trellis/tasks/05-27-oa-test-coverage-matrix/implement.md b/.trellis/tasks/05-27-oa-test-coverage-matrix/implement.md index 2e9f2074..39263bd2 100644 --- a/.trellis/tasks/05-27-oa-test-coverage-matrix/implement.md +++ b/.trellis/tasks/05-27-oa-test-coverage-matrix/implement.md @@ -2,7 +2,7 @@ ## Planning 口径 -本子任务先保持 planning。总任务完成后,再启动测试覆盖专项。 +本子任务已作为测试覆盖审查完成。后续补测试属于代码实施任务,应按风险分批启动。 ## 后续执行方式 @@ -16,3 +16,9 @@ - 不自动创建真实业务数据。 - 不执行真实付款、ERP 写入、企业微信写入或数据库重置。 - 不把只读巡检误写成完整业务写入测试通过。 + +## 完成记录 + +- 已形成业务流到后端、PC、移动、企业微信、公网只读巡检的覆盖矩阵。 +- 已识别高缺口:制度签收、用印台账、发票验真真实 provider、Day 7 真实闭环。 +- 已保留 Testing State Capsule,说明本轮没有跑全量 Vitest/E2E。 diff --git a/.trellis/tasks/05-27-oa-test-coverage-matrix/prd.md b/.trellis/tasks/05-27-oa-test-coverage-matrix/prd.md index 2d21a0f8..16680dcd 100644 --- a/.trellis/tasks/05-27-oa-test-coverage-matrix/prd.md +++ b/.trellis/tasks/05-27-oa-test-coverage-matrix/prd.md @@ -21,10 +21,10 @@ ## Acceptance Criteria -- [ ] 输出测试覆盖矩阵。 -- [ ] 明确每条业务流程是否有后端和前端覆盖。 -- [ ] 明确公网试运行只读巡检不能替代真实业务写入流程测试。 -- [ ] 给出第一批要补的测试清单和命令。 +- [x] 输出测试覆盖矩阵。 +- [x] 明确每条业务流程是否有后端和前端覆盖。 +- [x] 明确公网试运行只读巡检不能替代真实业务写入流程测试。 +- [x] 给出第一批要补的测试清单和命令。 ## Out of Scope @@ -46,3 +46,7 @@ git diff --check - Testing facts: `docs/测试规约与回归门禁.md` - Daily runner: `scripts/qa/run-oa-real-use-daily.sh` - Final readiness runner: `scripts/qa/run-oa-final-launch-readiness.sh` + +## Completion Note + +2026-05-27:审查型交付已完成,研究结论见 `research/test-coverage-matrix.md`。本轮不新增测试代码,后续缺口补齐需按业务流另起实施任务。 diff --git a/.trellis/tasks/05-27-oa-test-coverage-matrix/research/test-coverage-matrix.md b/.trellis/tasks/05-27-oa-test-coverage-matrix/research/test-coverage-matrix.md new file mode 100644 index 00000000..a68e7bc8 --- /dev/null +++ b/.trellis/tasks/05-27-oa-test-coverage-matrix/research/test-coverage-matrix.md @@ -0,0 +1,55 @@ +# 业务流程自动化测试覆盖矩阵 + +## Conclusion + +当前测试不是空白,前端 Playwright 和后端 Vitest 覆盖已经很重。主要缺口集中在:制度签收、用印台账、发票验真真实 provider、合同/采购/付款的真实试运行样本证据,以及最终 Day 7 Go/No-Go 汇总。 + +## Tooling + +| 层级 | 工具/命令 | +| --- | --- | +| Backend | `cd server && npm run prisma:validate && npm test` | +| Frontend static | `cd client && npm run typecheck && npm run build` | +| Frontend E2E | `cd client && npm run test:e2e` 或 focused Playwright | +| UI governance | `node scripts/qa/check-ui-design-rules.mjs` | +| Public smoke/readiness | `scripts/qa/run-oa-real-use-daily.sh`、`run-live-smoke-readiness.sh` | +| Trellis governance | `python3 ./.trellis/scripts/task.py validate `、`node scripts/qa/check-trellis-governance.mjs` | + +## Coverage Matrix + +| 业务流 | 后端覆盖 | 前端覆盖 | 公网/真实覆盖 | 缺口等级 | 建议 | +| --- | --- | --- | --- | --- | --- | +| 登录/邮箱/找回密码 | `auth.login.test`、email service | `login-portal-ux.spec` | SMTP 已本地/部署验证 | 低 | 继续回归即可 | +| 报销创建/提交/撤回 | `reimbursements.create/detail/withdraw` | `main-flow`、`r102`、`reimbursement-workflow-progress` | OAOPS1 只读;真实写入靠人工 | 中 | Day7 前补人工真实样本 | +| PDF OCR/查重/附件 | `invoicePool.upload/patch/bindable`、`ocrJob`、`invoiceGovernance` | `invoice-ocr-flow`、`r111`、`r125` | live OCR 辅助复核 | 低/中 | 自动验真另列 | +| 发票验真 | `verification.*`、`invoicePool/verification` | 票据中心未覆盖真实 provider | 无真实 provider | 高 | POC 后补 provider 单测和 E2E | +| 审批中心/自审/转审 | `workflow.*`、`utils/workflow` | `workflow-*`、`permission-direct-access` | OAOPS1 只读 | 低/中 | 真实业务闭环继续人工 | +| 付款批次/AP/回单 | `paymentBatches`、`financeLedger`、exports | `reimbursement-payment-batch-flow`、Wave4 | 历史公网短窗口和只读巡检 | 中 | Day7 真实付款闭环证据仍需人工 | +| 采购/费用 | `purchase.*` | `procurement-flow`、移动采购页 | 只读巡检 | 中 | 真实采购样本和制度参数待补 | +| 合同/项目 | `contractsRegistry`、`projects` | `project-workbench`、合同台账页面 | 只读巡检 | 中 | 合同归档/用印样本待补 | +| 资产/盘点/移动扫码 | `assets.*`、inventory | `assets-flow`、MobileAssetScan | ASSET1 证据 | 低/中 | 账号交接证据待制度映射 | +| 员工制度签收 | 员工培训/档案有部分 route 测试 | 无专门签收页 | 无 | 高 | 先人工签收;如阻断再开发 | +| 权限/审计 | `permissions.*`、audit/export | `permission-direct-access`、`settings-governance` | OAOPS1 只读 | 低 | 继续每日巡检 | + +## Focused Test Gap List + +1. 发票验真 provider POC:provider adapter 单测、feature flag、费用控制、失败降级、票据中心动作 E2E。 +2. 制度签收:人工证据先行;若开发,需员工签收 API、不可抵赖记录、公告区分、权限与导出测试。 +3. 用印台账:如果现有合同台账字段不足,需合同/用印字段、附件审计、导出和权限测试。 +4. Day 7 真实闭环:人工真实报销、采购/费用、合同台账、付款/AP、权限/审计证据应汇总到 OALAUNCH1。 +5. 备份恢复:最终启用前仍需独立批准的受控恢复演练证据。 + +## Commands Observed This Round + +- `node scripts/qa/check-ui-design-rules.mjs`:scanned 133 files, 0 findings. +- 任务治理校验在收口阶段执行。 + +## Testing State Capsule + +Goal: 建立业务流程测试覆盖矩阵,不新增测试代码。 +Repo signals: Backend Vitest, Frontend Playwright, Vite typecheck/build. +Unit commands: 待最终收口执行 Trellis/task governance;未跑全量 Vitest。 +Integration commands: 未执行全量 E2E;本轮引用既有测试清单和 OAOPS1 公网证据。 +Assumptions: 审查型任务不要求跑完整回归,只要求识别覆盖和缺口。 +Last result: UI design static scan 0 findings. +Next action: 后续专项按缺口补 focused tests。