hl-api-changelog/changelogs-v2/2026-08/08_5708_车辆下拉新增车型牌价dayPrice-修改接口-管理后台.md

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

schema	ticket	title	consumer	change_type	author	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	5708	核单车辆下拉新增车型当日牌价 dayPrice（参考价，非最终核算价）	admin	修改接口	yaosutu(GIT)	deployed	verified	pending					PR #5713 已合并 dev-v3；GET /v3/admin/order/{orderId}/settlement/vehicle-options 出参 data[] 新增 dayPrice 字段（车型当日牌价，元/车天）。dayPrice 是参考价非最终核算价，最终核算价以派单后车辆快照 dailyPrice / 核单行 amount 为准。	2026-08-08	dev-v3

【修改接口·管理后台】核单车辆下拉新增车型当日牌价 dayPrice（#5708）

PR: #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

请求：

GET /v3/admin/order/2084000000000002978/settlement/vehicle-options?keyword=汉兰达&limit=10
Authorization: Bearer <token>

无请求体。

响应：

{
  "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。

请求：

GET /v3/admin/order/2084000000000002978/settlement/vehicle-options?keyword=别克&limit=10
Authorization: Bearer <token>

无请求体。

响应：

{
  "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

请求：

GET /v3/admin/order/0/settlement/vehicle-options?keyword=汉兰达
Authorization: Bearer <token>

无请求体。

响应：

{"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
• PR: #5713
• Merge commit: 10ba85d65
• 配套 fleet 侧 Issue: #5706

13.2 联系人

• 后端负责人: @yaosutu (yst)
• fleet 侧对接: @wx