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

2026-07-13 11:00:04 +08:00 · 2026-07-13 11:00:04 +08:00 · 61f23b9190
--- a/changelogs-v2/2026-07/13_4941_确认订单checklist删除actionPath-修改接口-管理后台.md
+++ 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 <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<Object> / 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<Object> | 酒店摘要列表。 |
+| `staffs` | Array<Object> | 本单配置人员列表。 |
+| `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 <token>
+```
+
+**响应**
+
+```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 <token>
+```
+
+**响应**
+
+```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 <token>
+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
+- 负责人: 腰苏图