docs(mp): C端发票切流v3状态枚举值域变化+email必填收紧 (#7252)

2026-09-07 12:05:07 +08:00
@@ -0,0 +1,156 @@
+---
+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)