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

> 日期：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` |
| 负责人 | 腰苏图 |