# 发票申请票种修正（最终契约）— 小程序端

> 变更类型：修改接口（破坏性）
> 端类型：小程序端
> 日期：2026-06-23 | Issue：#4296 | PR：#4292 / #4302 | 服务：hl-order-service-v3

> ⚠️ **破坏性变更**：`invoiceType` 删除 `ELECTRONIC`、`email` 改为始终必填 + 格式校验、专票限公司抬头 + 必填五项、删除 `mailAddress` 字段。小程序开票页与详情页均需同步改动，上线时前后端须同步发布。

> **勘误（截至 PR #4311 收口）**：抬头字段统一 `titleName`、金额 `amount` 改 JSON number（单位元，非分/x100）、票种仅 2 值（`VAT_NORMAL`/`VAT_SPECIAL`）、专票限公司抬头、入参和出参均无 `mailAddress`。关联 Issue [#4290](https://git.1814.love:8443/wx/HL/issues/4290) [#4296](https://git.1814.love:8443/wx/HL/issues/4296) [#4310](https://git.1814.love:8443/wx/HL/issues/4310) / PR [#4292](https://git.1814.love:8443/wx/HL/pulls/4292) [#4302](https://git.1814.love:8443/wx/HL/pulls/4302) [#4311](https://git.1814.love:8443/wx/HL/pulls/4311)。

---

## 接口背景

发票模型经 PR #4292 + #4302 多轮修正后定稿：删除「电子发票」票种（业务决策统一走普票），专票收严字段校验（限公司抬头 + 必填银行注册信息），email 改为始终必填（全系统电子交付），删除纸质邮寄字段 `mailAddress`。

本次涉及小程序两个接口：初次申请 `POST /v3/internal/mp/order/{orderId}/invoice/apply` 和重新开票 `POST /v3/internal/mp/invoice/{id}/reissue`，入参字段矩阵相同，出参亦做同步修正（删 `mailAddress`，invoiceType 去 ELECTRONIC）。

---

## 变更清单

| # | 变更类型 | 说明 |
|---|---------|------|
| 1 | ⚠️ 申请入参删枚举值 | `invoiceType` 删除 `ELECTRONIC`，只保留 `VAT_NORMAL` / `VAT_SPECIAL` |
| 2 | ⚠️ 申请入参删字段 | 删除 `mailAddress`（纸质邮寄地址） |
| 3 | ⚠️ 申请入参校验收严 | `email` 改为始终必填 + 邮箱格式校验 |
| 4 | ⚠️ 申请入参校验新增 | `taxNo`：单位抬头或专票时必填 |
| 5 | ⚠️ 申请入参校验新增 | 专票：`bankName` / `bankAccount` / `registAddress` / `registPhone` 四项必填 |
| 6 | ⚠️ 申请入参新增错误码 | `581523` 专票只能开给单位 |
| 7 | ⚠️ 详情出参删字段 | `GET /v3/internal/mp/order/{orderId}/invoice/detail` 出参删除 `mailAddress` |
| 8 | ⚠️ 列表出参枚举收窄 | `GET /v3/internal/mp/order/{orderId}/invoice/list` 出参 invoiceType 不再出现 ELECTRONIC |
| 9 | 重开接口同步 | `POST /v3/internal/mp/invoice/{id}/reissue` 入参字段矩阵与申请接口保持一致 |

---

## 接口详情

### 小程序申请接口

| 项 | 说明 |
|---|------|
| **方法 + 路径** | `POST /v3/internal/mp/order/{orderId}/invoice/apply` |
| **接口名** | 小程序客户自主申请发票 |
| **描述** | 客户在订单完成后自主提交开票申请，支持普票/专票，全电子交付 |
| **认证** | 小程序 JWT（Bearer Token，C 端用户） |
| **幂等性** | 非幂等，重复提交触发 581511（一单一票） |
| **限流** | 无特殊限流 |

### 小程序重开接口

| 项 | 说明 |
|---|------|
| **方法 + 路径** | `POST /v3/internal/mp/invoice/{id}/reissue` |
| **接口名** | 小程序重新开票 |
| **描述** | 旧发票作废后，客户重新提交开票申请；入参字段矩阵与 apply 接口相同 |
| **认证** | 小程序 JWT（Bearer Token，C 端用户） |
| **幂等性** | 非幂等 |
| **限流** | 无特殊限流 |

---

## 接口入参

### 路径参数

**apply 接口：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `orderId` | string（Long 雪花 ID） | 是 | 订单 ID |

**reissue 接口：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `id` | string（Long 雪花 ID） | 是 | 被重开的旧发票 ID |

### 请求体字段（两接口共用）

