hyb-oa/docs/invoice-pool-refactor-plan.md

invoicePool 路由拆分方案（P9A1）

1. 背景

• 现状：server/src/routes/invoicePool.js 超过 2700 行，上传、列表、详情、验真、归档、解绑、OCR 重试等职责集中在单文件。
• 风险：
  • 验真链路迭代时容易与票据主流程互相影响。
  • select 片段与响应映射逻辑重复，字段漂移不易发现。
  • 新人接手定位成本高，回归面过大。

2. 目标与非目标

• 目标：
  • 不改变现有 API 路径、权限码、响应结构。
  • 将验真端点独立到子模块，主文件保留入口职责。
  • 抽取 shared select/mapper，降低重复与字段遗漏风险。
• 非目标：
  • 不新增业务功能。
  • 不调整数据库模型与外部接口契约。

3. 拆分边界冻结

3.1 保留在 invoicePool.js 的能力

• 票据列表、上传、详情、编辑、归档、解绑、OCR 重试、判重例外、签名 URL 与文件读取。
• 入口职责：对外仍由 server/src/routes/invoicePool.js 注册全部 /api/invoice-pool/* 路径。

3.2 独立模块

• server/src/routes/invoicePool/verification.js
  • POST /invoice-pool/:id/verify
  • GET /invoice-pool/:id/verification
  • POST /invoice-pool/:id/verification/retry

3.3 shared 模块

• server/src/routes/invoicePool/shared/selects.js
  • 统一 verification_records 子查询。
  • 提供列表/详情 select builder。
• server/src/routes/invoicePool/shared/mappers.js
  • mapVerificationRecord
  • mapInvoiceSummary
  • normalizeInvoiceResponse
• server/src/routes/invoicePool/shared/schemas.js
  • 验真列表查询参数解析。
• server/src/routes/invoicePool/shared/helpers.js
  • 验真任务触发（pg-boss/inline 兼容）。

4. 迁移顺序

1. 新增 shared 模块与 verification.js，逻辑先保持等价迁移。
2. invoicePool.js 改为组合注册（调用 verification.js），删除内联验真端点。
3. 将列表与详情相关查询切换到 shared select builder。
4. 执行静态检查与验真回归脚本，确认无接口行为变化。

5. 兼容性与回滚

• 兼容性：
  • 路由路径、权限码、返回字段保持不变。
  • 错误码（VALID_001/PERM_001/SYS_404）保持原语义。
• 回滚策略：
  • 保留 invoicePool.js 入口文件与原有注册顺序。
  • 如发现回归，可将 verification.js 调用回切为原文件内联实现（无 schema 变更，无数据回滚）。