wx/hl-api-changelog

派生 0

yaosutu 61f23b9190 新增确认订单checklist删除actionPath变更说明

2026-07-13 11:00:04 +08:00

8.6 KiB

原始文件 Blame 文件历史

【修改接口 · 管理后台】确认订单 checklist 删除 actionPath 出参（#4941）

PR: #4942 服务: hl-order-service-v3 更新时间: 2026-07-13 适用端: 管理后台订单详情页

1. 接口背景

管理后台订单详情页点击“确认订单”时，会先调用确认订单前置 checklist 接口判断是否允许展示确认弹窗。

此前失败项 items[] 中返回 actionPath，但该字段只是后端拼接的弱跳转提示，前端实际应按 items[].code 自行映射补全入口。为避免前端误依赖后端路由字符串，本次删除 items[].actionPath 出参字段。

2. 变更清单

#	接口	方法	路径	变更类型	说明
1	确认订单前置 checklist	GET	`/v3/admin/order/{orderId}/confirm-checklist`	修改接口	出参删除 `items[].actionPath`；失败项继续返回 `code/checkName/passed/failReason`

3. 接口详情

3.1 确认订单前置 checklist

路径: GET /v3/admin/order/{orderId}/confirm-checklist
认证: 管理后台登录态，Header 携带 Authorization: Bearer <token>
使用场景: 订单详情页点击确认订单按钮后先调用。
核心语义:
- allPassed=true: items=null，preview 有值，前端可展示确认弹窗。
- allPassed=false: items 有值，preview=null，前端展示失败项并按 items[].code 映射引导。

4. 入参

4.1 路径参数

字段	类型	必填	说明
`orderId`	String	是	订单 ID。雪花 ID 建议按字符串处理，避免前端数字精度丢失。

4.2 Query 参数

无。

4.3 请求体

无请求体。

5. 出参

5.1 通用响应包

字段	类型	说明
`code`	Number	业务状态码，`200` 表示成功。
`message`	String	业务提示，成功时通常为 `成功`。
`data`	Object	checklist 结果。

5.2 `data` 字段

字段	类型	说明
`allPassed`	Boolean	是否全部通过。
`items`	Array	失败项明细；仅 `allPassed=false` 时返回数组，全部通过时为 `null`。
`preview`	Object / null	确认弹窗预览数据；仅 `allPassed=true` 时返回对象，未通过时为 `null`。

5.3 `items[]` 字段

字段	类型	说明
`code`	String	检查项代码。前端应按该字段映射补全入口。
`checkName`	String	检查项中文名称。
`passed`	Boolean	当前检查项是否通过。
`failReason`	String / null	未通过原因；通过时为 `null`。

本次删除字段：items[].actionPath。响应中不再出现该字段。

5.4 `preview` 字段

字段	类型	说明
`departureDate`	String	出发日期，格式 `yyyy-MM-dd`。
`totalPeopleCount`	Number	总出行人数。
`driverName`	String / null	司机姓名。
`driverPhoneMasked`	String / null	司机手机号脱敏值。
`hotels`	Array	酒店摘要列表。
`staffs`	Array	本单配置人员列表。
`contractAutoAction`	Object / null	确认后合同自动处理预告。
`insuranceAutoAction`	Object / null	确认后保险自动处理预告。

6. 枚举 / 数据字典

6.1 `items[].code`

值	中文	说明
`PAYMENT_OK`	款项校验	订单需满足确认前支付要求。
`TRAVELER_COMPLETE`	出行人信息	出行人信息需完整。
`HOTEL_DONE`	房型安排	需要配房的订单必须已完成配房。
`VEHICLE_DONE`	用车安排	需要配车的订单必须已完成配车。
`CONTRACT_TEMPLATE_OK`	合同方案配置	产品需存在可用合同方案。

7. 错误码

code	含义	触发场景
`401`	未登录或登录态无效	未携带有效 `Authorization`。
`581007`	订单不存在	`orderId` 不存在或已删除。
`581016`	当前订单状态不允许该操作	订单不处于可确认状态。
`581036`	确认订单前置校验未通过	直接提交确认，但 checklist 未全部通过。

8. 示例

8.1 全部通过

请求

GET /v3/admin/order/2076236236812345346/confirm-checklist
Authorization: Bearer <token>

