推 changelog：发票推送明细日志 #4395/#4397（管理后台，新增 GET push-logs 接口+发票详情出参加 pushLogs 数组，每渠道每次一条含操作人/时间/状态）

2026-06-25 15:18:09 +08:00 · 2026-06-25 15:18:09 +08:00 · 799981cbe8
--- a/changelogs-v2/2026-06/25_4395_发票推送明细日志-新增接口-管理后台.md
+++ 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<List<InvoicePushLogRespVO>>`）
+
+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 <token>
+```
+响应（一次推 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）