hl-api-changelog/changelogs-v2/2026-06/25_4379_发票推送渠道改走数据字典-修改接口-管理后台.md

发票推送渠道改走数据字典 invoice_push_channel（管理后台）

• 接口：PUT /v3/admin/order/invoice/{id}/push
• 变更类型：修改接口（推送渠道合法值由后端硬编码改为数据字典 invoice_push_channel 驱动）
• 端类型：管理后台
• 日期：2026-06-25
• Issue：#4379
• PR：#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

{
  "channels": ["email", "wechat"]
}

响应

{"code": 200, "msg": "success", "data": null}

8.2 边界——单渠道短信

{"channels": ["sms"]}

响应

{"code": 200, "msg": "success", "data": null}

8.3 业务失败——非法渠道值

请求

{"channels": ["fax"]}

响应

{"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
• PR：#4379 发票推送渠道改走数据字典 invoice_push_channel
• 后端负责人：腰苏图（yaosutu）