# 【新增接口·管理后台】核单操作日志查询 (#5038)

> **PR**: [#5042](https://git.1814.love:8443/wx/HL/pulls/5042) | **服务**: `hl-order-service-v3` | **更新时间**: 2026-07-18 15:30

## 1. 接口背景

核单页新增独立操作日志页签，用于查看当前订单在核单流程中的关键写入动作，包括住宿核单、门票/活动核单、人员费用、补助、返还记录、主报账对账、提交核单和财务确认。

## 2. 变更清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 查询核单操作日志 | GET | `/v3/admin/order/{orderId}/settlement/logs` | 新增接口 | 按订单分页返回核单专用操作日志 |

## 3. 接口详情

### 3.1 查询核单操作日志

- **使用场景**: 订单详情核单页签内展示核单操作历史。
- **认证**: 需要管理后台 JWT。
- **幂等性**: 是。GET 查询不产生写入。
- **排序**: 按 `operatedAt` 倒序；同一时间按 `id` 倒序。
- **请求体**: 无。

## 4. 接口入参

### 4.1 路径参数

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `orderId` | string | 是 | 订单 ID。后端按 64 位整数处理，前端按字符串保存和传递。 |

### 4.2 Query 参数

| 字段 | 类型 | 必填 | 默认值 | 校验规则 | 说明 |
|---|---|---|---|---|---|
| `page` | number | 否 | `1` | 最小 `1` | 当前页码。 |
| `pageSize` | number | 否 | `20` | `1` 到 `100` | 每页条数。 |

## 5. 出参

接口返回 `Result<PageResult<RecordVO>>`。

### 5.1 顶层响应字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `code` | number | 状态码，成功为 `200`。 |
| `message` | string | 响应消息，成功为 `成功`。 |
| `data` | object | 分页数据。 |
| `traceId` | string \| null | 链路追踪 ID。 |
| `success` | boolean | 是否成功。 |

### 5.2 `data` 字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `records` | array | 操作日志记录列表。无日志时为空数组。 |
| `total` | number | 总记录数。 |
| `page` | number | 当前页码。 |
| `pageSize` | number | 每页条数。 |

### 5.3 `records[]` 字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | string | 日志 ID。 |
| `orderId` | string | 订单 ID。 |
| `operationType` | string | 操作类型编码，见第 6 节。 |
| `operationTypeName` | string | 操作类型中文名。 |
| `operationObject` | string | 操作对象编码，见第 6 节。 |
| `operationObjectName` | string | 操作对象中文名。 |
| `content` | string | 操作内容。 |
| `operatorType` | string | 操作人类型，见第 6 节。 |
| `operatorId` | string \| null | 操作人 ID。系统自动操作时可为 `null`。 |
| `operatorName` | string | 操作人名称。 |
| `operatedAt` | string | 操作时间，格式示例 `2026-07-18 15:15:12`。 |
| `beforeSnapshot` | object \| array \| null | 改动前快照。结构随操作对象变化。 |
| `afterSnapshot` | object \| array \| null | 改动后快照。结构随操作对象变化。 |
| `changeItems` | array | 改动项列表。无差异时为空数组。 |

### 5.4 `changeItems[]` 字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `field` | string | 改动字段。非对象快照整体变化时为 `snapshot`。 |
| `fieldName` | string | 改动字段展示名。当前与 `field` 同值；整体变化时为 `整体快照`。 |
| `beforeValue` | any | 改动前值。 |
| `afterValue` | any | 改动后值。 |

## 6. 枚举 / 数据字典

### 6.1 `operationType`

| 值 | 中文 | 说明 |
|---|---|---|
| `SAVE_STEP1` | 保存住宿核单 | 保存 Step1 住宿核单明细时生成。 |
| `SAVE_STEP2` | 保存门票/活动核单 | 保存 Step2 门票/活动核单明细时生成。 |
| `SAVE_STEP3` | 保存人员费用 | 保存 Step3 人员费用核单时生成。 |
| `SAVE_STEP4` | 保存补助 | 保存 Step4 补助时生成。 |
| `ADD_REFUND` | 新增返还记录 | 新增 Step5 返还记录时生成；终止行程自动生成返还记录也使用该类型。 |
| `DELETE_REFUND` | 删除返还记录 | 删除 Step5 返还记录时生成。 |
| `SAVE_RECON` | 保存主报账对账 | 保存主报账对账信息时生成。 |
| `SUBMIT` | 提交核单 | Step6 提交核单时生成。 |
| `CONFIRM` | 财务确认 | 财务确认结算时生成。 |

### 6.2 `operationObject`

| 值 | 中文 | 说明 |
|---|---|---|
| `HOTEL` | 住宿核单 | 住宿核单相关操作对象。 |
| `TICKET` | 门票/活动核单 | 门票或活动核单相关操作对象。 |
| `STAFF_FEES` | 人员费用 | 司机、导游、摄影或其他人员费用。 |
| `SUBSIDY` | 补助 | 补助核单相关操作对象。 |
| `REFUND` | 返还记录 | 返还记录相关操作对象。 |
| `RECON` | 主报账对账 | 主报账对账相关操作对象。 |
| `SETTLEMENT` | 核单结算 | 提交核单或财务确认等整体结算操作对象。 |

### 6.3 `operatorType`

| 值 | 中文 | 说明 |
|---|---|---|
| `ADMIN` | 管理后台用户 | 管理后台人工操作。 |
| `SYSTEM` | 系统自动 | 定时任务或内部流程自动触发。 |
| `USER` | C 端用户 | 当前核单日志一般不使用，保留统一操作人类型。 |
| `MQ` | 消息回调 | 当前核单日志一般不使用，保留统一操作人类型。 |

## 7. 错误码

| code | 含义 | 触发场景 |
|---|---|---|
| `200` | 成功 | 查询成功，含无日志空列表。 |
| `400` | 参数校验失败 | `page < 1`、`pageSize < 1`、`pageSize > 100`，或 `orderId` 无法解析为整数。 |
| `401` | 未认证 | 未携带有效管理后台 JWT。 |

## 8. 示例

### 8.1 典型成功

**请求**

```http
GET /v3/admin/order/2077233855281971202/settlement/logs?page=1&pageSize=20
Authorization: Bearer <JWT>
```

**响应**

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "id": "2078378034477375490",
        "orderId": "2077233855281971202",
        "operationType": "SAVE_STEP4",
        "operationTypeName": "保存补助",
        "operationObject": "SUBSIDY",
        "operationObjectName": "补助",
        "content": "保存补助",
        "operatorType": "ADMIN",
        "operatorId": "1001",
        "operatorName": "admin",
        "operatedAt": "2026-07-18 15:15:12",
        "beforeSnapshot": [],
        "afterSnapshot": [],
        "changeItems": []
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  },
  "traceId": null,
  "success": true
}
```

### 8.2 边界：暂无日志

**请求**

```http
GET /v3/admin/order/2076236236812345346/settlement/logs?page=1&pageSize=20
Authorization: Bearer <JWT>
```

**响应**

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [],
    "total": 0,
    "page": 1,
    "pageSize": 20
  },
  "traceId": null,
  "success": true
}
```