| 字段名 | 类型 | 必填条件 | 说明 |
|--------|------|---------|------|
| `invoiceType` | string | 始终必填 | 发票类型：`VAT_NORMAL`（普票）/ `VAT_SPECIAL`（专票）；**不含 ELECTRONIC** |
| `titleType` | string | 始终必填 | 抬头类型：`COMPANY`（单位）/ `PERSONAL`（个人）；**VAT_SPECIAL 只能 COMPANY** |
| `titleName` | string | 始终必填 | 发票抬头 |
| `taxNo` | string | `titleType=COMPANY` 或 `invoiceType=VAT_SPECIAL` 时必填 | 纳税人识别号 |
| `bankName` | string | `invoiceType=VAT_SPECIAL` 时必填 | 开户银行 |
| `bankAccount` | string | `invoiceType=VAT_SPECIAL` 时必填 | 银行账号 |
| `registAddress` | string | `invoiceType=VAT_SPECIAL` 时必填 | 注册地址 |
| `registPhone` | string | `invoiceType=VAT_SPECIAL` 时必填 | 注册电话 |
| `amount` | number | 始终必填 | 开票金额，JSON number，单位**元**（如 `986.00`），须 > 0 且不超过订单总金额 |
| `email` | string | 始终必填 | 收件邮箱，须通过邮箱格式校验 |
| `remark` | string | 选填 | 备注 |

> ⚠️ `mailAddress` 字段**已删除**，不再接收。

---

## 出参字段

### apply / reissue 接口出参

返回结构：`Result<Long>`

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `data` | string | 新建/重开发票 ID，字符串雪花 ID |

### 发票详情出参变化（GET /v3/internal/mp/order/{orderId}/invoice/detail）

| 字段名 | 变化 | 说明 |
|--------|------|------|
| `mailAddress` | **已删除** | 原出参中此字段已移除，前端不应再渲染邮寄地址 |
| `invoiceType` | 值范围收窄 | 只会出现 `VAT_NORMAL` / `VAT_SPECIAL`，不再出现 `ELECTRONIC` |
| `email` | 始终有值 | 原可能为 null，现始终有值 |

---

## 枚举 / 数据字典

### 发票类型（invoiceType）

| 枚举值 | 中文名 | 适用抬头 | 专票字段要求 |
|--------|--------|---------|------------|
| `VAT_NORMAL` | 增值税普通发票 | COMPANY / PERSONAL | 专票四项均不需要 |
| `VAT_SPECIAL` | 增值税专用发票 | **仅 COMPANY** | taxNo + bankName + bankAccount + registAddress + registPhone 全必填 |

> ~~`ELECTRONIC`~~ 已删除，不得传入。

### 抬头类型（titleType）

| 枚举值 | 中文名 | 可选票种 |
|--------|--------|---------|
| `COMPANY` | 单位 | VAT_NORMAL / VAT_SPECIAL |
| `PERSONAL` | 个人 | 只能 VAT_NORMAL，选 VAT_SPECIAL 返回 581523 |

---

## 错误码

| 错误码 | 含义 | 触发场景 |
|--------|------|---------|
| `581510` | 订单未完成，不可开票 | 订单状态不是 COMPLETED |
| `581511` | 一单一票，已有有效发票 | 已有 REQUESTED / ISSUED / PUSHED 状态发票 |
| `581512` | 开票金额超订单总额 | `amount` > 订单 `orderAmount` |
| `581513` | 发票类型非法 | `invoiceType` 不是 VAT_NORMAL 或 VAT_SPECIAL |
| `581514` | 公司抬头或专票须填税号 | 单位抬头或专票时 `taxNo` 为空 |
| `581515` | 专票须填银行及注册信息 | 专票时任一四项为空 |
| `581516` | 收件邮箱不能为空 | HTTP 400，入参层 @NotBlank 校验；格式错误返回 400「邮箱格式不正确」 |
| `581523` | 专票只能开给单位 | `invoiceType=VAT_SPECIAL` 且 `titleType=PERSONAL` |
| `401` | 未授权 | 未携带有效 JWT |
| `403` | 无权限 / 越权 | 非订单归属用户操作 |

---

## 示例

### 典型成功（增值税普通发票，个人抬头）

请求：
```
POST /v3/internal/mp/order/1920000000000000001/invoice/apply
Authorization: Bearer <mp-token>
Content-Type: application/json
```
```json
{
  "invoiceType": "VAT_NORMAL",
  "titleType": "PERSONAL",
  "titleName": "张三",
  "taxNo": null,
  "amount": 986.00,
  "email": "zhangsan@qq.com",
  "remark": "旅游报销"
}
```

响应：
```json
{
  "code": 200,
  "msg": "success",
  "data": "1934567890123456789"
}
```

### 典型成功（增值税专用发票，公司抬头，全字段）

请求：
```
POST /v3/internal/mp/order/1920000000000000002/invoice/apply
Authorization: Bearer <mp-token>
Content-Type: application/json
```
```json
{
  "invoiceType": "VAT_SPECIAL",
  "titleType": "COMPANY",
  "titleName": "某某科技有限公司",
  "taxNo": "91310000XXXXXXXXXX",
  "bankName": "招商银行上海支行",
  "bankAccount": "1234567890123456",
  "registAddress": "上海市浦东新区XX路XX号",
  "registPhone": "021-88888888",
  "amount": 2980.00,
  "email": "finance@company.com"
}
```

