diff --git a/changelogs-v2/2026-07/18_5038_核单操作日志-新增接口-管理后台.md b/changelogs-v2/2026-07/18_5038_核单操作日志-新增接口-管理后台.md new file mode 100644 index 0000000..4d147bc --- /dev/null +++ b/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>`。 + +### 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 +``` + +**响应** + +```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 +``` + +**响应** + +```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 +- **前端对接**: 管理后台前端