58 行
2.4 KiB
Markdown
58 行
2.4 KiB
Markdown
# 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 变更，无数据回滚）。
|
||
|