293 行
13 KiB
Markdown
293 行
13 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "5187"
|
||
title: "多车辆槽位原子批量派车与价格日历带价"
|
||
consumer: "admin"
|
||
change_type: "新增接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "implemented"
|
||
frontend_owner: "hl-ui-codex"
|
||
frontend_ref: "mmg/hl-ui@6479adf1caf2a5caeea08a24a42bacecbaaabd6a"
|
||
target_release: "hl-ui/v2.1"
|
||
verified_at: ""
|
||
status_note: "前端 v2.1 已实现按 fleetItemIndex 的多槽位选择、批量提交和重复车辆/司机禁选；测试环境 9527 已提供对应源码，尚待登录态页面实操验收。"
|
||
updated_at: "2026-07-24"
|
||
base: "dev-v3"
|
||
generated: "2026-07-23T15:38:00+08:00"
|
||
---
|
||
|
||
# 【新增接口·前端待处理·管理后台】多车辆槽位原子批量派车与价格日历带价
|
||
|
||
## 目标前端
|
||
|
||
- 端类型：管理后台（Web）
|
||
- 目标仓库：`mmg/hl-ui`
|
||
- 目标分支：`v2.1`
|
||
- 页面：车务管理 → 派车看板 → 派车派人弹窗、派单详情
|
||
- 前端交接：仅以本 `hl-api-changelog` 文档为准，不另建前端仓库工单。
|
||
- 小程序：无需处理
|
||
|
||
> **后端工单**: [wx/HL#5187](https://git.1814.love:8443/wx/HL/issues/5187)
|
||
>
|
||
> **后端 PR**: [wx/HL#5189](https://git.1814.love:8443/wx/HL/pulls/5189)
|
||
>
|
||
> **兼容性**: 既有单槽位 `POST /admin/fleet/assignments` 不变；多车订单必须改用本次批量接口，
|
||
> 前端不得循环调用单派接口。
|
||
|
||
## 一、业务口径
|
||
|
||
一条用车需求可能展开出多个车辆槽位。派车弹窗应按 `fleetItemIndex` 维护多组
|
||
“车辆 + 司机 + 协议价”，允许一次选择多辆车并一次提交。整批任一槽位失败时不得留下前面
|
||
已成功、后面失败的半批派单。
|
||
|
||
- 同一批内 `fleetItemIndex`、`vehicleId`、`driverId` 分别不可重复。
|
||
- 前端只允许选择当前需求实际展开出的待派槽位，不得自行增加超过需求数量的车辆。
|
||
- 雪花 ID 全程按字符串保存和提交。
|
||
- 同一次提交及其网络重试必须复用同一个 `requestId`；用户修改选择后主动再次提交应生成新值。
|
||
- `holdMode=1` 表示排车中等待司机确认，`holdMode=0` 表示直接派定；整批模式必须一致。
|
||
|
||
## 变更接口
|
||
|
||
```http
|
||
POST /admin/fleet/assignments/batch
|
||
Content-Type: application/json
|
||
```
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"orderId": "2046800000000000001",
|
||
"orderNo": "26-4165",
|
||
"requirementId": "2046800000000000101",
|
||
"startDate": "2026-07-28",
|
||
"endDate": "2026-07-30",
|
||
"pickupAt": "海拉尔",
|
||
"dropoffAt": "满洲里",
|
||
"headcount": 8,
|
||
"chargeableServiceDates": [
|
||
"2026-07-28",
|
||
"2026-07-29",
|
||
"2026-07-30"
|
||
],
|
||
"holdMode": 1,
|
||
"skipCityJunctionException": false,
|
||
"fromEntry": "from-board",
|
||
"requestId": "fleet-batch-7fe5c3a8",
|
||
"items": [
|
||
{
|
||
"fleetItemIndex": 0,
|
||
"vehicleId": "2046800000000000201",
|
||
"driverId": "2046800000000000301",
|
||
"protocolPrice": "520.00",
|
||
"confirmCrossResident": false
|
||
},
|
||
{
|
||
"fleetItemIndex": 1,
|
||
"vehicleId": "2046800000000000202",
|
||
"driverId": "2046800000000000302",
|
||
"protocolPrice": "860.00",
|
||
"confirmCrossResident": false
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 公共字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | ---: | --- |
|
||
| `orderId` | String(Long) | 是 | 订单 ID |
|
||
| `orderNo` | String | 否 | 订单号冗余 |
|
||
| `requirementId` | String(Long) | 是 | 当前生效用车需求 ID |
|
||
| `startDate` / `endDate` | LocalDate | 是 | 整批服务日期闭区间 |
|
||
| `pickupAt` / `dropoffAt` | String | 否 | 接送地 |
|
||
| `headcount` | Integer | 否 | 乘客人数 |
|
||
| `chargeableServiceDates` | LocalDate[] | 否 | 不传=全部计费；空数组=全部免费 |
|
||
| `vehicleFeeWaiverReason` | String | 条件必填 | 存在免费服务日时填写 |
|
||
| `confirmAllServiceDatesFree` | Boolean | 条件必填 | 全部免费时必须为 `true` |
|
||
| `holdMode` | Integer | 是 | `1=排车中`，`0=直接派定` |
|
||
| `skipCityJunctionException` | Boolean | 否 | 与单派接口同义 |
|
||
| `fromEntry` | String | 否 | 操作来源 |
|
||
| `requestId` | String | 是 | 批次幂等键，最大 64 字符 |
|
||
| `items` | Object[] | 是 | 1-20 个车辆槽位 |
|
||
|
||
### `items[]`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | ---: | --- |
|
||
| `fleetItemIndex` | Integer | 是 | 当前需求展开后的槽位序号，0 起 |
|
||
| `vehicleId` | String(Long) | 是 | 所选车辆 ID，批内不可重复 |
|
||
| `driverId` | String(Long) | 是 | 所选司机 ID，批内不可重复 |
|
||
| `protocolPrice` | String(BigDecimal) | 否 | 元/车天；不传时后端按车型价格日历兜底 |
|
||
| `messageTemplateId` | String(Long) | 否 | `holdMode=1` 的通知模板 |
|
||
| `customBody` | String | 否 | `holdMode=1` 的本次自定义通知正文 |
|
||
| `confirmCrossResident` | Boolean | 否 | 跨常驻车辆组合的显式确认 |
|
||
|
||
成功响应按 `fleetItemIndex` 升序返回：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"assignments": [
|
||
{
|
||
"fleetItemIndex": 0,
|
||
"assignment": {
|
||
"id": "2046800000000000401",
|
||
"assignmentGroupId": "2046800000000000501",
|
||
"assignmentSlotId": "2046800000000000601",
|
||
"assignmentStatus": "holding",
|
||
"stageCode": "holding_wait_driver",
|
||
"stageLabel": "排车中·等待司机确认",
|
||
"currentStep": 2,
|
||
"skippedStepCodes": [],
|
||
"protocolPrice": "520.00",
|
||
"holdSentAt": null,
|
||
"confirmedAt": null,
|
||
"sideEffects": null,
|
||
"dailyDifferences": null
|
||
}
|
||
}
|
||
],
|
||
"failedFleetItemIndex": null,
|
||
"dailyDifferences": null
|
||
},
|
||
"message": "成功",
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
直接派定发生订单/行程/需求冻结基线不一致时返回既有业务码 `605041`，并额外指出失败槽位：
|
||
|
||
```json
|
||
{
|
||
"code": 605041,
|
||
"data": {
|
||
"assignments": [],
|
||
"failedFleetItemIndex": 1,
|
||
"dailyDifferences": [
|
||
{
|
||
"serviceDate": "2026-07-29",
|
||
"differenceType": "CAPACITY_INSUFFICIENT",
|
||
"message": "逐日车辆可用座位不足"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
无论返回哪一种失败，整批均不产生部分成功数据。前端失败后保留用户当前选择并展示后端文案；
|
||
`605041` 可同时高亮 `failedFleetItemIndex` 对应槽位及逐日差异。
|
||
|
||
## 三、派车弹窗前端修改
|
||
|
||
### 3.1 多车辆选择
|
||
|
||
当前实现只有全局单值 `selVehicle/selDriver`，再次选择会覆盖上一辆车。需改成按
|
||
`fleetItemIndex` 保存的槽位数组或 Map：
|
||
|
||
```text
|
||
selectedSlots[fleetItemIndex] = {
|
||
vehicle,
|
||
driver,
|
||
protocolPrice,
|
||
confirmCrossResident
|
||
}
|
||
```
|
||
|
||
- 点击某个候选车辆只修改当前待选槽位，不清空其他已选槽位。
|
||
- 已选摘要、取消车辆、司机选择和常驻组合提示均必须作用于对应槽位。
|
||
- 提交前校验所有本次待派槽位都有车辆和司机，然后一次调用批量接口。
|
||
- 禁止用 `for` 循环调用旧单派接口；那会在中途失败时留下半批状态。
|
||
- 成功后一次关闭弹窗并刷新看板；不得每成功一辆刷新一次。
|
||
|
||
#### 当前消费差距
|
||
|
||
- `useVehicleDriverPicker.js` 仍只维护一组 `selVehicle/selDriver`。
|
||
- `AssignModalFooter.vue` 仍只展示一组车辆和司机，并按这一组决定按钮是否可用。
|
||
- `useAssignFlow.js` 仍只调用 `createAssignment`，没有构造 `items[]`。
|
||
- `src/api/fleet/board.js` 尚未封装 `POST /fleet/assignments/batch`。
|
||
|
||
#### 展示矩阵
|
||
|
||
| 场景 | “已选车辆”区域 | 候选/司机联动 | 主操作 |
|
||
| --- | --- | --- | --- |
|
||
| 尚未选择 | 显示 `已选车辆 0/N` 和 N 个待选槽位 | 提示先选择车辆 | 禁用，显示未完成组数 |
|
||
| 已选一辆 | 槽位 01 显示车牌、车型、司机和移除操作，并成为当前编辑槽位 | 已选车辆标记不可重复；司机只写入当前槽位 | 未完成全部槽位时保持禁用 |
|
||
| 继续多选 | 新车辆进入下一个待选 `fleetItemIndex`；其他已选槽位保持不变 | 已被其他槽位使用的车辆和司机不可重复选择 | 全部槽位完整后启用 |
|
||
| 切换槽位 | 高亮当前编辑槽位；允许单独更换车辆、司机和价格 | 候选与司机面板切换到该槽位上下文 | 完整度实时更新 |
|
||
| 搜索/筛选/翻页 | 已选区域固定可见，集合不丢失 | 只改变候选列表 | 状态保持 |
|
||
| HOLD 完整 | 显示 `已选择 N/N 辆，司机 N/N` | 每槽位独立司机 | `下一步 · 发送给 N 名司机` |
|
||
| DIRECT 完整 | 显示 `已选择 N/N 辆，司机 N/N` | 每槽位独立司机 | `直接派定 N 辆车` |
|
||
| 批量失败 | 保留全部选择；高亮 `failedFleetItemIndex` | 允许修正失败槽位 | 原批次不产生部分成功 |
|
||
| 批量成功 | 清空选择并关闭弹窗 | 看板只统一刷新一次 | 仅发送一次批量请求 |
|
||
|
||
“已选车辆”应作为车辆筛选与候选列表之间持续可见的紧凑区域，不得只在底栏显示最后一辆。
|
||
选择数量不得超过当前需求的待派车辆槽位数；移除某一槽位不得重排或清空其他槽位。
|
||
|
||
### 3.2 车型价格日历自动带价
|
||
|
||
候选接口 `vehicles[].protocolPrice` 已返回所选车辆车型在服务开始日的价格日历单价。当前页面
|
||
只从订单级 `props.order.protocolPrice` 初始化输入框，导致价格日历明明有值仍显示空。
|
||
|
||
- 选中车辆时，把该车辆的 `protocolPrice` 写入对应槽位价格框。
|
||
- 每辆车独立显示、独立可编辑，提交到 `items[].protocolPrice`。
|
||
- 切换车辆时改为新车辆的价格日历值；不能沿用上一辆车的价格。
|
||
- 候选值为空时输入框可留空，后端仍会在最终保存时按所选车辆车型 + `startDate` 再兜底一次。
|
||
- 不得把一个全局价格复制给所有不同车型。
|
||
|
||
### 3.3 联系定制师
|
||
|
||
派车看板卡片已有“联系定制师”，派单详情第 1 步和后续派车弹窗也应与房务详情保持一致：
|
||
|
||
- 在详情可见区域补“联系定制师”按钮，复用现有 `open-fleet` 会话流程。
|
||
- 订单 ID 使用数字雪花字符串，不能传 `HL...` 展示号或团号。
|
||
- 按钮位置、图标、禁用态、加载态和聊天抽屉交互复用房务模块，不另做一套样式。
|
||
- 首次打开真实会话和实时未读角标仍按
|
||
[#5180 前端交接](./23_5180_订单详情联系车务独立未读红点-修改接口-管理后台.md)处理。
|
||
|
||
## 四、派车看板默认状态筛选
|
||
|
||
这是前端初始化逻辑修复，不需要后端接口变更：
|
||
|
||
- `statusSel` 初始值必须为 `[]`，页面首次进入状态框显示空/不限。
|
||
- 首次列表请求不得携带 `statuses=unassigned`，默认展示全部状态。
|
||
- 点击“重置”后的值和首次进入完全一致。
|
||
- 用户主动选择“待派车”后才传对应状态；刷新筛选结果时不得偷偷恢复默认待派车。
|
||
|
||
## 五、前端验收清单
|
||
|
||
- [ ] 一条需求展开 2 个车辆槽位时，可同时选择 2 辆不同车辆和 2 名不同司机，第一辆不会被第二辆覆盖。
|
||
- [ ] 提交只发送 1 次 `/admin/fleet/assignments/batch`，不循环调用旧单派接口。
|
||
- [ ] 第二槽位失败时页面提示失败，刷新后两个槽位都没有半批残留。
|
||
- [ ] 价格日历有值时，选择每辆车后各自价格框立即带出对应 `protocolPrice`。
|
||
- [ ] 修改某辆车价格只影响该槽位，成功响应按槽位回显冻结价格。
|
||
- [ ] 派单详情第 1 步和派车流程均能直接“联系定制师”，交互与房务一致。
|
||
- [ ] 派车看板首次进入状态筛选为空，首次请求不传 `statuses`，默认可见全部状态。
|
||
- [ ] 主动筛选“待派车”及重置行为正确。
|
||
- [ ] 增加多槽位状态管理、批量请求映射、车型切换带价和默认空筛选的组件/组合式函数测试。
|
||
|
||
## 验证证据
|
||
|
||
- `mvn -pl hl-fleet-service spotless:check` 通过。
|
||
- `AssignmentControllerTest + AssignmentServiceTest`：281 项通过。
|
||
- `mvn -pl hl-fleet-service -am verify` 通过：fleet 2334 项，0 failure / 0 error，1 skipped。
|
||
- 批量成功、空明细校验、重复槽位校验、字符串雪花 ID、直接派定基线差异及事务/幂等注解均有测试覆盖。
|
||
- 测试环境部署任务 `28f9048a` 成功，`hl-fleet-service` 两个滚动实例均恢复健康。
|
||
- 经测试环境网关验证：
|
||
- 派车看板列表请求返回 HTTP 200 / 业务码 200。
|
||
- 批量接口空明细返回业务码 400，文案为“派单车辆槽位不能为空”。
|
||
- 批量接口重复 `fleetItemIndex` 返回业务码 100001，且未产生写入。
|
||
- 自建并标记测试订单，使用 SUV + MPV 两个槽位执行失败探针：第一槽位合法、第二槽位车辆不存在，
|
||
接口返回 605001；随后详情仍为 0 个有效派单，证明第一槽位及副作用意图随整批回滚。
|
||
- 同一测试订单使用两个合法槽位执行成功探针：接口返回 200，结果按
|
||
`fleetItemIndex=[0,1]` 排序，价格快照分别为 `700.00`、`860.00`，详情恰有 2 个
|
||
`assigned` 派单。
|
||
- 使用相同 `requestId` 重放返回业务码 100502；重放后详情仍恰有 2 个有效派单，无重复写入。
|
||
- 验收后已通过订单取消 API 精确清理自建测试订单，订单状态为 `CANCELLED`，详情有效派单恢复为 0。
|
||
- 部署后 fleet 服务与网关日志未发现 ERROR；重复槽位探针只产生预期的业务校验 WARN。
|
||
|
||
> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`。
|