### 8.3 异常：未登录

**请求**

```http
GET /v3/admin/order/2077233855281971202/settlement/logs?page=1&pageSize=20
```

**响应**

```json
{
  "code": 401,
  "message": "缺少有效 Authorization 头",
  "data": null,
  "traceId": null,
  "success": false
}
```

## 9. 业务边界

- 该接口只查询核单专用操作日志，不返回订单状态日志、支付流水、调整订单记录或房车操作日志。
- 无核单日志时返回空分页，不视为异常。
- `beforeSnapshot`、`afterSnapshot` 的内部字段随操作对象变化，前端应把它们作为 JSON 快照展示或按对象类型做兼容解析。
- `changeItems` 只表达快照层面的差异；数组类快照整体变化时可能只返回一条 `field=snapshot` 的整体改动项。
- 查询接口本身不会生成日志；日志由对应核单写入动作生成。

## 10. 修改前后对比

新增接口，无历史接口可对比。

## 11. 影响评估 / 回滚

- **是否破坏向后兼容**: 否，新增接口。
- **前端是否必须同步上线**: 否。不接入该接口时只是不展示核单操作日志页签。

## 12. 注意事项

- 前端展示长整型 ID 时按字符串处理，避免精度丢失。
- 前端不要根据 `operationTypeName` 或 `operationObjectName` 反推状态；需要判断类型时使用编码字段。
- 空列表是合法状态，适用于未开始核单或日志功能上线前的历史订单。

## 13. 关联 / 联系人

### 13.1 链接

- **Issue**: [#5038](https://git.1814.love:8443/wx/HL/issues/5038)
- **PR**: [#5042](https://git.1814.love:8443/wx/HL/pulls/5042)
- **Merge commit**: [176405d](https://git.1814.love:8443/wx/HL/commit/176405d489df22a184e848df88a64fe104a6672f)

### 13.2 联系人

- **后端负责人**: @yaosutu
- **前端对接**: 管理后台前端