diff --git a/changelogs-v2/2026-07/13_4941_确认订单checklist删除actionPath-修改接口-管理后台.md b/changelogs-v2/2026-07/13_4941_确认订单checklist删除actionPath-修改接口-管理后台.md new file mode 100644 index 0000000..f589cc1 --- /dev/null +++ b/changelogs-v2/2026-07/13_4941_确认订单checklist删除actionPath-修改接口-管理后台.md @@ -0,0 +1,290 @@ +# 【修改接口 · 管理后台】确认订单 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 ` +- **使用场景**: 订单详情页点击确认订单按钮后先调用。 +- **核心语义**: + - `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 / null | 失败项明细;仅 `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 全部通过 + +**请求** + +```http +GET /v3/admin/order/2076236236812345346/confirm-checklist +Authorization: Bearer +``` + +**响应** + +```json +{ + "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 未通过 + +**请求** + +```http +GET /v3/admin/order/2072930000000000000/confirm-checklist +Authorization: Bearer +``` + +**响应** + +```json +{ + "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 直接提交确认但前置校验未通过 + +**请求** + +```http +POST /v3/admin/order/2072930000000000000/confirm-itinerary +Authorization: Bearer +Content-Type: application/json +``` + +```json +{} +``` + +**响应** + +```json +{ + "code": 581036, + "message": "确认订单前置校验未通过,请先补全所有必填项", + "data": null +} +``` + +## 9. 业务边界 + +1. 前端确认按钮流程仍是先调 `GET /confirm-checklist`,`allPassed=true` 后再调 `POST /confirm-itinerary`。 +2. `allPassed=false` 时前端不要读 `preview`,只处理 `items[]`。 +3. `items[].actionPath` 已删除,前端不要再读取该字段。 +4. 失败项跳转或高亮入口由前端按 `items[].code` 自行映射。 + +## 10. 修改前后对比 + +### 10.1 字段级对比 + +| 字段 | 修改前 | 修改后 | +|------|--------|--------| +| `items[].actionPath` | String / null,失败时可能返回后端拼接的跳转路径 | 删除,不再返回 | +| `items[].code` | String,检查项代码 | 保持不变,作为前端映射依据 | +| `items[].checkName` | String,检查项中文名称 | 保持不变 | +| `items[].passed` | Boolean,是否通过 | 保持不变 | +| `items[].failReason` | String / null,失败原因 | 保持不变 | + +### 10.2 示例对比 + +修改前: + +```json +{ + "code": "TRAVELER_COMPLETE", + "checkName": "出行人信息", + "passed": false, + "failReason": "未添加出行人", + "actionPath": "/admin/order/orders/2072930000000000000?tab=traveler" +} +``` + +修改后: + +```json +{ + "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. 注意事项 + +1. `items[].code` 是稳定映射字段,前端可按 `PAYMENT_OK / TRAVELER_COMPLETE / HOTEL_DONE / VEHICLE_DONE / CONTRACT_TEMPLATE_OK` 分别定位到对应补全区域。 +2. 不要用 `checkName` 做逻辑判断;`checkName` 是展示文案。 +3. `orderId` 建议继续按字符串处理。 + +## 13. 关联 / 联系人 + +- Issue #4941: https://git.1814.love:8443/wx/HL/issues/4941 +- PR #4942: https://git.1814.love:8443/wx/HL/pulls/4942 +- Merge commit: https://git.1814.love:8443/wx/HL/commit/10c120109d04bd21ab53a3af5baf03caa1116f42 +- 负责人: 腰苏图