From ffecb0f2d233de76bf8559817f2e657254d9d674 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Sun, 27 Sep 2026 21:59:17 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#8430=20=E7=BA=AF=E6=8E=A5?=
 =?UTF-8?q?=E9=80=81=E6=9C=BA=E8=AE=A2=E5=8D=95=E7=9C=8B=E6=9D=BF=E8=AF=A6?=
 =?UTF-8?q?=E6=83=85=E6=94=B9=E6=8C=89=E6=8E=A5=E9=80=81=E6=9C=BA=E9=9C=80?=
 =?UTF-8?q?=E6=B1=82=EF=BC=88TRANSFER=EF=BC=89=E5=8F=96=E6=95=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 ...•çœ‹æ�¿è¯¦æƒ…改按接é€�机需求å�–æ•°-修改接å�£-管ç�†å�Žå�°.md | 296 ++++++++++++++++++
 1 file changed, 296 insertions(+)
 create mode 100644 changelogs-v2/2026-09/27_8430_纯接�机订�看�详情改按接�机需求�数-修改接�-管���.md

diff --git a/changelogs-v2/2026-09/27_8430_纯接�机订�看�详情改按接�机需求�数-修改接�-管���.md b/changelogs-v2/2026-09/27_8430_纯接�机订�看�详情改按接�机需求�数-修改接�-管���.md
new file mode 100644
index 00000000..e673a2ca
--- /dev/null
+++ b/changelogs-v2/2026-09/27_8430_纯接�机订�看�详情改按接�机需求�数-修改接�-管���.md
@@ -0,0 +1,296 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8430"
+title: "纯接�机订�看�详情改按接�机需求（TRANSFER）�数：门��求日��日方案�车数�进度�方案代际"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接�"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "PR #8452 已�入 dev-v3（squash 0bae84b59）。TEST 环境 hl-fleet-service 0bae84b59 于 2026-09-27 20:29:52 部署�21:12 �核未�，hl-gateway 71def6dc5；�一张纯接�机订�在部署�（fleet 267ab6906）与部署���一次详情�对照，结论�第八节。�改看�详情一个接�，看�列表未改；TRAVEL 与 TRANSFER 并存的订�行为��。"
+updated_at: "2026-09-27"
+base: "dev-v3"
+---
+
+# fleet: 纯接�机订�看�详情改按接�机需求（TRANSFER）�数
+
+**�务**: hl-fleet-service
+**PR**: `#8452`（已�入 `dev-v3`，squash `0bae84b59`）
+**Issue**: #8430
+**日期**: 2026-09-27
+**影�范围**: 管���车务看�「订�详情�，�影�**纯接�机订�**（�有 TRANSFER 用车需求�没有 TRAVEL 需求）
+
+---
+
+## ⚠� 关键�化
+
+🟡 **纯接�机订�的详情终于有内容了。** 改�这类订�打开详情，�数�按（并�存在的）TRAVEL 需求走：`dailyVehiclePlan` �为空数组�`suggestedVehicleCount`/`actualVehicleCount` �为 0�进度�在第 1 步�接�机门�的�求日��了订�出�日与返回日。改�这些字段都按 TRANSFER 需求�值。**�应结构�字段��字段类型都没有�**，�的�是纯接�机订�上这些字段的�值。
+
+🟡 **顶层 `requirementId` / `requirementVersion` / `requirementSha256` 对纯接�机订��为 null**（设计如此）。�拿接�机需求的身份（例如调需求级确认接�），请用 `requirementIdentities` 里 `kind=TRANSFER` 那一�。
+
+🟡 **纯接�机订�现在也�能返回 605311。** 这个错误� #7990 就有，此��会出现在 TRAVEL 订�上；改��一判�也作用于 TRANSFER 需求，�端按已有的 605311 处���。
+
+---
+
+## 一�背景
+
+纯接�机订�（�下了接�机�没有行程用车）在车务看�打开详情时，�端 `BoardOrderService.queryOrderDetail` �按 TRAVEL 需求�数。TRAVEL 缺席，于是窗��门���日方案�车数�进度全部�空或�到订�快照兜底，车务在详情里看�到任何已派的车，也拼�出需求级确认�回传的方案代际。
+
+本�改为：TRAVEL 缺席时，以 TRANSFER 需求作为「有效需求��数。TRAVEL 存在时有效需求就是 TRAVEL，�字沿用原逻辑。
+
+---
+
+## 二��更接�清�
+
+| # | 接� | 方法 | 路径 | �更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 车务看�订�详情 | GET | `/admin/fleet/board/orders/{orderId}` | 修改（�值） | 纯接�机订�按 TRANSFER 需求�数；结构�� |
+
+---
+
+## 三�接�详情
+
+### 1. 车务看�订�详情 `GET /admin/fleet/board/orders/{orderId}`
+
+**VO**: `BoardOrderDetailVO`
+
+#### 使用场景
+
+管���车务看�，点开一张订�的详情抽屉。纯接�机订�现在能看到�日派车方案�实派车数�接�机缺�与进度，并能从 `requirementIdentities` 拿到接�机需求的版本�指纹与方案代际，用于需求级确认。
+
+#### 入�字段表
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|------|------|------|------|------|------|
+| orderId | Path | Long | 是 | 订�主键（雪花 ID） | 看�列表行里的订� ID |
+
+#### 出�字段表
+
+�列本�改��值的字段，其余字段与改�一致。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| requirementId | String | **�值��**：纯接�机订��为 null（�指� TRAVEL 需求） |
+| requirementVersion | Integer | **�值��**：纯接�机订��为 null |
+| requirementSha256 | String | **�值��**：纯接�机订��为 null |
+| requirementIdentities | List | ��需求一个身份；纯接�机订��有一� `kind=TRANSFER`。**改�**其 `dispatchPlanGeneration` 按该需求自己的已定稿行计算（改�纯接�机订��为 null） |
+| requirementIdentities[].dispatchPlanGeneration | String | 该需求已定稿行的唯一方案代际；该需求还没有已定稿行�或已定稿行没有代际时为 null，�端按�空处� |
+| pickupDropoffGate.arrivalRequiredDates | List | **改�**�自 TRANSFER 需求声明的接机�务日；改���订�出�日 |
+| pickupDropoffGate.departureRequiredDates | List | **改�**�自 TRANSFER 需求声明的�机�务日；改���订�返回日 |
+| pickupDropoffGate.missingPickupDates / missingDropoffDates | List | 按上�的�求日与实际标记�与的派车行�新计算 |
+| dailyVehiclePlan | List | **改�**返回 TRANSFER 需求的�日派车行；改�纯接�机订��为空数组。已完结的行 `readOnly=true`�`readOnlyReason="派�已完结"` |
+| suggestedVehicleCount | Integer | **改�**按 TRANSFER 需求计算；改��为 0 |
+| actualVehicleCount | Integer | **改�**按 TRANSFER 需求的派车行计算；改��为 0 |
+| progressSteps | List | **改�**按 TRANSFER 需求的派车行推进；改��在第 1 步 |
+
+#### 请求示例
+
+```http
+GET /admin/fleet/board/orders/2104161383220457474
+Authorization: Bearer <车务账� token>
+```
+
+#### �应示例
+
+测试�实测（纯接�机订�，部署�，截�关键字段；`dailyVehiclePlan` 共 7 行，�列两行）：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "orderNo": "HL20260927184901765",
+    "teamNo": "26-9179",
+    "startDate": "2027-08-03",
+    "endDate": "2027-08-09",
+    "requirementId": null,
+    "requirementVersion": null,
+    "requirementSha256": null,
+    "requirementIdentities": [
+      {
+        "kind": "TRANSFER",
+        "requirementId": "2104185762864115714",
+        "requirementVersion": 5,
+        "requirementSha256": "36bc63bf38bc881a7f5a48222538f232a304600cd970627247729262983b78e0",
+        "dispatchPlanGeneration": "362573468547551232"
+      }
+    ],
+    "suggestedVehicleCount": 1,
+    "actualVehicleCount": 3,
+    "dispatchReadOnly": false,
+    "pickupDropoffGate": {
+      "arrivalRequiredDates": ["2027-08-30", "2027-09-05"],
+      "departureRequiredDates": ["2027-08-09"],
+      "missingPickupDates": ["2027-08-30"],
+      "missingDropoffDates": [],
+      "declared": true,
+      "satisfied": false
+    },
+    "progressSteps": [
+      {"step": 1, "code": "ORDER_DETAIL", "status": "DONE"},
+      {"step": 2, "code": "DISPATCH", "status": "DONE"},
+      {"step": 3, "code": "PICKUP_DROPOFF", "status": "PROCESSING"},
+      {"step": 4, "code": "CONFIRM_EXECUTE", "status": "WAITING"}
+    ],
+    "dailyVehiclePlan": [
+      {
+        "serviceDate": "2027-08-03",
+        "assignmentId": "2104162972542935041",
+        "planFinalized": true,
+        "planState": "USED",
+        "pickupParticipant": true,
+        "assignmentStatus": "completed",
+        "readOnly": true,
+        "readOnlyReason": "派�已完结"
+      },
+      {
+        "serviceDate": "2027-09-05",
+        "assignmentId": "2104183651266863105",
+        "planFinalized": false,
+        "planState": "UNPLANNED",
+        "pickupParticipant": true,
+        "pickupRequired": true,
+        "assignmentStatus": "assigned",
+        "readOnly": false,
+        "readOnlyReason": null
+      }
+    ]
+  },
+  "success": true
+}
+```
+
+#### 空数� / �级�应
+
+- 纯接�机订�还没派过车：`dailyVehiclePlan` 为空数组�`actualVehicleCount=0`�`requirementIdentities[TRANSFER].dispatchPlanGeneration=null`，门��求日照常按 TRANSFER 需求给出。
+- TRAVEL 与 TRANSFER 两�需求都��到（订��务��达，`relatedDetailReady=false`）：与改�完全一致，顶层字段走订�快照兜底。
+
+#### 错误�应
+
+```json
+{
+  "code": 605311,
+  "message": "当�需求存在多个��明派车方案代际，请�系车务核对派车方案��试",
+  "data": null,
+  "success": false
+}
+```
+
+| 错误� | 触��件 |
+|---|---|
+| 605311 | 有效需求（纯接�机订�� TRANSFER 需求）的已定稿派车行出现一个以上方案代际，或无代际的�定稿行与有代际的行混在一起。看��猜当�代际，直接返回该�（HTTP 200）。错误�本身�是新增的（#7990），本�之�纯接�机订�也会走到这个判� |
+
+#### 业务边界
+
+- �改看�**详情**；看�**列表**未改。�一张纯接�机订�在列表与详情里的派车状��车辆�需求身份已实测一致；列表的 `currentStep` 按 3 步编��详情的 `progressSteps` 按 4 步编�，两者本�就���，�是本�引入的差异。
+- TRAVEL 与 TRANSFER 并存的订�：有效需求就是 TRAVEL，�个字段的�值与改��字相�。
+- 打开详情�会改� TRANSFER 需求的状�（�有 TRAVEL 需求会在打开详情时被置为处�中，这一点没�）。
+- `dispatchReadOnly` 的判�没�：�是「行程已结��（订�返回日早于今天）�为 true；�行是��读看 `dailyVehiclePlan[].readOnly`。
+- 纯接�机订�调需求级确认接�时，`expectedRequirementVersion` / `expectedRequirementSha256` / `expectedPlanGeneration` � `requirementIdentities` 中 `kind=TRANSFER` 那一�；`dispatchPlanGeneration` 为 null 时说明该需求还没有唯一的已定稿方案，此时�能按「已定稿方案�确认。
+
+---
+
+## 四�契约约�与正确调用方�
+
+纯接�机订�的需求身份一律从 `requirementIdentities` �，��读顶层 `requirementId`：
+
+```js
+const transfer = (detail.requirementIdentities || []).find(x => x.kind === 'TRANSFER');
+// 纯接�机订�：顶层 requirementId 为 null，身份一律从 transfer �
+const expected = transfer && {
+  expectedRequirementVersion: transfer.requirementVersion,
+  expectedRequirementSha256: transfer.requirementSha256,
+  expectedPlanGeneration: transfer.dispatchPlanGeneration, // �能为 null
+};
+```
+
+---
+
+## 五�数�库行为
+
+无 DDL�无写入。本��改详情接�的内存组装，打开详情�写任何表。
+
+---
+
+## 六�边界行为
+
+### 605311 的触���大
+
+判�本身没�（有效需求的已定稿行�能有一个方案代际，�的无代际定稿行�能与有代际的行混在一起），�的是它现在也作用于纯接�机订�的 TRANSFER 需求。�端沿用 605311 现有的�示��，�需�新分支。
+
+### 方案代际为 null
+
+`requirementIdentities[TRANSFER].dispatchPlanGeneration` 在该需求还没有已定稿行�或已定稿行没有代际时为 null。这时详情照常返回，�是�能按「已定稿方案��需求级确认。
+
+### �读判�
+
+`dispatchReadOnly` �按「行程已结��判定，与派车行是�全部完结无关；�行�读看 `dailyVehiclePlan[].readOnly`，已完结行为 `true`�原因「派�已完结�。
+
+## 六.6�修改��对比
+
+### 字段级对比
+
+�一张纯接�机订�实测：
+
+| 字段 | 改�（fleet `267ab6906`） | 改�（fleet `0bae84b59`） |
+|------|------|------|
+| `pickupDropoffGate.arrivalRequiredDates` | `["2027-08-03"]`（订�出�日） | `["2027-08-30","2027-09-05"]`（TRANSFER 需求的接机�务日） |
+| `pickupDropoffGate.departureRequiredDates` | `["2027-08-09"]`（订�返回日） | `["2027-08-09"]` |
+| `dailyVehiclePlan` | 0 行 | 7 行（4 行已完结 + 09-05 三行已派） |
+| `suggestedVehicleCount` / `actualVehicleCount` | 0 / 0 | 1 / 3 |
+| `progressSteps` 状� | 进行中 / 待处� / 待处� / 待处� | 已完� / 已完� / 进行中 / 待处� |
+| `requirementIdentities[TRANSFER].dispatchPlanGeneration` | null | `362573468547551232` |
+| 顶层 `requirementId` | null | null（��） |
+
+�机�求日改�改��好相�（订�返回日刚好也是 TRANSFER 需求的�机日），区分改�改�的是接机�求日。
+
+---
+
+## 六.7�影�评估
+
+| 维度 | 评估 |
+|---|---|
+| 接�结构 | 无�化，�新增��删除字段 |
+| 纯接�机订� | 详情字段从空值 / 0 / 订�日期兜底�为按 TRANSFER 需求�值；�能新出现 605311 |
+| TRAVEL 订��TRAVEL 与 TRANSFER 并存订� | 无�化 |
+| 看�列表 | 无�化 |
+| 数�库 | 无 DDL�无写入 |
+
+## 七��影�范围
+
+- 看�列表�派车 / 改派 / 接�机�置 / 需求级确认等写接�：未改。
+- TRAVEL 订��TRAVEL 与 TRANSFER 并存的订�：�值��。
+- �应结构：没有新增或删除字段。
+
+---
+
+## 八�测试环境已验�
+
+**环境**：TEST，hl-fleet-service `0bae84b59`（2026-09-27 20:29:52 部署，21:12 �核未�），hl-gateway `71def6dc5`，测试专用车务账�。
+
+1. **�一订�改�改�对照**（第六节）：部署�在 fleet `267ab6906` 上�详情，接机�求日为订�出�日��日方案 0 行�车数 0/0；部署��一订�接机�求日为 TRANSFER �务日��日方案 7 行�车数 1/3，`requirementIdentities[TRANSFER]` 带方案代际。
+2. **接�机�置写�与详情门�一致**：�建一张�有�机方�的纯接�机订�，接�机�置接��应里的门�与��看�详情返回的门��字段相�（`arrivalRequiredDates=[]`�`departureRequiredDates=["2027-10-19"]`�`satisfied=true`）；�有�机方�时接机�求日为空，�会拿订�出�日硬凑。
+3. **拿详情里的身份�需求级确认**：用�一订�详情里 `requirementIdentities[TRANSFER]` 的需求 ID�版本�指纹�代际调 `POST /admin/fleet/assignments/requirements/{requirementId}/confirm` �功（`confirmed=true`），确认���详情，`progressSteps` 四步�为已完�。
+4. **列表与详情一致**：�一订�在看�列表（`GET /admin/fleet/board/orders`）中的派车状��车辆�需求身份与详情一致。
+5. **�测**：看�详情新增 7 �纯接�机订�用例（�全部已完结�旧版在途行�平移�绑行��一需求多代 605311��置处�中�顶层身份为 null），�并�在 dev-v3 上�跑 234/0 通过。
+
+---
+
+## ��相关历� PR
+
+- PR [#8451](https://git.1814.love/wx/HL/pulls/8451)（#8429）：接�机最终方案�布三写�统一判�，本�实测纯接�机订�详情里的门�与它的接�机�置写��应�字段一致。
+
+## ��相关文档
+
+- **Issue**: [#8430](https://git.1814.love/wx/HL/issues/8430)
+- **PR**: [#8452](https://git.1814.love/wx/HL/pulls/8452)
+- **��**: [#7990](https://git.1814.love/wx/HL/issues/7990)（`requirementIdentities` 与 605311 的��）�[#8429](https://git.1814.love/wx/HL/issues/8429)（接�机最终方案�布判�）
+
+## 关� / �系人
+
+- **�端负责人**: @wx