# 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 变更，无数据回滚）。