hl-api-changelog/changelogs-v2/2026-07/15_4997_订单详情推送记录-新增接口-管理后台.md

订单详情推送记录 - 新增接口 - 管理后台

日期：2026-07-15 端类型：管理后台 服务：hl-order-service-v3 关联 Issue：#4997 关联 PR：#4998 关联提交：edd1d26da

1. 接口背景

订单详情页新增“推送记录”Tab，用于查看当前订单关联的短信、内部推送、企业微信、小程序订阅、公众号等通知发送记录。前端只调用订单服务的管理端接口，不直接调用用户中心内部通知日志接口。

2. 变更清单

类型	方法	路径	说明
新增接口	GET	/v3/admin/order/{id}/push-records	按订单 ID 聚合返回订单相关通知发送记录和渠道统计。

本次没有新增前端必传字段，也没有调整已有接口字段。

3. 接口详情

项	值
接口	GET /v3/admin/order/{id}/push-records
认证	管理后台 JWT
权限边界	房务角色不可查看订单详情推送记录
幂等性	只读接口，重复调用不改变订单或通知日志状态
请求体	无
查询参数	无
返回结构	Result<OrderPushRecordRespVO>

4. 入参

Path 参数

字段	类型	必填	说明
id	string	是	订单 ID，雪花 ID。前端按字符串透传，避免 JS 数字精度丢失。

Query 参数

无。

Body 参数

无。

5. 出参

Result 包装

字段	类型	说明
code	number	业务状态码，成功为 200。
message	string	业务提示。
data	object	推送记录聚合数据。
traceId	string | null	链路 ID，按网关实际返回。
success	boolean	是否成功。

data 字段

字段	类型	说明
total	number	聚合后记录总数。
records	array	推送记录列表，按 sentAt 倒序，同时间按 id 倒序。
summary	object	渠道和失败数量统计。

records[] 字段

字段	类型	说明
id	string	通知发送日志 ID，雪花 ID，前端按字符串处理。
eventCode	string | null	通知事件编码，例如 CONTRACT_SIGN_SMS。
channel	string | null	原始渠道编码，展示和筛选优先使用 channelGroup / kind。
channelName	string	渠道展示名。
channelGroup	string	归一化渠道分组，见枚举。
channelGroupName	string	渠道分组展示名。
kind	string	前端原型兼容分类，见枚举。
target	string | null	接收人展示文本，通常为“接收人类型 + 接收人姓名/账号”。
recipientName	string | null	接收人名称。
recipientType	string | null	接收人类型。
recipient	string | null	原始接收标识，例如手机号、openId、用户 ID 等。
content	string | null	通知内容摘要或渲染后的消息内容。
status	string	归一化状态，见枚举。
statusName	string	状态展示名。
rawStatus	number | null	通知日志原始状态码，见枚举。
failReason	string | null	失败原因，成功或未失败时为空。
bizId	string | null	关联业务 ID。可能是订单 ID，也可能是合同编号等关联业务号。
bizType	string | null	关联业务类型，例如 ORDER、CONTRACT、INSURANCE、HOUSE。
serviceName	string | null	记录来源服务。
sentAt	string | null	发送日志创建时间，格式 yyyy-MM-dd HH:mm:ss。

summary 字段

字段	类型	说明
all	number	全部记录数。
sms	number	短信记录数。
miniapp	number	小程序订阅记录数。
officialAccount	number	公众号记录数。
inapp	number	C 端站内信记录数。
internal	number	管理后台内部推送记录数。
wework	number	企业微信记录数。
other	number	其他渠道记录数。
failed	number	status = FAILED 的记录数。

6. 枚举 / 数据字典

channelGroup

值	展示名	说明
SMS	短信	原始渠道 SMS。
MINIAPP	小程序订阅	原始渠道 MINIAPP。
OFFICIAL_ACCOUNT	公众号	原始渠道 OA 或 OFFICIAL_ACCOUNT。
INAPP	站内信	原始渠道 INAPP。
INTERNAL	内部推送	原始渠道 ADMIN_INAPP。
WEWORK	企业微信	原始渠道 WEWORK 或 WECHAT_WORK。
OTHER	其他	不能归入上述渠道的记录。

kind

值	建议展示分类
sms	短信
miniapp	小程序
wechat	微信/公众号
inapp	站内信
system	内部推送
wework	企业微信
other	其他

status / rawStatus

rawStatus	status	statusName
0	DELIVERED	已送达
1	FAILED	失败
2	FILTERED	已过滤
3	SKIPPED	已跳过
null 或其他值	UNKNOWN	未知

bizType

值	说明
ORDER	订单相关通知。
CONTRACT	合同相关通知。
INSURANCE	保险相关通知。
HOUSE	房务相关通知。

