---
schema: "hl-changelog/v2"
ticket: "6057"
title: "多槽位越需求索引派车业务码 605911/605912 替代 500（required_vehicle_type 落 NULL 防御）"
consumer: "admin"
author: "wx"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: "mmg"
frontend_ref: ""
target_release: ""
verified_at: "2026-08-19"
status_note: "后端完成：PR #6064 + #6065 已合并 dev-v3（584f3adc3 / b07855c228）并部署 TEST（hl-fleet-service Deploy task d6cb4687 + 3bed5be8，jar 01:27:55、双实例 01:28 重启）。越界索引由 500（vehicleType is required）收敛为 605911 业务码；快照车型兜底缺失拦成 605912。错误消息自解释，前端全局错误处理可直接展示，无需适配；派车看板正常只发送已声明/已增槽槽位，行为不变。"
updated_at: "2026-08-19"
base: "dev-v3"
generated: "2026-08-19T01:32:00+08:00"
---

# 多槽位越需求索引派车业务码 605911/605912 替代 500（#6057）

## 背景

批量派车（车务最终实派方案）`fleetDecisionFinal` 放行的 `fleetItemIndex` 可能越出当前需求 `fleet[]` 声明的车辆总数（如需求声明 1 辆车却按 index=1 派第 2 辆）。该场景此前 `resolveFleetItemByIndex` 返 null、无占位可消费走拉单组装，`required_vehicle_type` 落 NULL（DAILY_V3 快照契约 required 字段），确认派车阶段快照校验炸 `vehicleType is required` **500**（P1 复现单 R2）。

## 变更接口

| 接口 | 变更 |
| --- | --- |
| `POST /admin/fleet/assignments/batch` 的 `items[]` | **行为变更**。`fleetItemIndex` 越出当前需求声明车辆数且该索引无 addSlot/展开占位可消费时，整批 fail-fast 返回 **605911**，零写入；有占位（经 `POST /admin/fleet/assignments/slots` 增槽或展开生成）的越界索引不受影响，正常消费占位车型快照派车 |
| `POST /admin/fleet/assignments/batch`（防御） | 需求项定位不到且所选车辆型号归一不出规范车型时，落库前拦 **605912**，不再留 NULL 车型脏行到确认派车阶段炸 500 |

## 新增错误码（fleet 605xxx 段）

| 错误码 | 消息 | 触发条件 | 前端处置 |
| --- | --- | --- | --- |
| `605911` | 用车条目索引越界：超出当前需求声明的车辆数 | `fleetItemIndex` ≥ 需求 `fleet[]` 全部 count 之和且该索引无占位 | 引导车务调整需求条目数或先经增槽（addSlot）再派；消息自解释可直接 toast |
| `605912` | 派车快照缺少需求车型，请检查用车需求车型明细 | 需求项定位不到且车辆型号无法归一（罕见，防御性） | 检查用车需求车型明细 |

## 行为口径

- **合法索引不变**：`index < 声明车辆数`（含 count-1 边界）与占位消费（增槽/展开）路径 200 正常，落库 `required_vehicle_type` 非空。
- **整批原子**：越界索引在锁内拉单组装前 fail-fast，任一项失败整批回滚、零写入。
- **对照一致**：需求声明条目数调整到位后同一请求 200（复现单 R2 实测验证）。
- 接口说明（swagger notes）已同步新口径：多派/新增槽位须先经 addSlot 生成占位。

## 前端动作

无必须动作：错误消息自解释，走全局错误提示即可。派车看板正常只发送已声明/已增槽的槽位索引，交互不变。若后续做 605911 专属引导文案，可按上表触发条件提示「调整需求车辆数或先增槽」。

## 验证证据

- 单测（AssignmentServiceTest 513 全绿）：越界索引批派 605911 拦截且 `insert` 零写入；`index=count-1` 命中/`index=count` 越界边界；占位消费的新增槽位仍成功；车型无法归一 605912 防御。`mvn -pl hl-fleet-service -am verify` 3838 测试仅剩 1 个 `ReleaseEMixedBinaryHarnessTest` Windows 环境抖动失败（基线 dev-v3 @ b93c7ddcc 同款失败、单跑通过）；Testcontainers 集成测试 12 条通过。
- 部署：PR #6064 squash 合并 dev-v3（merge commit `584f3adc3`）+ 文档对齐 PR #6065（`b07855c228`）；Deploy Panel task `d6cb4687` + `3bed5be8` success，测试服 jar mtime 2026-08-19 01:27:54（110669169 bytes），双实例 8087/8187 滚动重启健康。
- 网关实测（TEST，admin token）：复现单 R2 `HL20260818215924074`（需求声明 suv×1）批量派车 `fleetItemIndex=1` → **605911**（非 500）；复现单 R1 `HL20260818215914552` 同场景 → **605911**；同单合法索引 `fleetItemIndex=0` → 200 assigned，落库 `required_vehicle_type='suv'` 非空、越界请求零写入（DB 核对仅 2 行合法行）。

## 关联 / 联系人

- Issue：https://git.1814.love:8443/wx/HL/issues/6057
- PR：https://git.1814.love:8443/wx/HL/pulls/6064 （主修复）+ https://git.1814.love:8443/wx/HL/pulls/6065 （接口说明对齐）
- Commit（merge）：https://git.1814.love:8443/wx/HL/commit/584f3adc32e530389a994d92f3a002c312381632
- 后端负责人：wx
