# Contract: IF-REV-008 发票申请接口

## 1. 合同定位

本合同用于固化 REV-005 一期后台发票申请 / 单笔与批量开票接口口径，服务于后续正式接口文档修订、任务拆解与 backend 实施。

## 2. 适用范围

适用场景：
- 后台营业收费员 / 财务人员发起单笔开票
- 后台按已收费账单集合批量发起开票
- 生成发票申请记录并提交 `SYS-008`

不适用范围：
- 客户侧直接申请开票
- 原始单账单直接任意部分金额开票
- 复杂拆分/合并开票策略配置

## 3. 请求合同

| 字段 | 类型 | 必填 | 说明 | 约束 |
|------|------|------|------|------|
| applicationNo | String | 否 | 发票申请单号 | 服务端生成，作为幂等主键之一 |
| chargeIds | Array<Long> | 是 | 关联账单 ID 列表 | 所有账单必须已收费且未开票 |
| custId | Long | 是 | 客户 ID | 必须存在可用开票信息 |
| invoiceType | String | 是 | 发票类型 | `ELECTRONIC` / `PAPER` |
| invoiceTitle | String | 是 | 发票抬头 | 来自 `biz_cust_invoice` 或后台确认输入 |
| taxNo | String | 否 | 纳税人识别号 | 企业抬头场景建议必填 |
| email | String | 否 | 接收邮箱 | 电子发票场景优先使用 |
| mobile | String | 否 | 接收手机号 | 推送或通知场景使用 |
| sourceChannel | String | 是 | 来源渠道 | `COUNTER` / `FINANCE_BACKOFFICE` |
| remark | String | 否 | 申请备注 | 进入操作留痕 |

## 4. 响应合同

| 字段 | 类型 | 说明 | 约束 |
|------|------|------|------|
| invoiceId | Long | 发票申请记录 ID | 对应 `biz_invoice.id` |
| applicationNo | String | 发票申请单号 | 后续查询与幂等主键 |
| invoiceStatus | String | 当前状态 | `SUBMITTED` / `PENDING` / `REJECTED` |
| sysRequestNo | String | `SYS-008` 受理号 | 异步查询主键 |
| msg | String | 处理说明 | 不可开票时返回明确原因 |

## 5. 共性规则

1. 所有账单必须处于“已收费、未开票、未作废”状态。
2. 一期不支持对原始单账单直接任意部分金额开票。
3. 如需多张发票，需来源于拆账/分账后的账单集合。
4. 幂等控制可采用 `applicationNo` 或 `custId + chargeIds` 组合。
5. 申请成功后必须生成查询补偿任务，不可依赖回调作为唯一结果来源。
6. 所有申请动作必须写入操作留痕。

## 6. 物理承接口径

| 逻辑对象 | 物理承接 |
|---------|----------|
| 发票申请主对象 | `biz_invoice` |
| 客户开票信息 | `biz_cust_invoice` |
| 税率配置 | `biz_invoice_taxrate` |
| 关联账单 | `biz_charge*` |
| 操作留痕 | `biz_operat_log*` |

## 7. 验收关注点

- 是否支持后台单笔 / 批量已收费账单开票
- 是否拒绝原始单账单直接部分金额开票
- 是否生成申请单号与查询主键
- 是否与 `SYS-008` 查询兜底模式一致