257 行
9.2 KiB
Markdown
257 行
9.2 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "5708"
|
||
title: "核单车辆下拉新增车型当日牌价 dayPrice（参考价，非最终核算价）"
|
||
consumer: "admin"
|
||
change_type: "修改接口"
|
||
author: "yaosutu(GIT)"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "implemented"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "a9ddbd48"
|
||
target_release: ""
|
||
verified_at: ""
|
||
status_note: "PR #5713 已合并 dev-v3；GET /v3/admin/order/{orderId}/settlement/vehicle-options 出参 data[] 新增 dayPrice 字段（车型当日牌价，元/车天）。dayPrice 是参考价非最终核算价，最终核算价以派单后车辆快照 dailyPrice / 核单行 amount 为准。"
|
||
updated_at: "2026-08-08"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 【修改接口·管理后台】核单车辆下拉新增车型当日牌价 dayPrice（#5708）
|
||
|
||
> **PR**: [#5713](https://git.1814.love:8443/wx/HL/pulls/5713) | **服务**: hl-order-service-v3 | **更新时间**: 2026-08-08
|
||
|
||
## 1. 接口背景
|
||
|
||
核单 Step3 车辆 Tab 的车辆下拉选项接口，此前只返回车牌 / 车型 / 司机等基础信息，核单人员看不到该车型当日的参考牌价，选车时无法预估金额。本次在出参 `data[]` 新增 `dayPrice` 字段，按订单出发日期取该车型当日定价，**仅供前端展示参考，不是最终核算价**。
|
||
|
||
## 2. 变更清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 前端动作 |
|
||
|---|---|---|---|---|---|
|
||
| 1 | 查询核单车辆异步下拉 | GET | `/v3/admin/order/{orderId}/settlement/vehicle-options` | 出参新增字段 | 读取 `data[].dayPrice`，建议标注"参考价" |
|
||
|
||
## 3. 接口详情
|
||
|
||
- **使用场景**：核单人员在订单核单 Step3 车辆 Tab 选择车辆时，通过关键字异步搜索候选车辆。
|
||
- **认证**：需要管理后台登录态（Bearer Token）。
|
||
- **幂等性**：是，只读查询。
|
||
- **限流**：未声明接口专属限流。
|
||
|
||
## 4. 接口入参
|
||
|
||
### 4.1 路径参数 / Query 参数
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `orderId` | Path | Long | 是 | 订单 ID |
|
||
| `keyword` | Query | String | 否 | 可匹配车牌、品牌型号、车型大类和常驻司机姓名 |
|
||
| `limit` | Query | Integer | 否 | 由 Fleet 按默认 10、最大 20 处理 |
|
||
|
||
### 4.2 请求体字段
|
||
|
||
GET 请求无请求体。
|
||
|
||
## 5. 出参字段
|
||
|
||
响应类型：`Result<List<SettlementVehicleOptionRespVO>>`。
|
||
|
||
### 5.1 统一响应外层
|
||
|
||
| 字段 | 类型 | 可空 | 说明 |
|
||
|---|---|---|---|
|
||
| `code` | Integer | 否 | 成功为 `200`；失败见 §7 |
|
||
| `message` | String | 否 | 结果说明 |
|
||
| `data` | Array | 失败时为空 | 成功时为车辆下拉选项数组 |
|
||
| `success` | Boolean | 否 | `code=200` 时为 `true` |
|
||
|
||
### 5.2 `data[]` 字段（共 8 个）
|
||
|
||
| 字段 | 类型 | 可空 | 说明 |
|
||
|---|---|---|---|
|
||
| `vehicleId` | String(Long) | 否 | 车辆 ID |
|
||
| `plate` | String | 否 | 车牌号 |
|
||
| `modelName` | String | 否 | 车型名称 |
|
||
| `typeName` | String | 否 | 车型大类 |
|
||
| `primaryDriverId` | String(Long) | 是 | 常驻司机 ID |
|
||
| `primaryDriverName` | String | 是 | 常驻司机姓名 |
|
||
| `label` | String | 否 | 下拉展示文案（车牌/车型/大类/司机拼接） |
|
||
| **`dayPrice`** | **Decimal** | **是** | **车型当日牌价（元/车天），本次新增**；语义见下 |
|
||
|
||
### 5.3 `dayPrice` 语义（**重点，前端必读**）
|
||
|
||
- **是参考价，不是最终核算价**：`dayPrice` 来自 fleet 车型定价日历（按订单出发日 `departDate` 取当日牌价，未定价日回退车型 `basePrice`）。
|
||
- **最终核算价以派单后车辆快照 `dailyPrice` / 核单行 `amount` 为准**。前端展示 `dayPrice` 时应标注"参考价"，避免误导核单人员把它当成结算价。
|
||
- **fleet 未上线该字段前 `dayPrice` 为 `null`**（向前兼容）；fleet 侧现已上线（配套 Issue #5706），正常出值。
|
||
|
||
## 6. 枚举 / 数据字典
|
||
|
||
本次不涉及枚举新增或改值。
|
||
|
||
## 7. 错误码
|
||
|
||
| code | 含义 | 触发场景 |
|
||
|---:|---|---|
|
||
| `400` | 请求参数错误 | `orderId` 非法（如 0、负数、非数字） |
|
||
| `581007` | 订单不存在 | `orderId` 对应订单不存在 |
|
||
| `584071` | 无权访问该订单 | 当前账号不在订单可访问范围内 |
|
||
|
||
## 8. 示例
|
||
|
||
### 8.1 典型成功 —— 返回含 dayPrice
|
||
|
||
**请求**：
|
||
|
||
```http
|
||
GET /v3/admin/order/2084000000000002978/settlement/vehicle-options?keyword=汉兰达&limit=10
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
无请求体。
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": [
|
||
{
|
||
"vehicleId": "301",
|
||
"plate": "蒙A88888",
|
||
"modelName": "丰田汉兰达",
|
||
"typeName": "SUV",
|
||
"primaryDriverId": "45",
|
||
"primaryDriverName": "张师傅",
|
||
"label": "蒙A88888 丰田汉兰达 SUV 张师傅",
|
||
"dayPrice": "1000.00"
|
||
},
|
||
{
|
||
"vehicleId": "302",
|
||
"plate": "蒙A66666",
|
||
"modelName": "丰田汉兰达",
|
||
"typeName": "SUV",
|
||
"primaryDriverId": "46",
|
||
"primaryDriverName": "李师傅",
|
||
"label": "蒙A66666 丰田汉兰达 SUV 李师傅",
|
||
"dayPrice": "1000.00"
|
||
}
|
||
],
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
### 8.2 边界情况 —— 车型当日未定价时 dayPrice 回退 basePrice 或为 null
|
||
|
||
**场景说明**：某车型在订单出发日未配置定价日历时，后端回退取车型 `basePrice`；若 fleet 侧未上线该字段则返回 `null`。
|
||
|
||
**请求**：
|
||
|
||
```http
|
||
GET /v3/admin/order/2084000000000002978/settlement/vehicle-options?keyword=别克&limit=10
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
无请求体。
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": [
|
||
{
|
||
"vehicleId": "305",
|
||
"plate": "蒙A11111",
|
||
"modelName": "别克GL8",
|
||
"typeName": "MPV",
|
||
"primaryDriverId": "47",
|
||
"primaryDriverName": "王师傅",
|
||
"label": "蒙A11111 别克GL8 MPV 王师傅",
|
||
"dayPrice": null
|
||
}
|
||
],
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
前端拿到 `dayPrice: null` 时应展示为 "—" 或不显示该行参考价，**不要展示为 `0`**。
|
||
|
||
### 8.3 业务失败 —— orderId 非法返 400
|
||
|
||
**请求**：
|
||
|
||
```http
|
||
GET /v3/admin/order/0/settlement/vehicle-options?keyword=汉兰达
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
无请求体。
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{"code": 400, "message": "请求参数错误", "data": null, "success": false}
|
||
```
|
||
|
||
## 9. 业务边界
|
||
|
||
- **适用场景**：核单车辆下拉展示参考牌价，辅助核单人员选车预估金额。
|
||
- **不适用场景**：**不要把 `dayPrice` 当作最终核算价**展示在结算明细里；最终价以派单后快照 `dailyPrice` / 核单行 `amount` 为准。
|
||
- **特殊边界**：`dayPrice` 为 `null` 时表示 fleet 侧暂无该车型当日定价数据，不等于"免费"；展示时应与 `0.00` 区分。
|
||
|
||
## 10. 修改前后对比
|
||
|
||
### 10.1 字段级对比
|
||
|
||
| 字段 | 原来 | 现在 |
|
||
|---|---|---|
|
||
| `data[].dayPrice` | 不存在 | **新增**；Decimal，可空 |
|
||
|
||
其余 7 个字段（`vehicleId`/`plate`/`modelName`/`typeName`/`primaryDriverId`/`primaryDriverName`/`label`）无变化。
|
||
|
||
### 10.2 行为级对比
|
||
|
||
| 行为 | 原来 | 现在 |
|
||
|---|---|---|
|
||
| 车辆下拉展示 | 只有车牌/车型/司机 | 新增当日参考牌价 |
|
||
|
||
## 11. 影响评估 / 回滚
|
||
|
||
### 11.1 影响评估
|
||
|
||
- **是否破坏向后兼容**：否。仅出参新增字段，旧前端不读 `dayPrice` 即可继续工作。
|
||
- **前端是否必须同步上线**：否。字段为增强信息，前端可择机上线展示。
|
||
|
||
### 11.2 回滚方案
|
||
|
||
- 回滚即出参不再返回 `dayPrice`；已上线的新前端应把 `dayPrice` 作为可选字段处理（读到就展示、读不到就不展示），天然兼容回滚。
|
||
|
||
## 12. 注意事项
|
||
|
||
- **`dayPrice` 是参考价**，前端展示建议加"参考价"标注，避免与最终核算价混淆。
|
||
- fleet 侧配套改动见 Issue #5706；fleet 未上线前 `dayPrice` 恒为 `null`，前端需做 null 兜底展示。
|
||
- `dayPrice` 单位为元/车天（整段行程 1 天的价格），不是整段总价。
|
||
|
||
## 13. 关联 / 联系人
|
||
|
||
### 13.1 链接
|
||
|
||
- **Issue**: [#5708](https://git.1814.love:8443/wx/HL/issues/5708)
|
||
- **PR**: [#5713](https://git.1814.love:8443/wx/HL/pulls/5713)
|
||
- **Merge commit**: [10ba85d65](https://git.1814.love:8443/wx/HL/commit/10ba85d65eca08fa5b1f9da60a4e8c9cfd318938)
|
||
- **配套 fleet 侧 Issue**: [#5706](https://git.1814.love:8443/wx/HL/issues/5706)
|
||
|
||
### 13.2 联系人
|
||
|
||
- **后端负责人**: @yaosutu (yst)
|
||
- **fleet 侧对接**: @wx
|
||
|
||
## 前端实证确认（2026-08-08 mmg，hl-admin@a9ddbd48）
|
||
|
||
- 前端已接该下拉接口：`use-settlement-vehicle-options.js` 此前 `OPTION_FIELDS` 只投影 7 个契约字段（不含 dayPrice）。
|
||
- 修复：OPTION_FIELDS 与候选 option 增加 `dayPrice`（null 归一为 null）；CategoryTable `renderVehicleSelect` 新增 `renderLabel(option, selected)`——**下拉项**追加「参考价 ¥x/车天」角标（teleport 弹层用内联样式，scoped 选不中），**选中态**只显示车牌文案不带参考价；`dayPrice` 为 null 时显「—」，不当作 0 也不当最终核算价。
|
||
- 保存契约安全：`select()` 写回 source 的字段显式列出（vehicleId/vehicleModelId/vehicleModelName/driverId/driverName），dayPrice 不进 source、不进 step3/vehicles 保存 payload。
|
||
- 验证：settlement 全量定向 vitest 93/93 通过（含候选 option 携带 dayPrice 断言）；checkpoint 全绿。
|