66 lines
2.7 KiB
Markdown
66 lines
2.7 KiB
Markdown
# 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. 验收关注点
|
|
|
|
- 是否支持后台按申请单号 / 受理号查询结果
|
|
- 是否支持系统任务轮询补偿
|
|
- 是否支持客户侧查看、下载、推送已开票电子发票
|
|
- 是否避免客户侧越权查询和重复推送
|