wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

新增核单车辆异步下拉接口说明
所有检测均成功
changelog-filename-gate / validate (push) Successful in 2s
详情

浏览代码
这个提交包含在：
yaosutu 2026-07-30 17:21:03 +08:00
父节点 e1a5255ab3
当前提交 46b937135c
共有 1 个文件被更改，包括 252 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

252
changelogs-v2/2026-07/30_5360_核单车辆异步下拉-新增接口-管理后台.md 普通文件
查看文件

@ -0,0 +1,252 @@
---
schema: "hl-changelog/v2"
ticket: "5360"
title: "核单车辆异步下拉"
consumer: "admin"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "测试网关仅对核单车辆异步下拉 GET 做了只读定向验证：指定订单、keyword 为空、limit=1 返回 code=200 且 data 为 1 条七字段记录；未执行写入，也不构成 Full E2E。"
updated_at: "2026-07-30"
base: "dev-v3"
generated: "2026-07-30T17:18:34+08:00"
---
# ✨ 核单车辆异步下拉
## 1. 接口背景
核单页面需要按车牌、品牌型号、车型大类或常驻司机姓名异步检索车辆。新增轻量只读下拉接口，返回可直接作为车辆选项使用的七个字段。
## 变更接口（第 2 节：变更清单）
| # | 接口名 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 查询核单车辆异步下拉 | `GET` | `/v3/admin/order/:orderId/settlement/vehicle-options` | ✨ 新增接口 | `:orderId` 表示订单 ID；按关键词检索车辆，默认最多返回 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` 即可；不需要为车牌、车型或司机姓名拆分多次请求。
- 本接口为只读查询，成功响应不表示已选择、保存或核单确认车辆。
- 测试网关仅完成该 GET 的定向只读验证，未执行 Full E2E。
## 验证证据
- **验证模式**：`TARGETED_FALLBACK`，仅执行只读 GET，无写入。
- **测试请求**：`GET /v3/admin/order/2079454953641836546/settlement/vehicle-options?limit=1`。
- **测试结果**：响应 `code=200`，`data` 返回 1 条记录；记录字段严格为 `vehicleId`、`plate`、`modelName`、`typeName`、`primaryDriverId`、`primaryDriverName`、`label`。
- **验证边界**：本次只证明该下拉 GET 在测试网关可达并返回七字段契约，不代表核单 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
- **前端状态**：待认领