wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs-v2/2026-06/25_4395_发票推送明细日志-新增接口-管理后台.md

6.7 KiB
原始文件 Blame 文件历史

发票推送明细日志（push-logs 接口 + 详情 pushLogs 数组）（管理后台）

  • 接口：GET /v3/admin/order/invoice/{id}/push-logs（新增） + GET /v3/admin/order/invoice/{id}（详情出参新增 pushLogs）
  • 变更类型：新增接口 + 修改接口（详情出参新增数组字段）
  • 端类型：管理后台
  • 日期：2026-06-25
  • Issue：#4395
  • PR：#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 条）

{
  "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

响应

{"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 关联 / 联系人