hl-api-changelog/changelogs-v2/2026-07/30_5360_核单车辆异步下拉-新增接口-管理后台.md

schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base, generated

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

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

头部字段	当前值
PR / 服务	#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 典型成功

请求：

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

无请求体。

响应：

{
  "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 使用允许的最大返回条数；示例项没有常驻司机。

请求：

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

无请求体。

响应：

{
  "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 返回空数组：

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

8.3 业务失败

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

请求：

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

无请求体。

响应：

{
  "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
• PR: #5361
• Merge commit: 0ff4ef45ccd0f4ebb1d3be00b27cde06f26bce0b
• Feature commit: 5be7985164cdae5417cdeb2a2be7d104dc8fdae8

13.2 联系人

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