新增核单操作日志查询接口变更说明

changelogs-v2/2026-07/18_5038_核单操作日志-新增接口-管理后台.md

@@ -0,0 +1,261 @@
+# 【新增接口·管理后台】核单操作日志查询 (#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
+- **前端对接**: 管理后台前端