# Contract: IF-REV-009 发票结果查询与客户侧消费接口

## 1. 合同定位

本合同用于固化 REV-005 一期发票结果查询、查询兜底补偿以及客户侧查看/下载/推送已开票电子发票的统一口径。

## 2. 适用范围

适用场景：
- 后台按申请单号 / 受理号查询发票最终状态
- 系统定时轮询 `SYS-008` 获取开票结果
- 客户侧查看已开具电子发票
- 客户侧下载、推送电子发票

不适用范围：
- 客户侧直接发起开票申请
- 发票作废 / 红冲全流程深度处理

## 3. 查询请求合同

| 字段 | 类型 | 必填 | 说明 | 约束 |
|------|------|------|------|------|
| applicationNo | String | 否 | 发票申请单号 | 与 `sysRequestNo` 二选一 |
| sysRequestNo | String | 否 | 外部受理号 | 与 `applicationNo` 二选一 |
| custId | Long | 否 | 客户 ID | 客户侧查询时使用 |
| querySource | String | 是 | 查询来源 | `SYSTEM_JOB` / `ADMIN` / `CUSTOMER` |
| pushEmail | String | 否 | 推送邮箱 | 客户侧推送时使用 |

## 4. 查询响应合同

| 字段 | 类型 | 说明 | 约束 |
|------|------|------|------|
| invoiceId | Long | 发票记录 ID | 对应 `biz_invoice.id` |
| applicationNo | String | 发票申请单号 | 幂等主键 |
| invoiceStatus | String | 发票状态 | `PENDING` / `SUCCESS` / `FAIL` / `INVALID` / `RED_INK` |
| invoiceCode | String | 发票代码 | 成功后返回 |
| invoiceNumber | String | 发票号码 | 成功后返回 |
| fileUrl | String | 电子票下载地址 | 成功后返回 |
| failReason | String | 失败原因 | 失败时返回 |
| pushStatus | String | 推送状态 | `NONE` / `PUSHED` / `FAIL` |
| lastQueryTime | DateTime | 最近查询时间 | 用于补偿追踪 |

## 5. 共性规则

1. 查询兜底是开票结果获取的必备路径，不可省略。
2. 已成功开票状态不得被后续失败结果覆盖。
3. 客户侧只允许查询、下载、推送属于当前客户的已开票电子发票。
4. 下载/推送前必须校验发票状态为 `SUCCESS` 且存在 `fileUrl`。
5. 查询补偿任务需记录 `lastTryTime`、`nextTryTime`、`tryCount` 等信息。

## 6. 物理承接口径

| 逻辑对象 | 物理承接 |
|---------|----------|
| 发票结果主对象 | `biz_invoice` |
| 客户查询身份与资料 | `biz_cust_invoice` |
| 查询补偿与结果留痕 | `biz_invoice` 扩展字段 + `biz_operat_log*` |
| 账单发票摘要展示 | `biz_charge*` + 历史关系快照 |

## 7. 验收关注点

- 是否支持后台按申请单号 / 受理号查询结果
- 是否支持系统任务轮询补偿
- 是否支持客户侧查看、下载、推送已开票电子发票
- 是否避免客户侧越权查询和重复推送