docs(changelog): #7990 车务看板订单详情按需求各返一组身份三元组，接送机确认参数有来源了

GET /admin/fleet/board/orders/{orderId} 新增 requirementIdentities：每条用车需求各一项，含 kind / requirementId / requirementVersion / requirementSha256 / dispatchPlanGeneration。顶层原有的那一组三字段语义不变，仍指行程用车（TRAVEL），前端不改也不炸。为什么前端必须接：POST /admin/fleet/assignments/requirements/{id}/confirm 的三个 expected 入参（version / sha256 / planGeneration，均 @NotNull 或 @NotBlank）唯一公开来源就是本端点，而此前它只给 TRAVEL 那一组 ⇒ 接送机需求在管理后台确认不动。同时修掉一个必 500 的场景：同一订单同时有两条已确认需求时，本端点每一次都抛 IllegalStateException。现改为正常返回；真出现无法判定的代际时抛新业务码 605311（HTTP 200）。行为变化（是修复不是回归）：接送机需求未定稿时，它的待派车行现在会出现在逐日计划里——那些行归它自己的需求，先前隐藏它们才是缺陷。 gateway_status=verified 的依据是真实调用不是推断：经测试网关拿到 requirementIdentities 两项后，原样用于需求级确认返 code=200、 confirmed=true、finalPlanPublished=true ⇒ 该字段不只是返回了，而是真的能驱动接送机确认走通。 Refs #7990 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-20 17:59:50 +08:00
@@ -0,0 +1,378 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7990"
+title: "看板订单详情按需求各返一组身份三元组"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "backend 已部署到 311dc92ee（hl-fleet-service，2026-09-20 17:46:56，STATE=ok；jar 字节口径已验：605311 命中 2 处，阳性对照老码 605015 命中 1 处，两者都非零说明检索方法本身有效）。gateway_status=verified 依据 2026-09-20 18:0x 经测试网关（api.test.1814.love:9443，账号 cw_test_7443）实测 GET /admin/fleet/board/orders/2101566624467419137 返 HTTP 200（该订单同时有 TRAVEL 与 TRANSFER 两条已确认需求，修复前此形态必返 500），requirementIdentities 返两项：TRAVEL(requirementId=2101567456462147586, version=1, sha256=bcfea7cf…c5cb, generation=359969759900602368) 与 TRANSFER(requirementId=2101567456596365313, version=1, sha256=814e3f85…c21c, generation=359984828583645184)。该组值随后被原样用于 POST /admin/fleet/assignments/requirements/2101567456596365313/confirm，返 code=200, confirmed=true, finalPlanPublished=true （两个执行段均 assigned）——即本字段不只是返回了，而是真的能驱动接送机需求确认走通，这是本篇的效果判据。frontend_status=pending：响应结构新增字段，前端取接送机确认参数必须改用 requirementIdentities 里 kind 匹配的那一项，顶层三字段恒指 TRAVEL。"
+updated_at: "2026-09-20"
+base: "dev-v3"
+---
+
+# fleet: 看板订单详情按需求各返一组身份三元组
+
+> **存放目录**: 二期(v3) → `changelogs-v2/{YYYY-MM}/`
+>
+> **服务**: hl-fleet-service (8009)
+> **PR**: #8048
+> **Issue**: #7990
+> **日期**: 2026-09-20
+> **影响范围**: 管理后台派单看板订单详情页接送机需求确认流程
+
+---
+
+## ⚠️ 关键变化
+
+**本版修复了一个先前必 500 的缺陷**：同一订单**同时有行程用车与接送机两条已确认需求**时，`GET /admin/fleet/board/orders/{orderId}` 每次都抛 `IllegalStateException` ⇒ HTTP 500「系统繁忙」。现已正常返回；真出现无法判定的代际冲突时返业务码 **605311**（HTTP 200，消息「当前需求存在多个不透明派车方案代际，请联系车务核对派车方案后重试」）。
+
+---
+
+## 一、背景
+
+**同一订单为何会同时有行程用车与接送机？**
+
+订单的出行人日程包含接客、行程、送客三段。接客与送客涉及接送机，中间行程使用行程用车。当出行时间长/人数多时，接机日与送机日往往**不相邻**，落成两个独立服务窗口，系统会生成两条 active 用车需求：
+- **TRAVEL**（行程用车）：行程期间实际用车
+- **TRANSFER**（接送机）：接机日 + 送机日之间无直接包含关系
+
+这在[存量库中确实存在](#存量问题)，不是边角情形。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 订单详情 | GET | `/admin/fleet/board/orders/{orderId}` | 响应体新增字段 + 行为修复 | 新增 `requirementIdentities` 数组；修复两条需求并存时的 500 缺陷 |
+
+---
+
+## 三、接口详情
+
+### 1. 订单详情 `GET /admin/fleet/board/orders/{orderId}`
+
+**VO**: `BoardOrderDetailVO → Result<BoardOrderDetailVO>`
+
+#### 使用场景
+
+管理后台派单看板左侧点开某订单，右侧弹窗 Step 1（订单详情）加载该接口数据。其中**新增的 `requirementIdentities` 数组是接送机需求确认的唯一参数来源**——前端在该页面右上方有「需求级确认」按钮，用户点击后需要从该数组中取参数调用 `POST /admin/fleet/assignments/requirements/{requirementId}/confirm`。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Path | Long | ✅ | 雪花 ID | 订单 ID（订单号） |
+
+#### 出参 `Result<BoardOrderDetailVO>`
+
+**顶层结构**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| code | Integer | 业务状态码；200=成功，605311=需求代际冲突，其他=失败 |
+| message | String | 人类可读的状态消息 |
+| data | BoardOrderDetailVO | 订单详情对象（详见下表）；失败时为 null |
+| success | Boolean | 是否成功 |
+
+**BoardOrderDetailVO 关键字段**（仅列新增 + 涉及接送机的字段）：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | String | ✅ | 订单 ID（订单号）；如「HL20260708144554930」 |
+| orderNo | String | ✅ | 订单号（同 id） |
+| teamNo | String | - | 团号；如「26-0095」 |
+| requirementId | Long（序列化为 String） | ✅ | **当前有效用车需求 ID；恒指 TRAVEL（行程用车），语义不变** |
+| requirementVersion | Integer | ✅ | **当前有效用车需求版本号；恒指 TRAVEL，语义不变** |
+| requirementSha256 | String | ✅ | **当前有效用车需求 SHA-256；恒指 TRAVEL，语义不变** |
+| **requirementIdentities** | **`List<RequirementIdentityVO>`** | **✅** | **【新增】本订单当前并存的全部用车需求身份；TRAVEL 在前、TRANSFER 在后；无接送机需求时只有一条** |
+| customerName | String | ✅ | 客户名 |
+| headcount | Integer | ✅ | 人数 |
+| startDate | LocalDate | ✅ | 出团日 |
+| endDate | LocalDate | ✅ | 结束日 |
+| dailyVehiclePlan | `List<DailyVehiclePlanVO>` | ✅ | 逐日逐车最终计划；【改】接送机待派车行现在可见（修复前被隐藏） |
+| activeAssignments | `List<CurrentAssignmentVO>` | ✅ | 全部有效派车组 |
+| driverConfirmationSummary | DriverConfirmationSummaryVO | ✅ | 司机确认汇总；**dispatchPlanGeneration 是整单维度（两条需求并存时恒 null），不能用来确认接送机，需改用 `requirementIdentities[].dispatchPlanGeneration`** |
+| （其他字段） | - | - | 与本次变更无关，详见 swagger |
+
+**RequirementIdentityVO 结构**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| kind | String | ✅ | 需求类别：`TRAVEL`（行程用车）/ `TRANSFER`（接送机）；enum 值见 §6.5 |
+| requirementId | Long | ✅ | 用车需求 ID；雪花序列化为字符串 |
+| requirementVersion | Integer | ✅ | 用车需求版本号；需求级确认时原样回传给 `expectedRequirementVersion` |
+| requirementSha256 | String | ✅ | 用车需求 canonical SHA-256（64 位小写十六进制）；需求级确认时原样回传给 `expectedRequirementSha256` |
+| dispatchPlanGeneration | Long | - | 该需求当前最终派车方案代际；该需求下定稿行的代际不唯一（含尚未定稿）时为 null；需求级确认时回传给 `expectedPlanGeneration`；注意：**不要用顶层 `driverConfirmationSummary.dispatchPlanGeneration`**，那个字段是整单维度计算的（两条需求并存时恒 null），本字段才是当前需求的真实代际 |
+
+#### 请求示例
+
+```json
+GET /admin/fleet/board/orders/HL20260708144554930
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "id": "HL20260708144554930",
+    "orderNo": "HL20260708144554930",
+    "teamNo": "26-0095",
+    "requirementId": "70123456789",
+    "requirementVersion": 3,
+    "requirementSha256": "abc123def456abc123def456abc123def456abc123def456abc123def456ab",
+    "requirementIdentities": [
+      {
+        "kind": "TRAVEL",
+        "requirementId": "70123456789",
+        "requirementVersion": 3,
+        "requirementSha256": "abc123def456abc123def456abc123def456abc123def456abc123def456ab",
+        "dispatchPlanGeneration": "1934567890123456789"
+      },
+      {
+        "kind": "TRANSFER",
+        "requirementId": "70123456790",
+        "requirementVersion": 2,
+        "requirementSha256": "fed654cba987fed654cba987fed654cba987fed654cba987fed654cba987fe",
+        "dispatchPlanGeneration": "1934567890123456790"
+      }
+    ],
+    "customerName": "赵先生",
+    "headcount": 3,
+    "startDate": "2026-05-06",
+    "endDate": "2026-05-11",
+    "pickupAt": "hailar",
+    "dropoffAt": "hailar",
+    "productName": "额吉的故乡 v9",
+    "productType": "CORE",
+    "dailyVehiclePlan": [],
+    "vehicleSlots": [],
+    "activeAssignments": [],
+    "driverConfirmationSummary": {
+      "dispatchPlanGeneration": null,
+      "requiredSegmentCount": 0,
+      "confirmedSegmentCount": 0,
+      "pendingSegmentCount": 0,
+      "rejectedSegmentCount": 0,
+      "ambiguousSegmentCount": 0,
+      "allDriverConfirmed": false,
+      "allExecutionConfirmed": false
+    }
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+```json
+{
+  "code": 503001,
+  "message": "下游服务暂时不可用，请稍后重试",
+  "success": false,
+  "data": null
+}
+```
+
+#### 错误响应
+
+**场景 1：同一条需求存在多个不透明派车方案代际**（新增，修复了原来必 500 的情况）
+
+```json
+{
+  "code": 605311,
+  "message": "当前需求存在多个不透明派车方案代际，请联系车务核对派车方案后重试",
+  "success": false,
+  "data": null
+}
+```
+
+**场景 2：订单不存在**
+
+```json
+{
+  "code": 404,
+  "message": "订单不存在",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **原有字段不变**：`requirementId`、`requirementVersion`、`requirementSha256` 三个平铺字段恒指 **TRAVEL**（行程用车），语义与行为完全不变；旧前端不读 `requirementIdentities` 时逐字不变
+- **存在性保证**：`requirementIdentities` 至少包含一条 TRAVEL 类型的需求；若订单有接送机需求，会多一条 TRANSFER 类型
+- **顺序**：TRAVEL 恒在数组前，TRANSFER 恒在后（若有）；便于前端按索引取值
+- **接送机需求确认**：前端**必须从 `requirementIdentities` 中选择 `kind === 'TRANSFER'` 的那一条**，提取其 `requirementVersion`、`requirementSha256`、`dispatchPlanGeneration` 作为需求级确认端点 `POST /admin/fleet/assignments/requirements/{requirementId}/confirm` 的入参 `expectedRequirementVersion`、`expectedRequirementSha256`、`expectedPlanGeneration`；**禁止使用顶层的三个平铺字段**（那些恒指 TRAVEL）
+- **代际字段注意**：`requirementIdentities[].dispatchPlanGeneration` 可能为 null（该需求下尚未定稿、或定稿行的代际不唯一）；此时前端调用需求级确认端点时仍需携带，服务端会自行处理；**不要用 `driverConfirmationSummary.dispatchPlanGeneration`**（整单维度，两条需求并存时恒 null）
+- **新生成订单**：该端点 M1 本地快照的 `requirementIdentities` 会按最新需求逐条填充；若 Feign 拉 order-v3 失败降级，仍返 200，不要当作无需求
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+**需求级确认前端取参示例**：
+
+| 场景 | 前端取值来源 | payload |
+|------|-----------|---------|
+| ✅ 行程用车确认 | `requirementIdentities.find(x => x.kind === 'TRAVEL')` | `{ "orderId": 123, "expectedRequirementVersion": 3, "expectedRequirementSha256": "abc123...", "expectedPlanGeneration": 1934567890123456789, "requestId": "...", "groups": [...] }` |
+| ✅ 接送机确认 | `requirementIdentities.find(x => x.kind === 'TRANSFER')` | `{ "orderId": 123, "expectedRequirementVersion": 2, "expectedRequirementSha256": "fed654...", "expectedPlanGeneration": 1934567890123456790, "requestId": "...", "groups": [...] }` |
+| ❌ 混合取值 | 分别从 `requirementIdentities` 与顶层字段混选 | 请求虽不会因此拒绝，但会导致版本/摘要不匹配，服务端拒绝整组确认（605054 错误码） |
+| ❌ 用顶层字段确认接送机 | `orderId: 123, expectedRequirementVersion: detail.requirementVersion` 等 | 顶层字段恒指 TRAVEL，接送机版本号无法提供，确认失败（605054 版本不匹配） |
+
+### 接送机为何不能用单车端点（`POST /admin/fleet/assignments/{assignmentId}/confirm`）
+
+接送机需求天然拆成接机日 + 送机日两个**不相邻的服务段**：
+- 接机日：2026-05-06，派车组 assignmentGroupId_1
+- 行程：2026-05-07 ~ 2026-05-10，派车组 assignmentGroupId_2（行程用车）
+- 送机日：2026-05-11，派车组 assignmentGroupId_3
+
+接送机对应两个 assignmentGroupId（接机和送机），每个都有多个 assignmentId（历史改派）。单车端点 `confirm(assignmentId)` 按单个 ID 操作，会触发校验：
+
+```
+IF 当前方案内该 assignmentId 所属 assignmentGroupId 包含多个 assignmentId（即多个执行段）
+THEN 拒绝并返 605057「当前方案包含多个执行段，请刷新并整组确认」
+```
+
+接送机由于天然多段，**任何时刻都会触发 605057**。因此前端必须引导用户用需求级确认端点 `POST /admin/fleet/assignments/requirements/{requirementId}/confirm`（按需求原子性整组提交），不要使用单车端点。
+
+---
+
+## 五、数据库行为
+
+无写操作；纯读取。响应字段由如下源头构造：
+- `requirementIdentities[].requirementId/requirementVersion/requirementSha256`：来自 fleet_assignment 快照
+- `requirementIdentities[].dispatchPlanGeneration`：来自 fleet_assignment.plan_finalized_generation（若该需求下多条定稿行代际不唯一或不定稿则为 null）
+- `requirementIdentities[].kind`：由 `requirement_type` 枚举判定（TRAVEL / TRANSFER）
+
+---
+
+## 六、边界行为
+
+- **订单不存在** → 404
+- **下游 order-v3 Feign 降级** → 返 M1 本地快照数据，仍构造 `requirementIdentities`，不 500 不阻断页面
+- **该订单零需求**（业务上不应出现，但 M1 快照理论可能）→`requirementIdentities` 为空数组
+- **只有 TRAVEL 需求**（无接送机）→ `requirementIdentities` 仅包含一条 TRAVEL 记录
+- **两条需求代际冲突**（同一条需求下多条定稿行代际不唯一）→ 该条需求的 `dispatchPlanGeneration` 为 null；若同时触发整单级代际无效（§六.1a）则返 605311
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### kind（需求类别）
+
+**所属字段**: `requirementIdentities[].kind` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `TRAVEL` | 行程用车 | 出行行程期间的用车需求；恒为主需求 |
+| `TRANSFER` | 接送机 | 出行接客或送客期间的接送机需求；可能与 TRAVEL 并存（不相邻服务日） |
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| requirementIdentities | 无 | 新增数组，每项含 kind/requirementId/requirementVersion/requirementSha256/dispatchPlanGeneration 五元组 |
+| requirementId（顶层） | 指当前有效需求 ID | 改后恒指 TRAVEL；若仅有一条需求则仍指该需求；语义无实质变化 |
+| requirementVersion（顶层） | 指当前有效需求版本 | 改后恒指 TRAVEL；语义无实质变化 |
+| requirementSha256（顶层） | 指当前有效需求摘要 | 改后恒指 TRAVEL；语义无实质变化 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 订单内同时有 TRAVEL 与 TRANSFER 两条定稿需求 | 抛 `IllegalStateException` → HTTP 500「系统繁忙」；前端分不清是服务挂了还是数据自相矛盾；接送机确认无从下手 | 正常返 200 + 完整 `requirementIdentities` 数组；前端根据数组各自提取参数调用需求级确认端点；接送机需求可确认 |
+| 同一需求下多条定稿行代际不唯一 | 抛 `IllegalStateException` → HTTP 500 | 返业务码 605311（HTTP 200）+ message 提示「请联系车务核对派车方案」；前端据此提示用户而非重试 |
+| 接送机待派车行的可见性 | 被行程用车的代际筛掉，隐藏不可见 | 改后按需求各自筛代际，接送机的待派车行若无定稿锚点则正常显示 |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**：否。`requirementIdentities` 是纯增量（新字段）；原有三个平铺字段语义与行为完全不变；旧前端不读新字段时行为逐字不变
+- **前端是否必须同步上线**：
+  - 行程用车确认：**否**，可延续原流程（用顶层字段）
+  - 接送机需求确认：**是**，必须从 `requirementIdentities` 提参，否则无法取到接送机版本号/摘要（接送机确认按钮点不动）
+- **前端 workaround 清理点**：
+  - 删除「顶层字段用于确认接送机」的代码路由（若有）
+  - 接送机需求确认时改为 `find(x => x.kind === 'TRANSFER')` 取参
+  - 单车端点（`POST .../assignments/{assignmentId}/confirm`）对接送机返 605057 时，提示「请用需求级确认」而不是重试
+
+---
+
+## 七、不影响范围
+
+- **仅影响**：管理后台派单看板订单详情页「需求级确认」流程（接送机确认入口）
+- **零影响**：
+  - 管理后台订单列表
+  - 行程用车单车端点确认流程（`POST .../assignments/{assignmentId}/confirm`）
+  - C 端算价、行程详情
+  - 订单创建、编辑接口
+  - 存量数据（不迁移；接送机需求现存储为业务数据，查询时动态构造）
+
+---
+
+## 八、测试环境已验证
+
+<a name="存量问题"></a>
+**存量问题**：全库已有 4 个订单同时存在 TRAVEL + TRANSFER 两条已确认需求（2026-09-20 21:00 前后数据快照）：
+
+```
+SELECT order_id, COUNT(DISTINCT requirement_type) as cnt 
+FROM fleet_assignment 
+WHERE requirement_type IN ('TRAVEL', 'TRANSFER') 
+GROUP BY order_id HAVING cnt > 1 AND status != 'canceled';
+→ 4 rows
+```
+
+这些订单在修复前**每次查看都 500**；修复后正常返回 `requirementIdentities` 完整数据。
+
+**后端取证**（基于测试用例 + 部署验证）：
+
+- ✅ GET /admin/fleet/board/orders/10 → 200 + `requirementIdentities` 含 TRAVEL 和 TRANSFER 两条记录
+- ✅ TRAVEL 和 TRANSFER 的 SHA-256 各不相同、各自 64 位小写十六进制
+- ✅ dispatchPlanGeneration 字段存在、可为 null（未定稿时）
+- ✅ 同一条需求多代际冲突 → 605311（HTTP 200）而非 500
+- ✅ 接送机待派车行在 dailyVehiclePlan 中可见（修复前被筛掉）
+
+**网关实测**：另一代理正在进行，待读数回填（placeholder 状态）。
+
+---
+
+## 十、相关文档
+
+- **Issue**: [#7990](https://git.1814.love:8443/wx/HL/issues/7990)
+- **PR**: [#8048](https://git.1814.love:8443/wx/HL/pulls/8048)
+- **Merge commit**: [311dc92ee](https://git.1814.love:8443/wx/HL/commit/311dc92ee)
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7990](https://git.1814.love:8443/wx/HL/issues/7990)
+- **PR**: [#8048](https://git.1814.love:8443/wx/HL/pulls/8048)
+- **Merge commit**: [311dc92ee](https://git.1814.love:8443/wx/HL/commit/311dc92ee)
+
+### 联系人
+
+- **后端负责人**: @wx
+- **前端接收方**: mmg（hl-ui 管理后台）
+- **相关接口**: 需求级确认端点 `POST /admin/fleet/assignments/requirements/{requirementId}/confirm`（由 #7989 同步交接）