# 【修改接口 · 管理后台】确认订单 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
- 负责人: 腰苏图