---
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`。
