diff --git a/changelogs-v2/2026-07/30_5360_核单车辆异步下拉-新增接口-管理后台.md b/changelogs-v2/2026-07/30_5360_核单车辆异步下拉-新增接口-管理后台.md new file mode 100644 index 0000000..937a2fb --- /dev/null +++ b/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>`。 + +### 5.1 统一响应 + +| 字段 | 类型 | 可空 | 说明 | +|---|---|---|---| +| `code` | `Integer` | 否 | `200` 表示成功；其他值见错误码 | +| `message` | `String` | 否 | 响应消息，成功时为 `成功` | +| `data` | `Array` | 失败时可空 | 车辆下拉项数组；没有匹配项时为 `[]` | +| `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 +- **前端状态**：待认领