6.7 KiB
6.7 KiB
Data Model: REV-005 发票业务流实现
建模原则
- 以“逻辑实体 + 现有在线主表承接 + 历史关系快照”三层表达，避免把旧系统全部 IV_* 细表误写为当前已落地在线表。
- 后台开票、客户侧查询下载、
SYS-008查询兜底、结果回写统一围绕单一发票申请主线建模。 - 一期不支持原始单账单直接任意部分开票，但关系模型需兼容拆账/分账后的多账单、多发票映射扩展。
实体一：InvoiceApplication（发票申请单）
作用
统一承接后台单笔/批量已收费账单的发票申请输入，是 IF-REV-008 的主业务对象。
核心字段
| 字段 | 类型 | 说明 |
|---|---|---|
| applicationNo | String | 发票申请单号 / 协同请求号 |
| chargeIds | Array | 关联账单 ID 列表 |
| custId | Long | 客户 ID |
| invoiceType | Enum | ELECTRONIC / PAPER |
| invoiceTitle | String | 发票抬头 |
| taxNo | String | 纳税人识别号 |
| invoiceAmount | Decimal | 本次申请开票总金额 |
| receiverEmail | String | 电子票接收邮箱 |
| receiverMobile | String | 电子票接收手机号 |
| sourceChannel | Enum | COUNTER / FINANCE_BACKOFFICE |
| applyStatus | Enum | SUBMITTED / ACCEPTED / REJECTED |
| appliedAt | DateTime | 申请时间 |
校验规则
chargeIds、custId、invoiceType、invoiceTitle必填。- 账单必须满足“已收费、未开票、未作废”。
- 原始单账单不允许直接任意部分金额开票；如需多张发票应来源于拆账/分账后的账单集合。
- 对同一账单组合的重复申请需按
applicationNo或custId + chargeIds做幂等控制。
物理承接
- 主承接：
biz_invoice - 关联输入：
biz_cust_invoice、biz_charge*
实体二：InvoiceRecord（发票记录）
作用
描述发票服务受理、开具成功/失败、票号回写、电子票文件地址等结果信息。
核心字段
| 字段 | 类型 | 说明 |
|---|---|---|
| invoiceId | Long | 发票记录 ID |
| applicationNo | String | 对应申请单号 |
| sysRequestNo | String | SYS-008 受理号 / 外部请求号 |
| invoiceStatus | Enum | PENDING / SUCCESS / FAIL / INVALID / RED_INK |
| invoiceCode | String | 发票代码 |
| invoiceNumber | String | 发票号码 |
| invoiceDate | DateTime | 开票日期 |
| fileUrl | String | 电子发票下载地址 |
| failReason | String | 开票失败原因 |
| pushStatus | Enum | NONE / PUSHED / FAIL |
| updatedAt | DateTime | 最近状态更新时间 |
状态关系
PENDING表示已提交给SYS-008但尚未确认最终结果。SUCCESS后允许客户侧查询、下载、推送电子发票。FAIL记录失败原因并进入异常核查或人工重试。
物理承接
- 主承接：
biz_invoice - 历史参照：旧
IV_INVOICE_INFOS
实体三：ChargeInvoiceRelation（账单-发票关联）
作用
承接账单与发票的映射关系，支持单票对应多账单、拆账后分别开票和后续合并开票扩展。
核心字段
| 字段 | 类型 | 说明 |
|---|---|---|
| relationId | Long | 关联记录 ID |
| chargeId | Long | 账单 ID |
| invoiceId | Long | 发票 ID |
| applicationNo | String | 申请单号 |
| relationType | Enum | FULL_AMOUNT / SPLIT_BILL / MERGED_BILL |
| invoiceAmount | Decimal | 当前账单对应开票金额 |
| relationStatus | Enum | PENDING / BOUND / FAILED |
| snapshotVersion | String | 开票配置/税率快照版本 |
关键规则
- 一期默认
relationType=FULL_AMOUNT或SPLIT_BILL（来自拆账后的账单），不支持对原始单账单直接自由部分金额开票。 - 发票成功后必须把关系状态更新为
BOUND，并可供账单详情查询。
物理承接
- 在线主承接：
biz_invoice+ 历史关系快照 - 历史参照：旧
IV_CHARGE_INVOICES、IV_CHARGE_INVOICE_MAPPINGS
实体四：InvoiceQueryTask（开票查询补偿任务）
作用
支持异步申请后的轮询查询、超时补偿和人工兜底查询，是“查询兜底”模式的核心对象。
核心字段
| 字段 | 类型 | 说明 |
|---|---|---|
| queryTaskId | Long | 查询任务 ID |
| applicationNo | String | 申请单号 |
| sysRequestNo | String | 外部受理号 |
| lastTryTime | DateTime | 最后一次查询时间 |
| nextTryTime | DateTime | 下一次查询时间 |
| tryCount | Integer | 已查询次数 |
| queryStatus | Enum | WAITING / RUNNING / DONE / FAILED |
| latestResult | String | 最近一次查询结果摘要 |
| latestError | String | 最近一次查询错误 |
关键规则
- 申请成功后默认生成查询任务。
- 查询到终态后任务进入
DONE。 - 查询异常不应覆盖已成功开票状态，只记录异常并等待人工或系统补偿。
物理承接
- 主承接：
biz_invoice扩展字段或关联查询日志对象 - 历史参照：旧发票表中的
last_try_time、next_try_time、try_count
实体五：InvoiceResultWriteBack（结果回写）
作用
统一描述 SYS-008 查询结果或主动回传结果进入营收域后的状态变更、幂等控制和操作留痕。
核心字段
| 字段 | 类型 | 说明 |
|---|---|---|
| writeBackNo | String | 回写流水号 |
| applicationNo | String | 申请单号 |
| invoiceStatus | Enum | 发票状态 |
| writeBackStatus | Enum | SUCCESS / IGNORE_REPEAT / FAIL |
| invoiceCode | String | 发票代码 |
| invoiceNumber | String | 发票号码 |
| fileUrl | String | 下载地址 |
| rawPayload | String | 原始回写/查询响应 |
| processedAt | DateTime | 处理时间 |
| processedBy | String | 系统任务 / 人工处理人 |
关键规则
- 按
applicationNo + invoiceStatus做幂等控制。 - 已成功开票后收到失败结果，不覆盖成功状态，转入异常核查。
- 所有回写处理必须记录到操作留痕对象。
物理承接
- 主承接：
biz_invoice+biz_operat_log*
关系总览
InvoiceApplication --> InvoiceRecord
InvoiceApplication --> ChargeInvoiceRelation
InvoiceApplication --> InvoiceQueryTask
InvoiceRecord --> InvoiceResultWriteBack
ChargeInvoiceRelation --> biz_charge* (N:1)
InvoiceApplication --> biz_cust_invoice
InvoiceApplication --> biz_invoice_taxrate
InvoiceResultWriteBack --> biz_operat_log*
状态与边界说明
- 一期默认后台申请、客户侧结果消费，不定义客户侧直接申请状态机。
- 作废、红冲作为 REV-005 后续能力保留在数据模型中，但 implement 时优先保证正常开票闭环。
- 旧发票明细、营业账开票关系、配置快照对象在当前阶段仅作为历史参照和追溯来源，不表述为已确认新增在线独立表。