28a1d43254
一些检查失败了
changelog-filename-gate / validate (push) Failing after 2s
修改原因：管理后台已完成核单车辆异步下拉接入，需要同步可追溯的消费终态。 修改内容：将前端状态更新为 implemented，记录 v2.1 业务提交与验证边界。 实际验证：业务仓库 pnpm checkpoint 全量通过；source 仓库 46 项校验测试全部通过。 Changelog：changelogs-v2/2026-07/30_5360_核单车辆异步下拉-新增接口-管理后台.md
262 行
10 KiB
Markdown
262 行
10 KiB
Markdown
---
|
||
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`
|