From 877d69e651e1a9309f40ace0129e61ff13241e7d Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Wed, 30 Sep 2026 14:24:21 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=208560=20=E8=AE=A2=E6=AD=A3=20?= =?UTF-8?q?requirementId=20=E4=B8=A4=E5=8D=A1=E6=98=AF=E5=90=A6=E5=90=8C?= =?UTF-8?q?=E5=80=BC=E6=8C=89=E8=B7=AF=E5=BE=84=E5=88=86=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 原文按真实行路径过度概括成「两张卡 requirementId 恒相同」。实测代码：MatrixService.java:497-498 真实行优先取订单侧单值（两卡相同），:637-638 虚拟待派条目优先取候选自身需求 ID（两卡不同），而未派订单最常见的形态正是后者。四处（正文口径、出参表、业务边界、测试说明）一并按路径分档，判类别只认 requirementKind 的结论不变、且更必要。 Refs #8560 Co-Authored-By: Claude Opus 5 (1M context) --- ...下发用车需求类别可区分行程用车与接送机-修改接口-管理后台.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/changelogs-v2/2026-09/30_8560_矩阵未派订单卡下发用车需求类别可区分行程用车与接送机-修改接口-管理后台.md b/changelogs-v2/2026-09/30_8560_矩阵未派订单卡下发用车需求类别可区分行程用车与接送机-修改接口-管理后台.md index 35822ed6..028707d4 100644 --- a/changelogs-v2/2026-09/30_8560_矩阵未派订单卡下发用车需求类别可区分行程用车与接送机-修改接口-管理后台.md +++ b/changelogs-v2/2026-09/30_8560_矩阵未派订单卡下发用车需求类别可区分行程用车与接送机-修改接口-管理后台.md @@ -35,7 +35,7 @@ base: "dev-v3" - 🔴 **`null` 不兜底成 `TRAVEL`**，这是本次修复的核心边界。判不出类别（跨服务降级 context=null；或派车行挂着 #5720 换版过渡窗里的上一版 `requirement_id`，命中不了任何当前活跃身份；或命中的身份自身 `kind` 为空白）时两个新字段均为 `null`，前端应不显示类别标签，**禁止自行按业务猜测补默认值**——尤其禁止把 `null` 当 `TRAVEL` 处理。 - 与看板列表（`BoardOrderRecordVO.requirementKind`，#8518 既有）**在判不出这一档口径不同**：看板列表的解析方法判不出时兜底返 `TRAVEL`（那里类别同时是筛选维度，返空会让卡片从筛选后的视图里彻底消失）；矩阵未派卡判不出时返 `null`（那里类别只是展示标签，车务会照标签去排完全不同的活，标错比不标更危险）。**同一张实体卡在两个入口可能显示不一致的类别信息，这是刻意保留的差异**，不是缺陷。 - 真实未派行与虚拟待派条目（`virtualPending=true`，#7067）两类条目都携带这两个新字段，取值口径一致。 -- 类别取的是**这张卡自身所属需求**（真实行用该行自己的 `requirement_id`，虚拟条目用该候选自己的 `requirementId`）解析出的类别，**不是**已有字段 `requirementId`（该字段取「订单侧单值」，#5667 口径，同一订单两类需求并存时恒指向身份列表首项、即恒为 TRAVEL 那条）。同一订单两张卡的 `requirementId` 字段取值会相同，但 `requirementKind`/`requirementKindLabel` 不同——这正是新增这两个字段的意义所在，不能拿旧字段替代判断。 +- 类别取的是**这张卡自身所属需求**（真实行用该行自己的 `requirement_id`，虚拟条目用该候选自己的 `requirementId`）解析出的类别，**不是**已有字段 `requirementId`（该字段取「订单侧单值」，#5667 口径，同一订单两类需求并存时恒指向身份列表首项、即恒为 TRAVEL 那条）。⚠️ `requirementId` 字段两张卡是否相同**取决于这张卡走哪条路径**：`virtualPending=true`（未派池的虚拟待派条目，未派订单最常见的形态）下它取该候选自身的需求 ID，两张卡**不相同**；`virtualPending=false`（已有派车行的真实行）下它优先取订单侧单值，两张卡**相同**。两条路径都不能拿 `requirementId` 判类别——相同时它分辨不出，不同时它也只是碰巧对得上。判类别一律只认 `requirementKind`/`requirementKindLabel`。 --- @@ -68,7 +68,7 @@ base: "dev-v3" |------|------|------| | requirementKind | String | **新增**。用车需求类别：`TRAVEL`=行程用车 / `TRANSFER`=接送机 / `null`=判不出（不兜底为 TRAVEL） | | requirementKindLabel | String | **新增**。类别中文名：`行程用车`/`接送机`/`null`，与 requirementKind 恒成对 | -| requirementId | Long（字符串序列化） | 既有字段，当前生效用车需求 ID；取订单侧单值（#5667），两类需求并存时恒指向 TRAVEL 那条，**不能**用它推导 requirementKind | +| requirementId | Long（字符串序列化） | 既有字段，这张卡对应的用车需求 ID。`virtualPending=false` 时优先取订单侧单值（#5667，两类并存时恒指向 TRAVEL 那条）；`virtualPending=true` 时取该候选自身的需求 ID。**两条路径取值口径不同，一律不能用它推导 requirementKind** | | assignmentId | Long（字符串序列化） | 既有字段，本行唯一主键；虚拟待派条目为 null | | virtualPending | Boolean | 既有字段，true=虚拟待派条目（零派车行订单，按需求上下文补出） | | vehicleCategory | String | 既有字段，规范小写车型 key（suv/mpv/bus/sedan），与需求类别是两个不同维度 | @@ -143,7 +143,7 @@ GET /admin/fleet/matrix/unassigned-orders?year=2026&month=11&typeKeys=mpv - `401` 未登录。 #### 业务边界 -- **同一订单两类需求并存时，两张卡的 `requirementId` 字段值完全相同（均指向 TRAVEL 那条），但 `requirementKind`/`requirementKindLabel` 不同**——单元测试 `MatrixServiceTest#queryUnassignedOrders_orderWithBothKinds_twoCardsCarryDifferentKinds` 对此有显式反向对照断言，用来证明「拿 requirementId 反推类别」是错的，前端也不能这么做。 +- **同一订单两类需求并存时，两张卡的 `requirementKind`/`requirementKindLabel` 必不相同；而 `requirementId` 字段是否相同取决于路径**——真实行（`virtualPending=false`）下两张卡相同（均取订单侧单值），虚拟待派条目（`virtualPending=true`）下两张卡各取自身需求 ID、并不相同。单元测试 `MatrixServiceTest#queryUnassignedOrders_orderWithBothKinds_twoCardsCarryDifferentKinds` 断言的是**真实行**那条路径。两条路径都不能拿 `requirementId` 反推类别，前端也不能这么做。 - `requirementKind=null` 时前端**禁止**折算成 `TRAVEL`；这既是判不出的真实状态，也是修复前的错误行为，回退等于复发。 - 矩阵未派卡与看板列表对同一张孤儿行（#5720 换版过渡窗）的类别展示口径不同（前者 null、后者兜底 TRAVEL），这是刻意保留的差异，不要据此判断某一端有 bug。 - 真实未派行与虚拟待派条目两种类型都下发这两个字段，前端不需要按 `virtualPending` 分支处理类别逻辑。 @@ -216,7 +216,7 @@ GET /admin/fleet/matrix/unassigned-orders?year=2026&month=11&typeKeys=mpv - 对 2026-06 ~ 2027-03 共 10 个月窗口的扫描（合计 14 条记录）未发现 `requirementKind=null` 的记录，也未发现同一订单出现两条不同类别记录的活跃实例——测试服当前业务数据里暂未出现这两种边界场景，实测未覆盖，靠下面的单元测试兜底。 - **单元测试覆盖（源码单测验证，未在测试服活数据上复现）**： - `BoardRequirementIdentitiesKindTest`（5/5 通过）：覆盖双身份按需求 ID 各取各类别、上下文降级返 null（对照既有方法仍兜底 TRAVEL）、陈旧需求 ID 不猜返 null、身份自身类别空白返 null、灰度上下文合成 TRAVEL 身份仍可取到。 - - `MatrixServiceTest` 新增 6 个 `#8560` 测试方法（均通过）：同订单两类需求两张卡类别互不相同（含反向对照：两张卡 `requirementId` 字段完全相同）、需求身份类别空白返 null 不兜底 TRAVEL、上下文降级返 null 不兜底 TRAVEL、派车行挂陈旧需求 ID（#5720）返 null 不兜底 TRAVEL、虚拟待派条目携带类别、虚拟待派条目无身份列表时类别为 null。 + - `MatrixServiceTest` 新增 6 个 `#8560` 测试方法（均通过）：同订单两类需求两张卡类别互不相同（含反向对照：**真实行路径**下两张卡 `requirementId` 字段完全相同；虚拟待派路径不适用该对照）、需求身份类别空白返 null 不兜底 TRAVEL、上下文降级返 null 不兜底 TRAVEL、派车行挂陈旧需求 ID（#5720）返 null 不兜底 TRAVEL、虚拟待派条目携带类别、虚拟待派条目无身份列表时类别为 null。 - 聚合结果（`mvn -pl hl-fleet-service -am test`）：`Tests run: 365, Failures: 0, Errors: 0, Skipped: 0`，`BUILD SUCCESS`；含 `VehicleRequirementKindsTest` 4、`BoardOrderServiceTest` 233、`FleetRedLineArchTest` 18（架构守护门禁绿）。 - 嵌套用例选择器守卫（`nested_selector_census`）：通过，内层名比对无缺组。 - `spotless:check`：`BUILD SUCCESS`，916 文件全部合规。