diff --git a/changelogs-v2/2026-06/25_4395_发票推送明细日志-新增接口-管理后台.md b/changelogs-v2/2026-06/25_4395_发票推送明细日志-新增接口-管理后台.md new file mode 100644 index 0000000..ec25f75 --- /dev/null +++ b/changelogs-v2/2026-06/25_4395_发票推送明细日志-新增接口-管理后台.md @@ -0,0 +1,202 @@ +# 发票推送明细日志(push-logs 接口 + 详情 pushLogs 数组)(管理后台) + +- **接口**:GET /v3/admin/order/invoice/{id}/push-logs(新增) + GET /v3/admin/order/invoice/{id}(详情出参新增 pushLogs) +- **变更类型**:新增接口 + 修改接口(详情出参新增数组字段) +- **端类型**:管理后台 +- **日期**:2026-06-25 +- **Issue**:[#4395](https://git.1814.love:8443/wx/HL/issues/4395) +- **PR**:[#4397](https://git.1814.love:8443/wx/HL/pulls/4397) + +发票「推送客户」由原来只记最后一次,升级为每渠道每次一条明细记录(含操作人/时间/渠道/状态)。新增推送历史查询接口,发票详情出参新增 `pushLogs` 数组。 + +--- + +## 1 接口背景 + +发票推送(PUT /v3/admin/order/invoice/{id}/push)原仅在发票行覆盖记最后一次推送的时间/渠道,无操作人、无多次历史、无逐渠道记录,财务无法回查「是否给客户推送过、推过几次、哪个渠道、谁推的」。 + +本次新增独立推送明细:每次推送按渠道逐条落库(一次推 email+sms = 2 条),并提供两个查询入口——独立的推送历史列表接口,以及发票详情出参内联 `pushLogs` 数组。 + +--- + +## 2 变更清单 + +| # | 变更项 | 说明 | +|---|--------|------| +| 1 | 新增接口 GET /{id}/push-logs | 查发票推送明细历史(每渠道每次一条,按推送时间倒序) | +| 2 | 详情出参新增 pushLogs | GET /{id} 响应新增推送明细数组,同一结构 | +| 3 | 推送行为 | 每次推送按渠道逐条落明细(含操作人/时间/渠道/状态),多次推送累积不覆盖 | + +> 推送提交接口(PUT /{id}/push)入参/出参/错误码本次不变。 + +--- + +## 3 接口详情 + +### 3.1 推送明细列表(新增) + +| 属性 | 值 | +|------|----| +| 方法 | GET | +| 路径 | /v3/admin/order/invoice/{id}/push-logs | +| 描述 | 查询某发票的推送明细历史,每渠道每次一条,按推送时间倒序 | +| 认证 | Bearer JWT(管理员) | + +### 3.2 发票详情(出参新增 pushLogs) + +| 属性 | 值 | +|------|----| +| 方法 | GET | +| 路径 | /v3/admin/order/invoice/{id} | +| 描述 | 发票详情,本次出参新增 `pushLogs` 数组(结构同 3.1 列表项) | +| 认证 | Bearer JWT(管理员) | + +--- + +## 4 接口入参 + +### 4.1 push-logs 路径参数 + +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| id | string(Long 雪花) | 是 | 发票记录 ID | + +无请求体、无 Query 参数。 + +--- + +## 5 出参字段 + +### 5.1 push-logs 响应(`Result>`) + +data 为推送明细数组,每项字段: + +| 字段 | 类型 | 说明 | +|------|------|------| +| channel | string | 推送渠道(单值):email / wechat / sms | +| pushStatus | string | 推送状态:SUCCESS / FAILED / PENDING | +| statusText | string | 推送状态文案:成功 / 失败 / 待发 | +| pushedBy | string | 操作人真实姓名 | +| pushedAt | string(datetime) | 推送时间 | +| failReason | string | 失败原因(预留,SUCCESS 时为 null) | + +> 列表按 pushedAt 倒序。一次推送多渠道 → 每渠道一条;多次推送累积,不覆盖。 + +### 5.2 发票详情新增字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| pushLogs | array | 推送明细数组,元素结构同 5.1,按 pushedAt 倒序 | + +> 详情其余字段不变。 + +--- + +## 6 枚举 / 数据字典 + +### 6.1 推送状态(pushStatus) + +| code | 文案 | 说明 | +|------|------|------| +| SUCCESS | 成功 | 当前所有推送记录均为此值 | +| FAILED | 失败 | 预留(接真实通知网关后启用) | +| PENDING | 待发 | 预留 | + +### 6.2 推送渠道(channel) + +单值,取自数据字典 `invoice_push_channel`(email / wechat / sms)。前端渠道文案可用该字典 dictLabel 映射。 + +> 说明:本期推送不对接真实邮件/微信/短信网关,仅登记推送动作,pushStatus 恒为 SUCCESS。 + +--- + +## 7 错误码 + +| 错误码 | 常量 | 触发场景 | +|--------|------|----------| +| 581501 | INVOICE_NOT_FOUND | id 对应发票不存在 | + +--- + +## 8 示例 + +### 8.1 典型成功——查推送明细 + +请求 +``` +GET /v3/admin/order/invoice/2070039024382193666/push-logs +Authorization: Bearer +``` +响应(一次推 email+sms,得 2 条) +```json +{ + "code": 200, + "msg": "success", + "data": [ + {"channel":"email","pushStatus":"SUCCESS","statusText":"成功","pushedBy":"admin","pushedAt":"2026-06-25 15:15:47","failReason":null}, + {"channel":"sms","pushStatus":"SUCCESS","statusText":"成功","pushedBy":"admin","pushedAt":"2026-06-25 15:15:47","failReason":null} + ] +} +``` + +### 8.2 边界——多次推送累积 + +先推 [email,sms] 再推 [wechat],push-logs 返回 3 条(wechat / email / sms,按时间倒序),历史不覆盖。 + +### 8.3 业务失败——发票不存在 + +请求 +``` +GET /v3/admin/order/invoice/9999999999/push-logs +``` +响应 +```json +{"code": 581501, "msg": "发票不存在", "data": null} +``` + +--- + +## 9 业务边界 + +- push-logs 返回该发票全部推送明细,按推送时间倒序,无分页(单发票推送次数有限)。 +- 一次推送多渠道 → 每渠道一条;多次推送累积,不覆盖。 +- 发票从未推送过 → 返回空数组。 +- 本期 pushStatus 恒 SUCCESS(不真发通知,仅登记动作)。 + +--- + +## 10 修改前后对比 + +| 维度 | 变更前 | 变更后 | +|------|--------|--------| +| 推送记录 | 仅发票行覆盖记最后一次时间/渠道 | 独立明细,每渠道每次一条,累积历史 | +| 操作人 | 不记录 | pushedBy 记录操作人真实姓名 | +| 查询入口 | 无 | 新增 push-logs 接口 + 详情 pushLogs 数组 | + +--- + +## 11 影响评估 / 回滚 + +破坏兼容性:否(纯新增接口 + 详情新增可选数组字段) + +- 前端可在发票详情/推送弹窗展示推送历史(渠道/操作人/时间/状态)。 +- 发票详情原有字段不变,新增 pushLogs 数组,老前端忽略该字段不受影响。 + +回滚方案:回滚后端至本 PR 前版本,push-logs 接口下线、详情不再返回 pushLogs。`invoice_push_log` 表保留不影响其它功能。 + +--- + +## 12 注意事项 + +1. channel 是单值(一条记录一个渠道),一次多渠道推送对应多条记录。 +2. pushStatus 本期恒 SUCCESS,FAILED/PENDING 为预留状态(接真网关后启用)。 +3. 渠道文案前端用数据字典 `invoice_push_channel` 的 dictLabel 映射(email→邮件等)。 +4. push-logs 无分页,按推送时间倒序返回全部。 + +--- + +## 13 关联 / 联系人 + +- **Issue**:[#4395 发票推送明细日志表 invoice_push_log + 每渠道事件解耦](https://git.1814.love:8443/wx/HL/issues/4395) +- **PR**:[#4397](https://git.1814.love:8443/wx/HL/pulls/4397) +- **后端负责人**:腰苏图(yaosutu)