响应：
```json
{
  "code": 200,
  "msg": "success",
  "data": "1934567890123456790"
}
```

### 业务失败（专票个人抬头，错误码 581523）

请求：
```
POST /v3/internal/mp/order/1920000000000000003/invoice/apply
Authorization: Bearer <mp-token>
Content-Type: application/json
```
```json
{
  "invoiceType": "VAT_SPECIAL",
  "titleType": "PERSONAL",
  "titleName": "李四",
  "taxNo": null,
  "amount": 500.00,
  "email": "lisi@example.com"
}
```

响应：
```json
{
  "code": 581523,
  "msg": "增值税专用发票只能开给单位，个人抬头不可选专票",
  "data": null
}
```

---

## 业务边界

**适用场景**
- 客户在小程序「我的订单 - 订单详情」中点「申请发票」，订单状态为 COMPLETED 时可用
- 旧发票被作废后，客户在小程序发起重新申请（reissue 接口）

**不适用场景**
- 订单未完成（非 COMPLETED 状态），返回 581510
- 已有有效发票，须先由财务作废后才能 reissue，不能再次 apply
- 管理后台代客申请走 admin 专属接口

**特殊边界**
- 金额单位：`amount` 为 JSON number，单位**元**（如 `986.00`），前端输入框以元为单位直接提交，无需 x100
- 一单一票：同一订单至多一张有效发票
- 专票抬头联动：选专票后，抬头类型需强制为单位，个人选项需禁用或隐藏
- 详情回显：`mailAddress` 字段已不存在，前端不应渲染邮寄地址块

---

## 修改前后对比

### 发票类型枚举

| 旧值 | 新值 |
|------|------|
| VAT_NORMAL（保留） | VAT_NORMAL（保留） |
| VAT_SPECIAL（保留） | VAT_SPECIAL（保留） |
| ELECTRONIC（电子发票） | **已删除** |

### email 字段校验

| 旧行为 | 新行为 |
|--------|--------|
| 条件必填（ELECTRONIC 时才必填） | **始终必填 + 邮箱格式校验** |

### mailAddress 字段

| 旧行为 | 新行为 |
|--------|--------|
| 申请入参可选填；详情/列表出参包含此字段 | **申请入参已删除；详情出参已删除** |

### 专票限制

| 旧行为 | 新行为 |
|--------|--------|
| titleType 无限制 | 专票只能 COMPANY（个人返回 581523） |
| bankName 等无强制要求 | 专票 taxNo + 银行四项全部必填（返回 581515） |

---

## 影响评估 / 回滚

### 小程序开票页必须改动

| 模块 | 必须改动 |
|------|---------|
| 发票类型选择 | 去掉「电子发票」，只保留「增值税普通发票」/「增值税专用发票」 |
| 专票表单区块 | 新增开户行、银行账号、注册地址、注册电话 4 个必填项，仅选专票时显示 |
| 抬头类型联动 | 选专票时隐藏/禁用「个人」选项 |
| email 输入框 | 改为必填（加红星），增加邮箱格式校验 |
| mailAddress 输入框 | 移除，不再渲染邮寄地址块 |
| 详情页 | 移除邮寄地址展示区，invoiceType 显示只有普票/专票两种文案 |

### 回滚方案

后端回滚至 PR #4292 前，ELECTRONIC 重新有效，email 恢复条件必填，mailAddress 重新可用。小程序需同步回滚开票页逻辑。

---

## 注意事项

1. `ELECTRONIC` 已从枚举删除，小程序开票选项只有两项，禁止出现「电子发票」
2. 重开接口（reissue）入参字段矩阵与 apply 完全相同，改动同步适用
3. 专票五项（taxNo + 开户行 + 账号 + 注册地址 + 注册电话）在专票场景下全必填，缺一返回 581515
4. 详情页 `mailAddress` 字段已消失，老版本小程序读到 undefined 需做好空值守卫（不报错）
5. `amount` 为 JSON number，单位**元**（如 `986.00`），小程序输入框直接传元值，无需 x100

---

## 关联 / 联系人

| 项 | 内容 |
|----|------|
| **Issue（功能）** | [#4290 发票申请票种修正](https://git.1814.love:8443/wx/HL/issues/4290) |
| **Issue（小程序）** | [#4296 小程序发票申请同步修正](https://git.1814.love:8443/wx/HL/issues/4296) |
| **PR（票种删 ELECTRONIC）** | [#4292](https://git.1814.love:8443/wx/HL/pulls/4292) |
| **PR（专票限公司/email 必填/删 mailAddress）** | [#4302](https://git.1814.love:8443/wx/HL/pulls/4302) |
| **后端负责人** | yst |