响应

{
  "code": 200,
  "message": "成功",
  "data": {
    "allPassed": true,
    "items": null,
    "preview": {
      "departureDate": "2026-07-19",
      "totalPeopleCount": 3,
      "driverName": "测试司机",
      "driverPhoneMasked": "1390000****",
      "hotels": [
        {
          "cityName": "拉萨",
          "hotelName": "测试酒店"
        }
      ],
      "staffs": [
        {
          "assignmentId": "2076236240000000001",
          "staffId": "2076236240000000002",
          "staffName": "张三",
          "staffPhone": "1380000****",
          "staffRole": "DRIVER",
          "staffRoleName": "司机",
          "isPrimaryReporter": true
        }
      ],
      "contractAutoAction": {
        "planName": "标准国内电子签约方案",
        "autoSign": true
      },
      "insuranceAutoAction": {
        "planName": "测试境内意外险方案",
        "peopleCount": 3,
        "effectiveDescription": "出发前 24h 内生效"
      }
    }
  }
}

8.2 未通过

请求

GET /v3/admin/order/2072930000000000000/confirm-checklist
Authorization: Bearer <token>

响应

{
  "code": 200,
  "message": "成功",
  "data": {
    "allPassed": false,
    "items": [
      {
        "code": "TRAVELER_COMPLETE",
        "checkName": "出行人信息",
        "passed": false,
        "failReason": "未添加出行人"
      },
      {
        "code": "HOTEL_DONE",
        "checkName": "房型安排",
        "passed": false,
        "failReason": "未提交用房需求"
      }
    ],
    "preview": null
  }
}

8.3 直接提交确认但前置校验未通过

请求

POST /v3/admin/order/2072930000000000000/confirm-itinerary
Authorization: Bearer <token>
Content-Type: application/json

{}

响应

{
  "code": 581036,
  "message": "确认订单前置校验未通过，请先补全所有必填项",
  "data": null
}

9. 业务边界

前端确认按钮流程仍是先调 GET /confirm-checklist，allPassed=true 后再调 POST /confirm-itinerary。
allPassed=false 时前端不要读 preview，只处理 items[]。
items[].actionPath 已删除，前端不要再读取该字段。
失败项跳转或高亮入口由前端按 items[].code 自行映射。

10. 修改前后对比

10.1 字段级对比

字段	修改前	修改后
`items[].actionPath`	String / null，失败时可能返回后端拼接的跳转路径	删除，不再返回
`items[].code`	String，检查项代码	保持不变，作为前端映射依据
`items[].checkName`	String，检查项中文名称	保持不变
`items[].passed`	Boolean，是否通过	保持不变
`items[].failReason`	String / null，失败原因	保持不变

10.2 示例对比

修改前：

{
  "code": "TRAVELER_COMPLETE",
  "checkName": "出行人信息",
  "passed": false,
  "failReason": "未添加出行人",
  "actionPath": "/admin/order/orders/2072930000000000000?tab=traveler"
}

修改后：

{
  "code": "TRAVELER_COMPLETE",
  "checkName": "出行人信息",
  "passed": false,
  "failReason": "未添加出行人"
}

11. 影响评估 / 回滚

维度	影响
是否破坏向后兼容	是。依赖 `items[].actionPath` 的前端代码需要调整。
前端是否必须同步上线	如果当前前端读取 `items[].actionPath` 做跳转，则必须改为按 `items[].code` 映射。仅展示 `checkName/failReason` 的页面不受影响。
影响接口范围	仅 `GET /v3/admin/order/{orderId}/confirm-checklist`。
回滚方式	回滚 PR #4942 可恢复字段。

12. 注意事项

items[].code 是稳定映射字段，前端可按 PAYMENT_OK / TRAVELER_COMPLETE / HOTEL_DONE / VEHICLE_DONE / CONTRACT_TEMPLATE_OK 分别定位到对应补全区域。
不要用 checkName 做逻辑判断；checkName 是展示文案。
orderId 建议继续按字符串处理。

13. 关联 / 联系人

Issue #4941: wx/HL#4941
PR #4942: wx/HL#4942
Merge commit: 10c120109d
负责人: 腰苏图

8.6 KiB 原始文件 Blame 文件历史 Unescape Escape