wx/hl-api-changelog

派生 0

yaosutu c7e99515de 新增订单详情推送记录接口前端变更说明

2026-07-15 10:47:12 +08:00

9.9 KiB

原始文件 Blame 文件历史

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

日期：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. 业务边界

这是订单详情只读接口，不推进订单状态，不触发补发通知。
当前聚合范围为订单相关通知：ORDER、CONTRACT、INSURANCE、HOUSE，并兼容合同编号作为 CONTRACT 的 bizId。
records 已由后端按通知日志 ID 去重，前端不需要再按 id 合并。
records 为空是正常业务结果，前端展示空态即可。
target、recipientName、recipient 可能包含手机号、openId 或内部用户标识，前端日志和埋点不要输出完整敏感信息。
bizId 不保证等于订单 ID，合同通知可能返回合同编号或合同相关业务号。
原始渠道 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. 注意事项

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

9.9 KiB 原始文件 Blame 文件历史 Unescape Escape

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

1. 接口背景

2. 变更清单

3. 接口详情

4. 入参

Path 参数

Query 参数

Body 参数

5. 出参

Result 包装

data 字段

records[] 字段

summary 字段

6. 枚举 / 数据字典

channelGroup

kind

status / rawStatus

bizType

7. 错误码

8. 示例

8.1 典型成功响应

8.2 无推送记录响应

8.3 订单不存在

9. 业务边界

10. 修改前后对比

11. 影响评估 / 回滚

12. 注意事项

13. 关联 / 联系人

9.9 KiB

原始文件 Blame 文件历史

`data` 字段

`records[]` 字段

`summary` 字段

`channelGroup`

`kind`

`status` / `rawStatus`

`bizType`