9.2 KiB
9.2 KiB
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 | verified | pending | 测试网关仅对核单车辆异步下拉 GET 做了只读定向验证：指定订单、keyword 为空、limit=1 返回 code=200 且 data 为 1 条七字段记录；未执行写入，也不构成 Full E2E。 | 2026-07-30 | dev-v3 | 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 典型成功
请求：
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必须始终按字符串保存、比较和提交，不能转为 JavaScriptNumber。- 前端只依赖
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
- PR: #5361
- Merge commit: 0ff4ef45ccd0f4ebb1d3be00b27cde06f26bce0b
- Feature commit: 5be7985164cdae5417cdeb2a2be7d104dc8fdae8
13.2 联系人
- 后端负责人：yaosutu
- 前端状态：待认领