7. 错误码

code	message	场景
200	成功	查询成功。没有记录时仍返回成功，total=0、records=[]。
581007	订单不存在	Path 中的订单 ID 不存在。
581045	房务角色无权查看订单详情，房务仅可配房	当前账号为房务角色。
平台通用鉴权错误码	按接口实际返回	未登录、Token 失效、无管理端权限等网关或安全框架错误。

8. 示例

8.1 典型成功响应

请求：

GET /v3/admin/order/2076936583562285058/push-records

响应：

{
  "code": 200,
  "message": "成功",
  "data": {
    "total": 1,
    "records": [
      {
        "id": "2076951776115793921",
        "eventCode": "CONTRACT_SIGN_SMS",
        "channel": "SMS",
        "channelName": "短信",
        "channelGroup": "SMS",
        "channelGroupName": "短信",
        "kind": "sms",
        "target": "其它 155****2307",
        "recipientName": "155****2307",
        "recipientType": "其它",
        "recipient": "155****2307",
        "content": "合同签署短信(创建首发)",
        "status": "DELIVERED",
        "statusName": "已送达",
        "rawStatus": 0,
        "failReason": null,
        "bizId": "MOCK-2076951776057044993",
        "bizType": "CONTRACT",
        "serviceName": "hl-order-service-v3",
        "sentAt": "2026-07-14 16:47:46"
      }
    ],
    "summary": {
      "all": 1,
      "sms": 1,
      "miniapp": 0,
      "officialAccount": 0,
      "inapp": 0,
      "internal": 0,
      "wework": 0,
      "other": 0,
      "failed": 0
    }
  },
  "traceId": null,
  "success": true
}

8.2 无推送记录响应

{
  "code": 200,
  "message": "成功",
  "data": {
    "total": 0,
    "records": [],
    "summary": {
      "all": 0,
      "sms": 0,
      "miniapp": 0,
      "officialAccount": 0,
      "inapp": 0,
      "internal": 0,
      "wework": 0,
      "other": 0,
      "failed": 0
    }
  },
  "traceId": null,
  "success": true
}

8.3 订单不存在

{
  "code": 581007,
  "message": "订单不存在",
  "data": null,
  "traceId": null,
  "success": false
}

9. 业务边界

1. 这是订单详情只读接口，不推进订单状态，不触发补发通知。
2. 当前聚合范围为订单相关通知：ORDER、CONTRACT、INSURANCE、HOUSE，并兼容合同编号作为 CONTRACT 的 bizId。
3. records 已由后端按通知日志 ID 去重，前端不需要再按 id 合并。
4. records 为空是正常业务结果，前端展示空态即可。
5. target、recipientName、recipient 可能包含手机号、openId 或内部用户标识，前端日志和埋点不要输出完整敏感信息。
6. bizId 不保证等于订单 ID，合同通知可能返回合同编号或合同相关业务号。
7. 原始渠道 channel 可能扩展，前端展示和筛选优先使用稳定字段 channelGroup、channelGroupName、kind。

10. 修改前后对比

项	修改前	修改后
订单详情推送记录	无统一管理端查询接口，前端不能直接调内部通知日志接口	新增 GET /v3/admin/order/{id}/push-records，由订单服务聚合返回。
渠道分类	无统一前端字段	返回 channelGroup、channelGroupName、kind。
统计	前端无数据来源	返回 summary，可直接用于 Tab 数量或筛选统计展示。

11. 影响评估 / 回滚

项	说明
兼容性	新增接口，不影响已有订单详情接口。
前端影响	订单详情“推送记录”Tab 可接入该接口；旧页面不接入则无影响。
后端影响	只读聚合用户中心通知日志，不写订单表和通知表。
回滚方式	回滚 hl-order-service-v3 对应 PR 后，该新增接口不可用；前端需要隐藏或降级推送记录 Tab。

12. 注意事项

1. 前端请求路径中的订单 ID 按字符串传递。
2. id、bizId 等雪花 ID 或业务号按字符串处理，不转 JS Number。
3. summary.failed 只统计 status=FAILED 的记录，FILTERED、SKIPPED、UNKNOWN 不算失败。
4. 不要依赖 channel 原始值做页面分组，后续原始渠道可能继续扩展。
5. 当前接口不支持分页、筛选和补发；如页面需要筛选，建议先基于返回的 records 做本地筛选。

13. 关联 / 联系人

项	链接
Issue	https://git.1814.love:8443/wx/HL/issues/4997
PR	https://git.1814.love:8443/wx/HL/pulls/4998
后端提交	https://git.1814.love:8443/wx/HL/commit/edd1d26da
负责人	腰苏图