# 发票推送明细日志（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）