---
schema: "hl-changelog/v2"
ticket: "7252"
title: "C端发票切流 order-v3：状态枚举值域变化 + email 必填收紧"
consumer: "mp"
author: "yst(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: "2026-09-07"
status_note: "C端发票 4 接口后端由 order-v2 切到 order-v3，路径/入参/出参字段名零变化；但状态枚举值域变化（PENDING→REQUESTED 等）+ email 必填收紧，前端需适配状态映射与表单校验。后端/网关已测试服验证，前端待消费。"
updated_at: "2026-09-07"
base: "dev-v3"
---

# 【修改接口·小程序端】C端发票切流 order-v3：状态枚举值域变化 + email 必填收紧（#7252）

## 1. 接口背景

order-v2 全量下线工程，C 端发票 invoice 由 order-v2 切流到 order-v3 发票域承接。**4 个对外接口的路径、请求方法、入参字段名、出参字段名全部不变**，前端无需改请求地址与字段名。

但后端切换带来 **2 处对外可见的行为变化**，前端需要适配：
1. **发票状态 `status` 枚举值域变化**（v2 → v3 值不同）
2. **email 由可选变为必填**（v3 服务端强制校验）

## 2. 变更清单

| 接口 | 路径 | 方法 | 变化 |
|---|---|---|---|
| 申请开票 | `/mp/invoice/apply` | POST | 出参 status 值域变化；email 必填收紧 |
| 发票详情 | `/mp/invoice/{id}` | GET | 出参 status 值域变化 |
| 按订单查发票 | `/mp/invoice/order/{orderId}` | GET | 出参 status 值域变化；未开票仍返 data=null |
| 发票换开 | `/mp/invoice/{invoiceId}/reissue` | POST | 出参 status 值域变化；email 必填收紧 |

## 3. 接口详情

路径 / 方法 /  Content-Type 均不变。仅出参 `status` 的**取值集合**与入参 `email` 的**必填性**变化。

## 4. 入参

入参字段名、类型、必填性**基本不变**，唯一变化：

- `email`（申请开票 / 换开）：**由可选变为必填**。前端若不传 email，v3 服务端返回 400「收件邮箱不能为空」。建议前端表单将邮箱设为必填项。

## 5. 出参

出参字段名、类型不变。**唯一变化是 `status` 字段的取值集合**：

| 维度 | v2 旧值（切流前） | v3 新值（切流后） |
|---|---|---|
| status 枚举 | `PENDING` / `ISSUED` / `CANCELLED` | `REQUESTED` / `ISSUED` / `VOIDED` / `FAILED` |

映射关系（供前端文案/样式适配参考）：
- `REQUESTED` ≈ 旧 `PENDING`（已申请待开票）
- `ISSUED` = 旧 `ISSUED`（已开票，不变）
- `VOIDED` ≈ 旧 `CANCELLED`（已作废）
- `FAILED` 为 v3 新增（开票失败）

其余出参字段（id / invoiceId / orderId / invoiceTitle / taxNumber / titleType / amount / invoiceUrl / pdfUrl / fileUrl / createdAt / issuedAt）字段名与类型均不变。

## 6. 枚举/数据字典

发票状态 `status`：
- `REQUESTED` 待开票（已提交申请）
- `ISSUED` 已开票
- `VOIDED` 已作废（换开后原发票作废为此态）
- `FAILED` 开票失败

抬头类型 `titleType`（不变）：`PERSONAL` 个人 / `COMPANY` 单位。

## 7. 错误码

- `600004` 订单ID格式错误（apply 时 orderId 非数字兜底）
- email 缺失：v3 服务端 Bean Validation 返 400「收件邮箱不能为空」
- `581500` 发票不存在（含归属校验：非本订单属主查询时也返此码）

## 8. 示例

### 典型：申请开票（email 必填）
```json
POST /mp/invoice/apply
{
  "orderId": "2091418470443810817",
  "invoiceTitle": "上海呼籁旅行科技有限公司",
  "titleType": "COMPANY",
  "taxNumber": "91310115MA1K48XXXX",
  "email": "finance@hulalv.com",
  "remark": "对公开票"
}
```
响应（status 为新值域）：
```json
{
  "code": 200,
  "data": {
    "id": "2091422818997612545",
    "invoiceId": "2091422818997612545",
    "orderId": "2091418470443810817",
    "invoiceTitle": "上海呼籁旅行科技有限公司",
    "taxNumber": "91310115MA1K48XXXX",
    "titleType": "COMPANY",
    "status": "REQUESTED",
    "invoiceUrl": null,
    "pdfUrl": null,
    "fileUrl": null,
    "createdAt": "2026-09-07 12:00:00",
    "issuedAt": null
  }
}
```

### 边界：按订单查发票（未开票）
```json
GET /mp/invoice/order/2091418470443810817
→ { "code": 200, "data": null }
```

### 异常：email 缺失
```json
POST /mp/invoice/apply  （body 无 email）
→ { "code": 400, "message": "收件邮箱不能为空" }
```

## 9. 业务边界

- `invoiceUrl` / `pdfUrl` 为历史遗留字段，恒为 null（v2 侧从未赋值），前端不应依赖，请使用 `fileUrl`。
- 申请开票时 `invoiceType` 固定按增值税普通发票（VAT_NORMAL）提交，C 端入参无发票类型选择字段。
- 换开成功后旧发票置 VOIDED，返回新发票完整信息。

## 10. 修改前后对比

| 项 | 修改前（v2） | 修改后（v3） |
|---|---|---|
| 后端服务 | order-v2 | order-v3 |
| status 值域 | PENDING/ISSUED/CANCELLED | REQUESTED/ISSUED/VOIDED/FAILED |
| email 必填 | 可选 | 必填（缺失返 400） |

## 11. 影响评估 / 回滚

- 前端需适配：①状态文案/样式映射按新枚举 ②邮箱表单必填。
- 回滚：后端可切回 v2 client（需回滚 mp-service 代码并重新部署）。

## 12. 注意事项

- 路径与字段名零变化，前端**不需要改请求地址**，只需处理状态枚举值与 email 必填。
- 若前端对 status 有硬编码判断（如 `status === 'PENDING'`），必须改为新值 `REQUESTED`。

## 13. 关联 / 联系人

- Issue：https://git.1814.love:8443/wx/HL/issues/7252
- PR：https://git.1814.love:8443/wx/HL/pulls/7255
- 负责人：yst(GIT)