diff --git a/changelogs-v2/2026-07/23_5187_多车辆槽位原子批量派车与价格日历带价_前端待处理-新增接口-管理后台.md b/changelogs-v2/2026-07/23_5187_多车辆槽位原子批量派车与价格日历带价_前端待处理-新增接口-管理后台.md new file mode 100644 index 0000000..92d6e64 --- /dev/null +++ b/changelogs-v2/2026-07/23_5187_多车辆槽位原子批量派车与价格日历带价_前端待处理-新增接口-管理后台.md @@ -0,0 +1,250 @@ +--- +schema: "hl-changelog/v1" +ticket: "5187" +title: "多车辆槽位原子批量派车与价格日历带价" +consumer: "admin" +backend: "verified" +gateway: "pending" +frontend: "pending" +base: "dev-v3" +generated: "2026-07-23T15:38:00+08:00" +--- + +# 【新增接口·前端待处理·管理后台】多车辆槽位原子批量派车与价格日历带价 + +## 目标前端 + +- 端类型：管理后台（Web） +- 目标仓库：`mmg/hl-ui` +- 目标分支：`v2.1` +- 页面：车务管理 → 派车看板 → 派车派人弹窗、派单详情 +- 前端跟踪：[mmg/hl-ui#16](https://git.1814.love:8443/mmg/hl-ui/issues/16)、 + [mmg/hl-ui#17](https://git.1814.love:8443/mmg/hl-ui/issues/17) +- 小程序：无需处理 + +> **后端工单**: [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` 循环调用旧单派接口；那会在中途失败时留下半批状态。 +- 成功后一次关闭弹窗并刷新看板；不得每成功一辆刷新一次。 + +### 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、直接派定基线差异及事务/幂等注解均有测试覆盖。 + +> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`。测试环境网关实测完成后会补充 +> `gateway` 状态和请求证据。