From a43cb158b867aba615ba9d64e1956a93c39dfe1a Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Mon, 28 Sep 2026 13:11:34 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#8455=20=E5=B9=B6=E5=AD=98?=
 =?UTF-8?q?=E8=AE=A2=E5=8D=95=E6=8E=A5=E9=80=81=E6=9C=BA=E7=9C=8B=E6=9D=BF?=
 =?UTF-8?q?=E9=97=A8=E7=A6=81=E4=B8=8E=E6=94=B9=E6=9C=9F=E6=AE=8B=E7=95=99?=
 =?UTF-8?q?=E6=8C=89=E9=9C=80=E6=B1=82=E8=87=AA=E8=BA=AB=E7=AA=97=E5=8F=A3?=
 =?UTF-8?q?=E5=88=A4=E5=AE=9A=EF=BC=88PR=20#8470=EF=BC=89?=
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 | 356 ++++++++++++++++++
 1 file changed, 356 insertions(+)
 create mode 100644 changelogs-v2/2026-09/28_8455_并存订�接�机看�门�与改期残留按需求自身窗�判定-修改接�-管���.md

diff --git a/changelogs-v2/2026-09/28_8455_并存订�接�机看�门�与改期残留按需求自身窗�判定-修改接�-管���.md b/changelogs-v2/2026-09/28_8455_并存订�接�机看�门�与改期残留按需求自身窗�判定-修改接�-管���.md
new file mode 100644
index 00000000..a225d829
--- /dev/null
+++ b/changelogs-v2/2026-09/28_8455_并存订�接�机看�门�与改期残留按需求自身窗�判定-修改接�-管���.md
@@ -0,0 +1,356 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8455"
+title: "并存订�接�机看�门�与改期残留按需求自身窗�判定"
+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: ""
+updated_at: "2026-09-28"
+base: "dev-v3"
+---
+
+# fleet: 并存订�接�机看�门�与改期残留按需求自身窗�判定
+
+**�务**: hl-fleet-service
+**PR**: #8470（已�入 `dev-v3`，squash `82444e3f0`）
+**Issue**: #8455
+**日期**: 2026-09-28
+**影�范围**: 管���车务看�订�详情 `GET /admin/fleet/board/orders/{orderId}`
+
+---
+
+## ⚠� 关键�化
+
+**�影�「并存订��**：�一订��时有一�有效的行程用车需求（TRAVEL）和一�有效的接�机需求（TRANSFER），且订�详情��到（`relatedDetailReady=true`）。字段��类型��应结构都��，�的是下�几个字段的�值�径。
+
+- `dailyVehiclePlan[].rescheduleResidue` 与 `vehicleSlots[].rescheduleResidue`：行程用车与接�机两�需求并存的订�中，属于接�机需求的派车行改为按接�机需求自身的�务日判断是�越窗，��按行程用车的日期窗判断，因此�法接�车��被误标「改期残留/待清��；接�机需求没有任何�务日期时，这些行�判残留。其余派车行和�并存订�的判定��。
+- `pickupDropoffGate`（接�机门�）与�日 `dailyVehiclePlan[].pickupRequired / dropoffRequired`：改为按 TRANSFER 需求自己的�务日窗��以 TRANSFER 需求�下的派车行为��计算，与写侧�布门���径。改�按行程用车窗�算：接机日早于行程首日时被窗�滤掉�兜底�行程首日，看�报一个写侧�存在的「缺接机�。
+- `requirementIdentities[].dispatchPlanGeneration` 与 `driverConfirmationSummary.dispatchPlanGeneration`：已完结（COMPLETED）的派车行���与代际判定。行程中途�排�，旧代已完结行��把代际挤� null。
+- `progressSteps`：当�需求存在过期定稿方案�`activeAssignments` 已回拨�待派车时，进度�也按待派车计算，��显示「排车已完��。
+
+---
+
+## 一�背景
+
+核心订�和团期订�都会�时有行程用车和接�机两�需求，接�机日�以早于行程首日（客人��一天到）。看�详情此�用行程用车的日期窗判接�机，出现两类误报：
+
+1. 已派好的接机车被报「缺接机�，进度��在接�机一步；
+2. 行程窗外的接机派车行被标「改期残留/待清�，��消释放�用�，车务照��消就会误伤�法派车。
+
+写侧（最终方案�布门�）本�就按接�机需求自身窗�判，两侧�径�一致。本�把读侧改�与写侧��径。
+
+---
+
+## 二��更接�清�
+
+| # | 接� | 方法 | 路径 | �更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 车务看�订�详情 | GET | `/admin/fleet/board/orders/{orderId}` | 修改 | 并存订�的接�机门���日接�标记�改期残留�派车方案代际�进度��值�径�更 |
+
+---
+
+## 三�接�详情
+
+### 1. 车务看�订�详情 `GET /admin/fleet/board/orders/{orderId}`
+
+**VO**: `BoardOrderDetailVO`
+
+#### 使用场景
+
+车务打开看�订�详情，查看接�机门���日派车计划�槽�改期残留徽标�派车方案代际（拼需求级确认的 `expectedPlanGeneration`）与进度�。
+
+#### 入�字段表
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|------|------|------|------|------|------|
+| orderId | Path | Long | 是 | 订�主键 | 看�列表行里的订� ID |
+
+#### 出�字段表
+
+�列�值�径有�化的字段；其余字段与改�一致。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| pickupDropoffGate.arrivalRequiredDates | Array&lt;String(yyyy-MM-dd)&gt; | 需�接机的日期。并存订�按 TRANSFER 需求�务日窗�计算 |
+| pickupDropoffGate.departureRequiredDates | Array&lt;String(yyyy-MM-dd)&gt; | 需��机的日期。并存订�按 TRANSFER 需求�务日窗�计算 |
+| pickupDropoffGate.missingPickupDates | Array&lt;String(yyyy-MM-dd)&gt; | 缺接机的日期。并存订��拿 TRANSFER 需求�下的派车行（�已完结行，用于完结日��）��� |
+| pickupDropoffGate.missingDropoffDates | Array&lt;String(yyyy-MM-dd)&gt; | 缺�机的日期。��行�径�上 |
+| pickupDropoffGate.declared | Boolean | 是�存在任一方�的接�机�求（两个�求日期集�任一�空） |
+| pickupDropoffGate.satisfied | Boolean | 两个缺失集�都为空�为 true |
+| dailyVehiclePlan[].pickupRequired | Boolean | 当天是��求接机。并存订�与顶层门�用�一个 TRANSFER 窗� |
+| dailyVehiclePlan[].dropoffRequired | Boolean | 当天是��求�机。并存订�与顶层门�用�一个 TRANSFER 窗� |
+| dailyVehiclePlan[].rescheduleResidue | Boolean | 是�改期残留旧日期行。并存订�中归 TRANSFER 需求的行按 TRANSFER 需求窗�判，其余行按订�当�有效用车需求窗�判；窗�为空时�判残留 |
+| vehicleSlots[].rescheduleResidue | Boolean | 是�改期残留旧日期槽�，�径�上；已被新需求�代的�留槽��按当�有效用车需求窗�判 |
+| requirementIdentities[].dispatchPlanGeneration | String(Long) | 该需求在途定稿行的唯一派车方案代际；已完结行��与；代际�唯一�未定稿或全部已完结时为 null |
+| driverConfirmationSummary.dispatchPlanGeneration | String(Long) | 整�在途定稿行的唯一派车方案代际；已完结行��与；历�无代际�代际�唯一或全部已完结时为 null |
+| progressSteps[].status | String | 当�需求存在过期定稿方案�且锚点派车行�进入�车�程时，进度按「待派车�计算，与 `activeAssignments[].assignmentStatus` 回拨�的值一致 |
+
+#### 请求示例
+
+```http
+GET /admin/fleet/board/orders/2104416028559835138
+Authorization: Bearer <REDACTED-JWT>
+```
+
+#### �应示例
+
+2026-09-28 测试�实测节选（核心订�夹具，行程用车 2027-11-20 ~ 2027-11-26，接�机：11-19 接机�11-26 �机；��留与本�有关的字段，夹具验收�已�消）：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "requirementIdentities": [
+      {
+        "kind": "TRAVEL",
+        "requirementId": "2104416559248375810",
+        "requirementVersion": 1,
+        "requirementSha256": "46cb40c594edb2704ffc27b41acc3273041e42db3a599aadbef4f9d07e777501",
+        "dispatchPlanGeneration": null
+      },
+      {
+        "kind": "TRANSFER",
+        "requirementId": "2104416585181724674",
+        "requirementVersion": 1,
+        "requirementSha256": "62ab87d408692a438880d1e6e3497563a15e5e5adc081ad6ed9b24d3692d0097",
+        "dispatchPlanGeneration": "362806657824198656"
+      }
+    ],
+    "pickupDropoffGate": {
+      "arrivalRequiredDates": [
+        "2027-11-19"
+      ],
+      "departureRequiredDates": [
+        "2027-11-26"
+      ],
+      "missingPickupDates": [],
+      "missingDropoffDates": [],
+      "declared": true,
+      "satisfied": true
+    },
+    "dailyVehiclePlan": [
+      {
+        "serviceDate": "2027-11-19",
+        "assignmentId": "2104416840996564994",
+        "assignmentStatus": "assigned",
+        "pickupRequired": true,
+        "dropoffRequired": false,
+        "rescheduleResidue": false
+      },
+      {
+        "serviceDate": "2027-11-26",
+        "assignmentId": "2104416841218863105",
+        "assignmentStatus": "assigned",
+        "pickupRequired": false,
+        "dropoffRequired": true,
+        "rescheduleResidue": false
+      }
+    ],
+    "vehicleSlots": [
+      {
+        "assignmentId": "2104416840996564994",
+        "requirementId": "2104416585181724674",
+        "superseded": false,
+        "rescheduleResidue": false
+      },
+      {
+        "assignmentId": "2104416841218863105",
+        "requirementId": "2104416585181724674",
+        "superseded": false,
+        "rescheduleResidue": false
+      }
+    ],
+    "driverConfirmationSummary": {
+      "dispatchPlanGeneration": "362806657824198656"
+    },
+    "progressSteps": [
+      {
+        "step": 1,
+        "code": "ORDER_DETAIL",
+        "status": "DONE",
+        "statusLabel": "已完�"
+      },
+      {
+        "step": 2,
+        "code": "DISPATCH",
+        "status": "DONE",
+        "statusLabel": "已完�"
+      },
+      {
+        "step": 3,
+        "code": "PICKUP_DROPOFF",
+        "status": "DONE",
+        "statusLabel": "已完�"
+      },
+      {
+        "step": 4,
+        "code": "CONFIRM_EXECUTE",
+        "status": "DONE",
+        "statusLabel": "已完�"
+      }
+    ]
+  }
+}
+```
+
+#### 空数� / �级�应
+
+- �并存订�（�有 TRAVEL，或�有 TRANSFER）：�值�径与改�完全相�。
+- 并存订�的 TRANSFER 需求没有�务日期�也没有自身起止日：接�机窗�为空，�回�到行程用车日期或订�起止日。此时 `arrivalRequiredDates`�`departureRequiredDates` 为空数组，`declared=false`，`satisfied=true`，归 TRANSFER 需求的派车行 `rescheduleResidue=false`。写侧�布门�对这� TRANSFER �样给空门�。
+- 订�详情��到（`relatedDetailReady=false`）：�按并存订�处�，门�与�日接�标记按改�的�级�径返回，本�未改动。
+- 派车行全部已完结：`dispatchPlanGeneration` 为 null（没有�确认的在途派车组）。
+
+#### 错误�应
+
+```json
+{
+  "code": 605311,
+  "message": "当�需求存在多个��明派车方案代际，请�系车务核对派车方案��试",
+  "data": null,
+  "success": false
+}
+```
+
+| 错误� | 触��件 |
+|---|---|
+| 401 | 未登录 |
+| 605311 | �一�需求下派车方案代际�唯一，看��猜当�代际，�试无效，须�系车务核对派车方案。本�未改动该错误� |
+
+#### 业务边界
+
+- 并存订�的判定�件：订�详情��到，且�时有有效的 TRAVEL 需求与有效的 TRANSFER 需求。
+- 派车行归属按行上的 `requirementId` 判断：等于 TRANSFER 需求 ID 的行用 TRANSFER 窗�，其余行（� `requirementId` 对�上任何需求的行）用订�当�有效用车需求窗�。
+- 门���行�本订�全部原始派车行中归 TRANSFER 需求的行，包括已完结行；已完结的日期按原规则��，�会被误报缺失。
+- `driverConfirmationSummary.dispatchPlanGeneration` 按整�算：两�需求都有在途定稿行且代际��时为 null；�拼接�机需求的 `expectedPlanGeneration`，请� `requirementIdentities[]` 里 `kind=TRANSFER` 那一项的 `dispatchPlanGeneration`。
+- 进度�回拨�改�应里的计算副本，�改派车行�库状�。
+
+---
+
+## 四�契约约�与正确调用方�
+
+| 场景 | 门�与�日接�标记用的窗� | 门���行 | 改期残留用的窗� |
+|------|-----|-----|-----|
+| 并存订�（TRAVEL + TRANSFER） | TRANSFER 需求�务日 | TRANSFER 需求�下全部原始行 | TRANSFER 行用 TRANSFER 窗�，其余行用当�有效需求窗� |
+| �有 TRAVEL | 与改�相� | 与改�相� | 与改�相� |
+| �有 TRANSFER | 与改�相�（#8430 �径） | 与改�相� | 与改�相� |
+
+- �端展示「缺接机 / 缺�机�请直接用 `pickupDropoffGate.missingPickupDates / missingDropoffDates`，��自己拿行程起止日�算。
+- 「改期残留/待清��徽标直接用 `rescheduleResidue`，��按行程日期自行判断接�机行是�越窗。
+
+---
+
+## 五�数�库行为
+
+无表结构�更，无写库。�改 fleet `BoardOrderService` 组装详情时的内存判定。
+
+---
+
+## 六�边界行为
+
+- �一�应内顶层门�与�日 `pickupRequired / dropoffRequired` 用�一个窗���，二者�会出现「�日说�接机�门�说�需��的矛盾。
+- 过期定稿方案的进度回拨判�与 `activeAssignments` 回拨判�相�（锚点行�进入�车�程）；锚点行�满足时进度按原状�计算。
+
+### ��兼容
+
+�应结构��，无新增�无删除字段。�并存订��值��。
+
+---
+
+## 六.5�枚举 / 数�字典
+
+本��新增��修改枚举。
+
+---
+
+## 六.6�修改��对比
+
+测试��一张并存核心订�（行程用车 2027-11-20 ~ 2027-11-26；接�机 11-19 接机�11-26 �机；两�接�派车行�已派）修�修�实测读数：
+
+| 字段 | 修� | 修� |
+|------|------|------|
+| `pickupDropoffGate.arrivalRequiredDates` | `["2027-11-20"]` | `["2027-11-19"]` |
+| `pickupDropoffGate.missingPickupDates` | `["2027-11-20"]` | `[]` |
+| `pickupDropoffGate.satisfied` | `false` | `true` |
+| `pickupDropoffGate.departureRequiredDates` | `["2027-11-26"]` | `["2027-11-26"]` |
+| `pickupDropoffGate.missingDropoffDates` | `[]` | `[]` |
+| `dailyVehiclePlan[11-19].pickupRequired` | `false` | `true` |
+| `dailyVehiclePlan[11-19].rescheduleResidue` | `true` | `false` |
+| `vehicleSlots[11-19 那一行].rescheduleResidue` | `true` | `false` |
+| `dailyVehiclePlan[11-26].rescheduleResidue` | `false` | `false` |
+| `progressSteps` 中 `PICKUP_DROPOFF` / `CONFIRM_EXECUTE` | `PROCESSING` / `WAITING` | `DONE` / `DONE` |
+
+---
+
+## 六.7�影�评估
+
+- **是�破���兼容**: �，�有�值�径�化。
+- **�端是�必须�步上线**: �。�展示这些字段的页�无需改动。
+- **�端 workaround 清�点**: 如果�端为规�「缺接机�误报或「改期残留�误标加过按行程日期过滤接�机行的逻辑，�以删掉，直接用�端字段。
+
+---
+
+## 七��影�范围
+
+- �并存订�（�有 TRAVEL 或�有 TRANSFER）的全部字段。
+- 看�列表接�。
+- 写侧接�（最终方案�布�需求级确认）逻辑未改；本��让读侧与写侧�径对�。
+
+---
+
+## 八�测试环境已验�
+
+部署：测试� `hl-fleet-service` 两个实例于 2026-09-28 12:19:44 滚到 `dev-v3 d10aada4d`（包�本��并�交 `82444e3f0`），deploy-status 显示�� 0。
+
+### 测试�网关实测（`GET /admin/fleet/board/orders/{orderId}`，测试专用账�与自造夹具）
+
+| 场景 | 检验点 | 结果 |
+|------|--------|------|
+| 并存核心订�，接机日 11-19 早于行程首日 11-20 | `arrivalRequiredDates=["2027-11-19"]`�`missingPickupDates=[]`�`satisfied=true` | ✅ 读数�六.6 |
+| �上 | 11-19 行 `pickupRequired` 由 false � true | ✅ |
+| �上 | 11-19 接机行在 `dailyVehiclePlan[]` 与 `vehicleSlots[]` 的 `rescheduleResidue` 由 true � false；11-26 �机行�� false | ✅ |
+| �上 | 门�满足� `progressSteps` 的接�机与确认执行两步�为 DONE | ✅ |
+
+### �测覆盖（`BoardOrderServiceTest`，修�红�修�绿）
+
+| 场景 | 用例 |
+|------|------|
+| 并存订� TRANSFER 行在行程窗外�在接�机窗内：�判残留 | `queryOrderDetail_coexistingTransferRowOutsideTravelWindow_notRescheduleResidue` |
+| TRANSFER 行�在行程窗内��在接�机窗内：判残留 | `queryOrderDetail_coexistingTransferRowInsideTravelWindowOnly_rescheduleResidueByTransferWindow` |
+| TRANSFER 行两个窗�都�在：�判残留 | `queryOrderDetail_coexistingTransferRowOutsideBothWindows_stillRescheduleResidue` |
+| �有 TRAVEL 的订�：残留判定��（阴性对照） | `queryOrderDetail_travelOnlyOrder_rescheduleResidueUnchanged` |
+| 行程中途�排，旧代已完结�新代在途：两个 `dispatchPlanGeneration` 都给新代 | `queryOrderDetail_travelMidTripReplan_completedOldGenerationExcludedFromGeneration` |
+| 过期定稿方案：`DISPATCH` 为 PROCESSING，`PICKUP_DROPOFF`�`CONFIRM_EXECUTE` 为 WAITING | `queryOrderDetail_staleFinalizedPlan_progressStepsFollowRebasedStatus` |
+
+中途�排与过期定稿两个场景没有在测试�造数，�由�测覆盖。
+
+---
+
+## ��相关文档
+
+- 工� #8455: https://git.1814.love/wx/HL/issues/8455
+- ��工� #8430（纯接�机订�看�详情按 TRANSFER �数）：https://git.1814.love/wx/HL/issues/8430
+- ��工� #7990（接�机需求确认链路）：https://git.1814.love/wx/HL/issues/7990
+
+---
+
+## 关� / �系人
+
+### 链接
+
+- **Issue**: [#8455](https://git.1814.love/wx/HL/issues/8455)
+- **PR**: [#8470](https://git.1814.love/wx/HL/pulls/8470)
+- **Merge commit**: [82444e3f0](https://git.1814.love/wx/HL/commit/82444e3f0)
+
+### �系人
+
+- **�端负责人**: @wx