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

2026-07-15 10:47:12 +08:00 · 2026-07-15 10:47:12 +08:00 · c7e99515de
--- a/changelogs-v2/2026-07/15_4997_订单详情推送记录-新增接口-管理后台.md
+++ b/changelogs-v2/2026-07/15_4997_订单详情推送记录-新增接口-管理后台.md
@ -0,0 +1,302 @@
+# 订单详情推送记录 - 新增接口 - 管理后台
+
+> 日期：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 典型成功响应
+
+请求：
+
+```http
+GET /v3/admin/order/2076936583562285058/push-records
+```
+
+响应：
+
+```json
+{
+  "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 无推送记录响应
+
+```json
+{
+  "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 订单不存在
+
+```json
+{
+  "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` |
+| 负责人 | 腰苏图 |