# Data Model: REV-005 发票业务流实现

## 建模原则

- 以“逻辑实体 + 现有在线主表承接 + 历史关系快照”三层表达，避免把旧系统全部 IV_* 细表误写为当前已落地在线表。
- 后台开票、客户侧查询下载、`SYS-008` 查询兜底、结果回写统一围绕单一发票申请主线建模。
- 一期不支持原始单账单直接任意部分开票，但关系模型需兼容拆账/分账后的多账单、多发票映射扩展。

## 实体一：InvoiceApplication（发票申请单）

### 作用
统一承接后台单笔/批量已收费账单的发票申请输入，是 `IF-REV-008` 的主业务对象。

### 核心字段

| 字段 | 类型 | 说明 |
|------|------|------|
| applicationNo | String | 发票申请单号 / 协同请求号 |
| chargeIds | Array<Long> | 关联账单 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*`

## 关系总览

```text
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 时优先保证正常开票闭环。
- 旧发票明细、营业账开票关系、配置快照对象在当前阶段仅作为历史参照和追溯来源，不表述为已确认新增在线独立表。