---
schema: "hl-changelog/v2"
ticket: "5360"
title: "核单车辆异步下拉"
consumer: "admin"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "partial"
frontend_status: "implemented"
frontend_owner: "Pi"
frontend_ref: "v2.1@0927f28de6c091d1eb1c867f5c96088358057043"
target_release: ""
verified_at: "2026-07-30"
status_note: "管理后台已在核单车辆手工行接入异步车辆下拉，按关键词远程检索并回填车辆、车型与常驻司机字符串 ID；pnpm checkpoint 全量通过，业务提交 0927f28de6c091d1eb1c867f5c96088358057043 已推送至 origin/v2.1。测试服真实订单正向响应与角色权限仍受有效登录态缺失限制。"
updated_at: "2026-07-31"
base: "dev-v3"
generated: "2026-07-30T17:18:34+08:00"
---

# ✨【新增接口·管理后台】核单车辆异步下拉 (#5360)

| 头部字段 | 当前值 |
|---|---|
| PR / 服务 | [#5361](https://git.1814.love:8443/wx/HL/pulls/5361) / `hl-order-service-v3` |
| 后端状态 | `deployed`：已合入 `dev-v3` 并部署测试服 |
| 网关状态 | `partial`：路由和鉴权响应已验证，正向业务响应待有效登录态复验 |
| 前端回写标志 | 已实现 |
| 前端认领信息 | `frontend_owner: Pi`；`frontend_ref: v2.1@0927f28de6c091d1eb1c867f5c96088358057043` |
| 更新时间 | `2026-07-30` |

## 1. 接口背景

核单页面需要按车牌、品牌型号、车型大类或常驻司机姓名异步检索车辆。新增轻量只读下拉接口，返回可直接作为车辆选项使用的七个字段。

## 2. 变更清单

| # | 接口名 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 查询核单车辆异步下拉 | `GET` | `/v3/admin/order/{orderId}/settlement/vehicle-options` | ✨ 新增接口 | 按关键词检索车辆，默认最多返回 10 条，最多返回 20 条 |

## 3. 接口详情

### 3.1 查询核单车辆异步下拉

- **接口说明**：`keyword` 可匹配车牌、品牌型号、车型大类和常驻司机姓名；`limit` 默认 10、最大 20。
- **使用场景**：核单页面加载车辆选择器或按关键词刷新候选项。
- **认证**：需要管理后台登录态。房务管理员和房务组长不可调用；管理员、超级管理员可查看任意订单，其他后台角色仅可查看本人作为定制师的订单。
- **幂等性**：幂等，只读查询，无请求体、无幂等键。
- **限流**：本接口未声明独立限流规则。

## 4. 接口入参

### 4.1 路径参数 / Query 参数

| 字段 | 位置 | 类型 | 必填 | 默认值 | 说明与校验规则 |
|---|---|---|---|---|---|
| `orderId` | path | `String` | 是 | — | 订单 ID，必须是大于 0 的整数；按字符串传递，避免 JavaScript 数字精度损失 |
| `keyword` | query | `String` | 否 | 空 | 模糊匹配车牌、品牌型号、车型大类或常驻司机姓名；不传或仅空白字符表示不过滤 |
| `limit` | query | `Integer` | 否 | `10` | 期望返回条数；不传或非正数按 10 处理，超过 20 按 20 处理 |

### 4.2 请求体字段

无请求体。

## 5. 出参字段

响应类型：`Result<List<SettlementVehicleOptionRespVO>>`。

### 5.1 统一响应

| 字段 | 类型 | 可空 | 说明 |
|---|---|---|---|
| `code` | `Integer` | 否 | `200` 表示成功；其他值见错误码 |
| `message` | `String` | 否 | 响应消息，成功时为 `成功` |
| `data` | `Array<VehicleOption>` | 失败时可空 | 车辆下拉项数组；没有匹配项时为 `[]` |
| `traceId` | `String` | 是 | 链路追踪 ID，未注入时可为 `null` 或不返回 |
| `success` | `Boolean` | 否 | `code === 200` 时为 `true` |

### 5.2 `data[]` 车辆下拉项

| 字段 | 类型 | 可空 | 说明 |
|---|---|---|---|
| `vehicleId` | `String` | 否 | 车辆 ID；JSON 固定按字符串返回 |
| `plate` | `String` | 是 | 车牌 |
| `modelName` | `String` | 是 | 品牌型号 |
| `typeName` | `String` | 是 | 车型大类名称 |
| `primaryDriverId` | `String` | 是 | 常驻司机 ID；无常驻司机时为 `null`；有值时按字符串返回 |
| `primaryDriverName` | `String` | 是 | 常驻司机姓名；无常驻司机时为 `null` |
| `label` | `String` | 否 | 下拉展示文案，依次包含车牌、品牌型号、车型大类和常驻司机姓名；无常驻司机时最后一段为 `无常驻司机` |

`data[]` 严格只有以上七个字段，不包含车辆费用、支付方式或其他未声明字段。

## 6. 枚举 / 数据字典

本接口的入参和出参不包含枚举或数据字典字段。

## 7. 错误码

| code | 含义 | 触发场景 |
|---|---|---|
| `400` | `订单 ID 必须大于 0` | `orderId <= 0`，参数校验失败 |
| `581007` | `订单不存在` | `orderId` 对应订单不存在 |
| `581008` | `无权查看此订单` | 非管理员后台角色访问其他定制师的订单，或请求上下文缺少可用于判断订单归属的管理员 ID |
| `581045` | `房务角色无权查看订单详情，房务仅可配房` | 房务管理员或房务组长调用本接口 |
| `584072` | `车务司机车辆信息暂时不可用，请稍后重试` | 车辆候选信息暂时不可用 |

管理后台登录态无效或缺失时，请求会在进入本接口前被统一认证拦截。

## 8. 示例

### 8.1 典型成功

**请求**：

```http
GET /v3/admin/order/2079454953641836546/settlement/vehicle-options?keyword=%E5%BC%A0%E5%B8%88%E5%82%85&limit=10
Authorization: Bearer <管理后台访问令牌>
```

无请求体。

**响应**：

```json
{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "vehicleId": "9202101",
      "plate": "蒙A-88888",
      "modelName": "丰田汉兰达",
      "typeName": "SUV",
      "primaryDriverId": "9204101",
      "primaryDriverName": "张师傅",
      "label": "蒙A-88888***丰田汉兰达***SUV***张师傅"
    }
  ],
  "traceId": "a1b2c3d4-e5f6-7890",
  "success": true
}
```

### 8.2 边界情况

**场景说明**：不传关键词；`limit=20` 使用允许的最大返回条数；示例项没有常驻司机。

**请求**：

```http
GET /v3/admin/order/2079454953641836546/settlement/vehicle-options?limit=20
Authorization: Bearer <管理后台访问令牌>
```

无请求体。

**响应**：

```json
{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "vehicleId": "9202102",
      "plate": "蒙A-66666",
      "modelName": "别克GL8",
      "typeName": "商务车",
      "primaryDriverId": null,
      "primaryDriverName": null,
      "label": "蒙A-66666***别克GL8***商务车***无常驻司机"
    }
  ],
  "traceId": "b2c3d4e5-f6a7-8901",
  "success": true
}
```

没有匹配项时，`data` 返回空数组：

```json
{
  "code": 200,
  "message": "成功",
  "data": [],
  "traceId": "b2c3d4e5-f6a7-8901",
  "success": true
}
```

### 8.3 业务失败

**场景说明**：`orderId=0`，不满足大于 0 的校验规则。

**请求**：

```http
GET /v3/admin/order/0/settlement/vehicle-options
Authorization: Bearer <管理后台访问令牌>
```

无请求体。

**响应**：

```json
{
  "code": 400,
  "message": "订单 ID 必须大于 0",
  "data": null,
  "traceId": "c3d4e5f6-a7b8-9012",
  "success": false
}
```

## 9. 业务边界

- **适用场景**：管理后台核单页面只读查询车辆候选；可按车牌、品牌型号、车型大类或常驻司机姓名搜索。
- **访问范围**：管理员、超级管理员可访问全部订单；其他允许查看订单详情的后台角色仅可访问本人作为定制师的订单。
- **不适用角色**：房务管理员、房务组长不可查看本接口数据。
- **返回范围**：查询结果最多 20 条；无匹配项返回 `[]`；接口不返回车辆费用、支付方式等核单数据。
- **特殊边界**：`keyword` 为空或空白时不过滤；`limit <= 0` 按 10 处理；`limit > 20` 按 20 处理。

## 10. 修改前后对比

本次为新增接口，不修改任何既有接口的字段、类型、必填性、枚举或错误码，因此无字段级、行为级替换关系。

## 11. 影响评估 / 回滚

- **是否破坏向后兼容**：否。新增独立 GET 路径，不影响既有调用方。
- **前端是否必须同步上线**：否。未接入本接口的旧版管理后台可继续运行；需要核单车辆异步搜索能力时再接入。
- **回滚影响**：若新接口不可用，前端应停用本下拉数据源，不应改用未在本文声明的字段或接口代替。

## 12. 注意事项

- `vehicleId` 和非空的 `primaryDriverId` 必须始终按字符串保存、比较和提交，不能转为 JavaScript `Number`。
- 前端只依赖 `data[]` 中声明的七个字段；`primaryDriverId`、`primaryDriverName` 允许为 `null`。
- 搜索时传用户输入的 `keyword` 即可；不需要为车牌、车型或司机姓名拆分多次请求。
- 本接口为只读查询，成功响应不表示已选择、保存或核单确认车辆。
- 测试服已确认新路径进入统一鉴权链路；因现有测试登录态失效，真实订单正向响应、关键词过滤、`limit` 边界与角色权限仍待使用有效管理后台登录态复验。

### 12.1 验证状态

- **验证模式**：`TARGETED_FALLBACK`，仅执行只读 GET，无写入。
- **已验证**：测试服双实例 OpenAPI 已加载本接口；真实网关请求已进入统一鉴权链路并返回标准五字段错误体。
- **待复验**：现有测试登录态已失效，真实订单 `code=200` 响应、七字段运行时值、关键词过滤、`limit` 边界和角色权限尚未形成正向实证。
- **验证边界**：上述状态不代表核单 Full E2E 已完成。

## 13. 关联 / 联系人

### 13.1 链接

- **Issue**: [#5360](https://git.1814.love:8443/wx/HL/issues/5360)
- **PR**: [#5361](https://git.1814.love:8443/wx/HL/pulls/5361)
- **Merge commit**: [0ff4ef45ccd0f4ebb1d3be00b27cde06f26bce0b](https://git.1814.love:8443/wx/HL/commit/0ff4ef45ccd0f4ebb1d3be00b27cde06f26bce0b)
- **Feature commit**: [5be7985164cdae5417cdeb2a2be7d104dc8fdae8](https://git.1814.love:8443/wx/HL/commit/5be7985164cdae5417cdeb2a2be7d104dc8fdae8)

### 13.2 联系人

- **后端负责人**：yaosutu
- **前端状态**：已实现并推送 `0927f28de6c091d1eb1c867f5c96088358057043`