推 changelog：发票推送渠道改走数据字典 invoice_push_channel #4379（管理后台，PUT push 渠道合法值由硬编码改字典驱动+降级兜底，渠道值不变）
这个提交包含在：
yaosutu
父节点
a3bc9a3e17
当前提交
10340d0104
@ -0,0 +1,189 @@
|
||||
# 发票推送渠道改走数据字典 invoice_push_channel（管理后台）
|
||||
|
||||
- **接口**：PUT /v3/admin/order/invoice/{id}/push
|
||||
- **变更类型**：修改接口（推送渠道合法值由后端硬编码改为数据字典 `invoice_push_channel` 驱动）
|
||||
- **端类型**：管理后台
|
||||
- **日期**：2026-06-25
|
||||
- **Issue**：[#4379](https://git.1814.love:8443/wx/HL/issues/4379)
|
||||
- **PR**：[#4379](https://git.1814.love:8443/wx/HL/pulls/4379)
|
||||
|
||||
发票「推送客户」的渠道合法值（email/wechat/sms）原为后端硬编码，本次改为读取数据字典 `invoice_push_channel`，便于后续在字典中增删渠道而无需改代码。当前可选值与含义不变。
|
||||
|
||||
---
|
||||
|
||||
## 1 接口背景
|
||||
|
||||
发票详情页「推送客户」操作（PUT push），入参为渠道列表 `channels`。原后端在代码里硬编码合法渠道集合 `{email, wechat, sms}` 做校验；本次改为运行时读取数据字典 `invoice_push_channel` 的全部 ACTIVE 字典值作为合法集合。
|
||||
|
||||
- 字典为空或字典服务不可用时，**降级回硬编码 `{email, wechat, sms}`**，保证可用性。
|
||||
- 本期渠道值与含义**未变**，仍为 email/wechat/sms 三项。
|
||||
- 前端渠道下拉/多选项建议改为从字典接口拉取（见第 6 节），不再前端写死，后续字典增删渠道前端可自动同步。
|
||||
|
||||
---
|
||||
|
||||
## 2 变更清单
|
||||
|
||||
| # | 变更项 | 变更前 | 变更后 |
|
||||
|---|--------|--------|--------|
|
||||
| 1 | push 渠道合法值来源 | 后端硬编码 `{email, wechat, sms}` | 数据字典 `invoice_push_channel` 的 ACTIVE 字典值 |
|
||||
| 2 | 字典缺失/异常时行为 | 不适用 | 降级回硬编码 `{email, wechat, sms}` |
|
||||
| 3 | 入参字段 / 渠道值 | channels: string[]，值 email/wechat/sms | 不变（同前） |
|
||||
| 4 | 错误码 581521/581522 | 已存在 | 不变（语义同前，仅合法集合来源变化） |
|
||||
|
||||
> 接口路径、入参结构、出参、错误码均无变化；仅「合法渠道值的来源」从硬编码改为字典。
|
||||
|
||||
---
|
||||
|
||||
## 3 接口详情
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|----|
|
||||
| 方法 | PUT |
|
||||
| 路径 | /v3/admin/order/invoice/{id}/push |
|
||||
| 描述 | 将已开具发票推送给客户（多渠道多选）；本期仅落状态与渠道记录，不真发通知 |
|
||||
| 认证 | Bearer JWT（管理员） |
|
||||
| 幂等性 | 状态守卫，非幂等 |
|
||||
| 限流 | 无特殊限制 |
|
||||
|
||||
---
|
||||
|
||||
## 4 接口入参
|
||||
|
||||
### 4.1 路径参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| id | string（Long 雪花） | 是 | 发票记录 ID |
|
||||
|
||||
### 4.2 请求体字段（InvoicePushReqVO）
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| channels | string[] | 是 | 推送渠道，多选；每个值须为字典 `invoice_push_channel` 中的 ACTIVE 字典值（当前 email/wechat/sms）。空数组报 581521，含非法值报 581522 |
|
||||
|
||||
---
|
||||
|
||||
## 5 出参字段
|
||||
|
||||
操作成功返回 HTTP 200，data 为 null。
|
||||
|
||||
---
|
||||
|
||||
## 6 枚举 / 数据字典
|
||||
|
||||
### 6.1 推送渠道字典（invoice_push_channel）
|
||||
|
||||
合法渠道值来源由本次改为该字典。前端可调用字典接口 `GET /admin/dict/data/invoice_push_channel` 动态获取下拉项（dictValue 作为提交值，dictLabel 作为展示文案）。
|
||||
|
||||
| dictValue | dictLabel | sortOrder | status |
|
||||
|-----------|-----------|-----------|--------|
|
||||
| email | 邮件 | 10 | ACTIVE |
|
||||
| wechat | 微信 | 20 | ACTIVE |
|
||||
| sms | 短信 | 30 | ACTIVE |
|
||||
|
||||
> 提交 push 时 channels 传 dictValue（如 `email`），非 dictLabel。
|
||||
|
||||
---
|
||||
|
||||
## 7 错误码
|
||||
|
||||
| 错误码 | 常量 | 触发场景 |
|
||||
|--------|------|----------|
|
||||
| 581521 | INVOICE_PUSH_CHANNEL_REQUIRED | channels 为空（至少选一个渠道） |
|
||||
| 581522 | INVOICE_PUSH_CHANNEL_INVALID | channels 含非法值（不在字典 invoice_push_channel 的 ACTIVE 字典值内） |
|
||||
|
||||
---
|
||||
|
||||
## 8 示例
|
||||
|
||||
### 8.1 典型成功——推送邮件 + 微信
|
||||
|
||||
请求
|
||||
```
|
||||
PUT /v3/admin/order/invoice/2069957731908784129/push
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
```json
|
||||
{
|
||||
"channels": ["email", "wechat"]
|
||||
}
|
||||
```
|
||||
|
||||
响应
|
||||
```json
|
||||
{"code": 200, "msg": "success", "data": null}
|
||||
```
|
||||
|
||||
### 8.2 边界——单渠道短信
|
||||
|
||||
```json
|
||||
{"channels": ["sms"]}
|
||||
```
|
||||
响应
|
||||
```json
|
||||
{"code": 200, "msg": "success", "data": null}
|
||||
```
|
||||
|
||||
### 8.3 业务失败——非法渠道值
|
||||
|
||||
请求
|
||||
```json
|
||||
{"channels": ["fax"]}
|
||||
```
|
||||
响应
|
||||
```json
|
||||
{"code": 581522, "msg": "推送渠道非法（须为 email/wechat/sms）", "data": null}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9 业务边界
|
||||
|
||||
适用：
|
||||
- channels 非空，且每个值均为字典 `invoice_push_channel` 中的 ACTIVE 字典值。
|
||||
|
||||
不适用：
|
||||
- channels 为空数组 → 581521
|
||||
- channels 含任意非字典值 → 581522（即便其余值合法，整体拒绝）
|
||||
|
||||
特殊边界：
|
||||
- 字典 `invoice_push_channel` 不可用或为空时，后端降级回硬编码 `{email, wechat, sms}`，校验行为与改前一致。
|
||||
|
||||
---
|
||||
|
||||
## 10 修改前后对比
|
||||
|
||||
| 维度 | 变更前 | 变更后 |
|
||||
|------|--------|--------|
|
||||
| 合法渠道来源 | 代码硬编码 `{email, wechat, sms}` | 数据字典 `invoice_push_channel`（ACTIVE 字典值） |
|
||||
| 增删渠道 | 改代码 + 发版 | 维护字典即可（前端从字典接口取项可自动同步） |
|
||||
| 入参 / 出参 / 错误码 | — | 无变化 |
|
||||
| 当前可选渠道 | email/wechat/sms | email/wechat/sms（不变） |
|
||||
|
||||
---
|
||||
|
||||
## 11 影响评估 / 回滚
|
||||
|
||||
破坏兼容性：否
|
||||
|
||||
- 当前渠道值与含义未变，已写死 email/wechat/sms 的前端仍可正常提交，不会立即报错。
|
||||
- 建议前端将渠道选项改为从 `GET /admin/dict/data/invoice_push_channel` 拉取，以便后续字典增删渠道时自动同步。
|
||||
|
||||
回滚方案：回滚后端至 #4379 前版本，合法渠道恢复为硬编码 `{email, wechat, sms}`；字典 `invoice_push_channel` 保留不影响其他功能。
|
||||
|
||||
---
|
||||
|
||||
## 12 注意事项
|
||||
|
||||
1. 提交 channels 传 dictValue（`email`/`wechat`/`sms`），不是中文 dictLabel。
|
||||
2. 字典维护需保持 status=ACTIVE 才生效；置为非 ACTIVE 的渠道值将被视为非法（581522）。
|
||||
3. 本期 push 仅落状态与渠道记录，不真实发送通知。
|
||||
|
||||
---
|
||||
|
||||
## 13 关联 / 联系人
|
||||
|
||||
- **Issue**：[#4379](https://git.1814.love:8443/wx/HL/issues/4379)
|
||||
- **PR**：[#4379 发票推送渠道改走数据字典 invoice_push_channel](https://git.1814.love:8443/wx/HL/pulls/4379)
|
||||
- **后端负责人**：腰苏图（yaosutu）
|
||||
正在加载...
x
在新工单中引用
屏蔽一个用户