From 10340d0104d30b5583f665520844ab4e44c52fc4 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Thu, 25 Jun 2026 10:35:13 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8E=A8=20changelog=EF=BC=9A=E5=8F=91?= =?UTF-8?q?=E7=A5=A8=E6=8E=A8=E9=80=81=E6=B8=A0=E9=81=93=E6=94=B9=E8=B5=B0?= =?UTF-8?q?=E6=95=B0=E6=8D=AE=E5=AD=97=E5=85=B8=20invoice=5Fpush=5Fchannel?= =?UTF-8?q?=20#4379=EF=BC=88=E7=AE=A1=E7=90=86=E5=90=8E=E5=8F=B0=EF=BC=8CP?= =?UTF-8?q?UT=20push=20=E6=B8=A0=E9=81=93=E5=90=88=E6=B3=95=E5=80=BC?= =?UTF-8?q?=E7=94=B1=E7=A1=AC=E7=BC=96=E7=A0=81=E6=94=B9=E5=AD=97=E5=85=B8?= =?UTF-8?q?=E9=A9=B1=E5=8A=A8+=E9=99=8D=E7=BA=A7=E5=85=9C=E5=BA=95?= =?UTF-8?q?=EF=BC=8C=E6=B8=A0=E9=81=93=E5=80=BC=E4=B8=8D=E5=8F=98=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...票推送渠道改走数据字典-修改接口-管理后台.md | 189 ++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 changelogs-v2/2026-06/25_4379_发票推送渠道改走数据字典-修改接口-管理后台.md diff --git a/changelogs-v2/2026-06/25_4379_发票推送渠道改走数据字典-修改接口-管理后台.md b/changelogs-v2/2026-06/25_4379_发票推送渠道改走数据字典-修改接口-管理后台.md new file mode 100644 index 0000000..8f7100f --- /dev/null +++ b/changelogs-v2/2026-06/25_4379_发票推送渠道改走数据字典-修改接口-管理后台.md @@ -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 +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）