docs(invoice): 发票申请最终契约 - 新增2文件 + 勘误2文件(#4290 #4292 #4302)

新增:
- changelogs-v2/2026-06/23_4290_发票申请入参票种修正-修改接口-管理后台.md
- changelogs-v2-mp/2026-06/23_4290_发票申请票种修正-修改接口-小程序端.md

勘误:
- 23_4258_发票详情接口:删除 mailAddress 出参字段、去掉 ELECTRONIC 枚举、email 改为始终有值
- 23_4265_发票列表:invoiceType 枚举去掉 ELECTRONIC(普票/专票两值)

契约定稿要点:invoiceType 只有 VAT_NORMAL/VAT_SPECIAL;email 始终必填+格式;
专票限 COMPANY 抬头(581523);专票五项全必填(581515);删 mailAddress(全电子交付)
这个提交包含在:
yaosutu
2026-06-23 16:05:51 +08:00
父节点 bfa877f3db
当前提交 a47eeeedcb
共修改 4 个文件,包含 646 行新增和 7 行删除
@@ -6,6 +6,11 @@
---
> **勘误(2026-06-23,#4292 #4302)**:本文件初版(#4262)包含 3 处与最终实现不符的内容,已在本次修正:
> 1. `invoiceType` 枚举已删除 `ELECTRONIC`(电子发票),只保留 `VAT_NORMAL`(增值税普通发票)和 `VAT_SPECIAL`(增值税专用发票)
> 2. 出参已删除 `mailAddress` 字段(无纸质邮寄,全电子交付)
> 3. `email` 字段始终有值(全电子交付),不再是"电子发票为 null"
## 接口背景
财务在「上传发票 PDF」弹窗或发票详情页中,需要读取完整的开票申请明细:抬头信息、开票金额、专票四项(银行账号、注册地址、注册电话)、开票后的发票号 / PDF / 推送记录。本接口返回单张发票的全量字段,供弹窗回显和详情页展示使用。
@@ -73,8 +78,7 @@
| `registAddress` | string / null | 注册地址,**仅专票**有值,其余 null |
| `registPhone` | string / null | 注册电话,**仅专票**有值,其余 null |
| `amount` | string | 开票金额,单位**分**,字符串防精度丢失,如 `"98600"` |
| `email` | string / null | 电子发票接收邮箱 |
| `mailAddress` | string / null | 纸质发票邮寄地址,电子发票为 null |
| `email` | string | 收件邮箱(始终有值,全电子交付) |
| `applyReason` | string / null | 备注(申请原因) |
### 状态字段
@@ -124,7 +128,6 @@
|--------|--------|------|
| `VAT_NORMAL` | 增值税普通发票 | 普票,专票四项字段均为 null |
| `VAT_SPECIAL` | 增值税专用发票 | 专票,bankName / bankAccount / registAddress / registPhone 有值 |
| `ELECTRONIC` | 电子发票 | 电子普票,mailAddress 为 null,仅 email 有值 |
### 抬头类型(titleType)
@@ -184,7 +187,6 @@ Authorization: Bearer <token>
"registPhone": null,
"amount": "98600",
"email": "finance@hulalv.com",
"mailAddress": null,
"applyReason": "报销使用",
"status": "REQUESTED",
"statusText": "待开票",
@@ -235,7 +237,6 @@ Authorization: Bearer <token>
"registPhone": "021-12345678",
"amount": "150000",
"email": null,
"mailAddress": "上海市浦东新区财务部",
"applyReason": null,
"status": "ISSUED",
"statusText": "已开票(待推送)",
@@ -288,7 +289,7 @@ Authorization: Bearer <token>
- 小程序端查询发票(本接口仅管理后台)
**特殊边界**
- 专票四项字段(`bankName` / `bankAccount` / `registAddress` / `registPhone`):仅 `invoiceType=VAT_SPECIAL` 时有值,前端按 invoiceType 决定是否展示这四项
- 专票五项字段(`taxNo` / `bankName` / `bankAccount` / `registAddress` / `registPhone`):taxNo 普票公司抬头也需填,专票四项仅 `invoiceType=VAT_SPECIAL` 时有值,前端按 invoiceType 决定是否展示
- 开票痕迹字段(`invoiceNo` / `fileUrl` / `pdfName` / `pdfSize` / `issuedBy` / `issuedAt`):状态为 `ISSUED` 或 `PUSHED` 时有值,`REQUESTED` 和 `VOIDED` 时为 null
- 推送痕迹字段(`pushedAt` / `pushedChannels`):仅 `PUSHED` 时有值
- `amount` 单位为**分**,前端展示时除以 100 转为元