From 9d7a1663e22700be67596819653a87bb02e28bb7 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Wed, 19 Aug 2026 01:33:38 +0800 Subject: [PATCH] =?UTF-8?q?chore(6057):=20=E5=A4=9A=E6=A7=BD=E4=BD=8D?= =?UTF-8?q?=E8=B6=8A=E9=9C=80=E6=B1=82=E7=B4=A2=E5=BC=95=E6=B4=BE=E8=BD=A6?= =?UTF-8?q?=E4=B8=9A=E5=8A=A1=E7=A0=81=20605911/605912=20=E6=9B=BF?= =?UTF-8?q?=E4=BB=A3=20500=EF=BC=88=E5=B7=B2=E9=83=A8=E7=BD=B2=E5=AE=9E?= =?UTF-8?q?=E6=B5=8B=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...越需求索引派车业务码拦截-修改接口-管理后台.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 changelogs-v2/2026-08/19_6057_多槽位越需求索引派车业务码拦截-修改接口-管理后台.md diff --git a/changelogs-v2/2026-08/19_6057_多槽位越需求索引派车业务码拦截-修改接口-管理后台.md b/changelogs-v2/2026-08/19_6057_多槽位越需求索引派车业务码拦截-修改接口-管理后台.md new file mode 100644 index 0000000..91818bd --- /dev/null +++ b/changelogs-v2/2026-08/19_6057_多槽位越需求索引派车业务码拦截-修改接口-管理后台.md @@ -0,0 +1,63 @@ +--- +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: "" +frontend_ref: "" +target_release: "" +verified_at: "" +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