wx/hl-api-changelog

派生 0

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

2026-07-18 15:22:45 +08:00

8.5 KiB

原始文件 Blame 文件历史

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

PR: #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 典型成功

请求

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

响应

{
  "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 边界：暂无日志

请求

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

响应

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

8.3 异常：未登录

请求

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

响应

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

9. 业务边界

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

10. 修改前后对比

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

11. 影响评估 / 回滚

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

12. 注意事项

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

8.5 KiB

原始文件 Blame 文件历史

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

1. 接口背景

2. 变更清单

3. 接口详情

3.1 查询核单操作日志

4. 接口入参

4.1 路径参数

4.2 Query 参数

5. 出参

5.1 顶层响应字段

5.2 `data` 字段

5.3 `records[]` 字段

5.4 `changeItems[]` 字段

6. 枚举 / 数据字典

6.1 `operationType`

6.2 `operationObject`

6.3 `operatorType`

7. 错误码

8. 示例

8.1 典型成功

8.2 边界：暂无日志

8.3 异常：未登录

9. 业务边界

10. 修改前后对比

11. 影响评估 / 回滚

12. 注意事项

13. 关联 / 联系人

13.1 链接

13.2 联系人

8.5 KiB 原始文件 Blame 文件历史

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

1. 接口背景

2. 变更清单

3. 接口详情

3.1 查询核单操作日志

4. 接口入参

4.1 路径参数

4.2 Query 参数

5. 出参

5.1 顶层响应字段

5.2 data 字段

5.3 records[] 字段

5.4 changeItems[] 字段

6. 枚举 / 数据字典

6.1 operationType

6.2 operationObject

6.3 operatorType

7. 错误码

8. 示例

8.1 典型成功

8.2 边界：暂无日志

8.3 异常：未登录

9. 业务边界

10. 修改前后对比

11. 影响评估 / 回滚

12. 注意事项

13. 关联 / 联系人

13.1 链接

13.2 联系人

8.5 KiB

原始文件 Blame 文件历史

5.2 `data` 字段

5.3 `records[]` 字段

5.4 `changeItems[]` 字段

6.1 `operationType`

6.2 `operationObject`

6.3 `operatorType`