From 07dbd2b5950ec56e44c024e4993184344338bb21 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Sun, 19 Jul 2026 02:20:37 +0800
Subject: [PATCH] =?UTF-8?q?docs(api):=20=E8=A1=A5=E5=85=85=20#4938=20?=
 =?UTF-8?q?=E8=BD=A6=E5=8A=A1=E5=9F=BA=E7=BA=BF=E5=B7=AE=E5=BC=82=E5=A5=91?=
 =?UTF-8?q?=E7=BA=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...œ€ç»ˆç¡®è®¤è®¢å�•è°ƒæ•´åŸºçº¿å·®å¼‚-修改接å�£-管ç�†å�Žå�°.md | 510 ++++++++++++++++++
 1 file changed, 510 insertions(+)
 create mode 100644 changelogs-v2/2026-07/62_4938_车务最终确认订�调整基线差异-修改接�-管���.md

diff --git a/changelogs-v2/2026-07/62_4938_车务最终确认订�调整基线差异-修改接�-管���.md b/changelogs-v2/2026-07/62_4938_车务最终确认订�调整基线差异-修改接�-管���.md
new file mode 100644
index 0000000..c85c68d
--- /dev/null
+++ b/changelogs-v2/2026-07/62_4938_车务最终确认订�调整基线差异-修改接�-管���.md
@@ -0,0 +1,510 @@
+# �#4938 �端对接·管���】车务创建�修改与最终确认返回订�调整基线差异
+
+> Issue: [wx/HL#4938](https://git.1814.love:8443/wx/HL/issues/4938)
+>
+> PR: [wx/HL#5065](https://git.1814.love:8443/wx/HL/pulls/5065)
+>
+> �务: `hl-fleet-service`
+>
+> 日期: 2026-07-18
+>
+> 影�范围: 车务直接派车�直接改派�`holding → assigned` 最终确认，以�订�调整�的日期�人数�车辆容�差异处�
+>
+> 状�: �端已�并并部署测试环境；待管���按本文完�页��调
+
+## 一��端对接结论
+
+以下三个既有管���接�现在共用业务� `605041` 返回结构化�日差异：
+
+| �作 | 接� | 触� 605041 的�件 |
+|---|---|---|
+| 创建派� | `POST /admin/fleet/assignments` | `holdMode=0` 直接派车时最终基线�一致 |
+| 修改派� | `POST /admin/fleet/assignments/{assignmentId}/change` | `holdMode=0` 直接改派时最终基线�一致 |
+| 最终确认 | `POST /admin/fleet/assignments/{assignmentId}/confirm` | 订��需求�行程��日派��人数或容�基线�一致 |
+
+�端必须�守以下判断：
+
+1. 三个接�的 `605041` 当��返回 HTTP 200，但统一�应体为 `code=605041`�`success=false`，�能�判断 HTTP 状�。
+2. `605041` 的 `data` �为空：
+   - create 返回 `AssignmentWriteRespVO`，�� `data.dailyDifferences` �读；
+   - change 返回 `ChangeAssignmentRespVO`，�� `data.dailyDifferences` �读；
+   - confirm 返回 `ConfirmRespVO`，�� `data.confirmed=false` 和 `data.dailyDifferences` �读。
+3. `605041` �会�交派��其关�业务状�写入：
+   - create �会新增或激活派�；
+   - change �会�消旧派�，也�会生��用的新派车版本；
+   - confirm �会推进派�状�或确认时间；
+   - 三者都�会触�车辆/�机�用��险�对账或订�派定结果�化。
+   - change �会按既有设计在独立事务�留一� `CHANGE_FAILED` �作审计；它�是有效派�版本，也�表示业务写入�功。
+4. 收到 `605041` ����作�页�状�，展示�日差异，并�新拉�最新订�和车务详情。
+5. 所有派��车辆槽��派车组�订��车辆和�机雪花 ID �按 JSON String ��和读�，�止转为 JavaScript `Number`。金�字段也按 String 读�。
+
+## 二�605041 公共�应契约
+
+### 2.1 统一�应外层
+
+```json
+{
+  "code": 605041,
+  "message": "订�行程或用车派�已�化，请按�日差异处���试",
+  "data": {
+    "dailyDifferences": [
+      {
+        "serviceDate": "2026-07-22",
+        "differenceType": "CAPACITY_INSUFFICIENT",
+        "assignmentId": null,
+        "assignmentSlotId": null,
+        "passengerCount": 8,
+        "passengerCapacity": 5,
+        "capacityGap": 3,
+        "message": "车辆载客��足，已按�车�机�一座计算"
+      }
+    ]
+  },
+  "traceId": "7db459fd-0b8e-4f29-9c46-4938f09a001",
+  "success": false
+}
+```
+
+注�：
+
+- `data` 的完整类型�决于调用的是 create�change 还是 confirm，�能跨接��用�功�应模型。
+- 除本文件明确��的失败字段外，其余�功�字段在 `605041` 时为空，�端�得用它们推断写入结果。
+- `traceId` 用于�馈和日志定�，��与业务判断。
+
+### 2.2 `dailyDifferences[]`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `serviceDate` | String/null | �生差异的�务日，格� `yyyy-MM-dd`；无法定�到�日时为空 |
+| `differenceType` | String | 差异类型，�值�下表 |
+| `assignmentId` | String/null | �定�到具体派�时返回；仅用于定�差异，�代表本次写入�功 |
+| `assignmentSlotId` | String/null | �定�到稳定车辆槽�时返回 |
+| `passengerCount` | Integer/null | 当�比对使用的乘客人数，���机 |
+| `passengerCapacity` | Integer/null | 当日车辆�计�载客人数，�辆车已扣除�机一座 |
+| `capacityGap` | Integer/null | 缺少座�数，等于 `passengerCount - passengerCapacity` |
+| `message` | String | �端生�的差异说明，�直接辅助展示 |
+
+差异类型：
+
+| `differenceType` | �义 |
+|---|---|
+| `REQUIREMENT_VERSION_MISMATCH` | 当�生效用车需求已�化，或订�/需求已��继续派� |
+| `ORDER_DATE_MISMATCH` | 订�当�日期与用车需求冻结日期�一致 |
+| `ITINERARY_DATE_MISMATCH` | �日行程日期与用车需求冻结日期�一致，或缺少�日行程 |
+| `ASSIGNMENT_DATE_MISSING` | ��务日缺少有效派�或车辆槽� |
+| `ASSIGNMENT_DATE_EXTRA` | 派��包�已�属于当�需求的�务日 |
+| `HEADCOUNT_BASELINE_MISMATCH` | 订�当�人数�需求冻结人数或派�人数快照�一致 |
+| `CAPACITY_INSUFFICIENT` | 当日所有车辆�计载客��足 |
+
+`dailyDifferences` �能�时包�多�类型�多��务日记录。�端应�历数组展示，�得��第一�，也�得自行�算人数或车辆容�。
+
+## 三�创建派� create
+
+### 3.1 请求
+
+```http
+POST /admin/fleet/assignments
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+```
+
+```json
+{
+  "orderId": "2078001000000000101",
+  "orderNo": "26-0719",
+  "requirementId": "2078001000000000201",
+  "fleetItemIndex": 1,
+  "vehicleId": "2078001000000000301",
+  "driverId": "2078001000000000401",
+  "startDate": "2026-07-21",
+  "endDate": "2026-07-23",
+  "pickupAt": "海拉尔",
+  "dropoffAt": "满洲里",
+  "headcount": 8,
+  "protocolPrice": "1300.00",
+  "holdMode": 0,
+  "fromEntry": "from-board",
+  "skipCityJunctionException": false,
+  "strictSeats": true,
+  "confirmCrossResident": false,
+  "requestId": "fleet-create-4938-20260719-001"
+}
+```
+
+`605041` �适用于 `holdMode=0`。原有 `holdMode=1` 排车�定�程�执行本次最终基线门�。
+
+### 3.2 holdMode=0 �功�应
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "id": "2078001000000000501",
+    "assignmentGroupId": "2078001000000000601",
+    "assignmentSlotId": "2078001000000000701",
+    "assignmentStatus": "assigned",
+    "stageCode": "assigned",
+    "stageLabel": "已派车",
+    "currentStep": 4,
+    "skippedStepCodes": [
+      "DRIVER_CONFIRMATION",
+      "DRIVER_CONFIRMATION_EVIDENCE"
+    ],
+    "protocolPrice": "1300.00",
+    "holdSentAt": null,
+    "confirmedAt": "2026-07-19 14:20:00",
+    "sideEffects": {
+      "vehicleStatusUpdated": "busy",
+      "driverStatusUpdated": "busy",
+      "reconPrepRowsCreated": 0,
+      "reconPrepMarkedCanceled": null
+    },
+    "dailyDifferences": null
+  },
+  "traceId": "7db459fd-0b8e-4f29-9c46-4938c200001",
+  "success": true
+}
+```
+
+仅在 `code=200` 时把新派�加入页�；`id`�`assignmentGroupId`�`assignmentSlotId` �按 String �存。
+
+### 3.3 605041 失败�应
+
+```json
+{
+  "code": 605041,
+  "message": "订�行程或用车派�已�化，请按�日差异处���试",
+  "data": {
+    "id": null,
+    "assignmentGroupId": null,
+    "assignmentSlotId": null,
+    "assignmentStatus": null,
+    "stageCode": null,
+    "stageLabel": null,
+    "currentStep": null,
+    "skippedStepCodes": null,
+    "protocolPrice": null,
+    "holdSentAt": null,
+    "confirmedAt": null,
+    "sideEffects": null,
+    "dailyDifferences": [
+      {
+        "serviceDate": "2026-07-22",
+        "differenceType": "CAPACITY_INSUFFICIENT",
+        "assignmentId": null,
+        "assignmentSlotId": null,
+        "passengerCount": 8,
+        "passengerCapacity": 5,
+        "capacityGap": 3,
+        "message": "车辆载客��足，已按�车�机�一座计算"
+      }
+    ]
+  },
+  "traceId": "7db459fd-0b8e-4f29-9c46-4938c605041",
+  "success": false
+}
+```
+
+此时�得把临时�应内容加入派�列表，�得本地�用车辆/�机；刷新��以�务端最新详情为准。
+
+## 四�修改派� change
+
+### 4.1 请求
+
+```http
+POST /admin/fleet/assignments/2078001000000000501/change
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+```
+
+```json
+{
+  "effectiveDate": "2026-07-22",
+  "newVehicleId": "2078001000000000302",
+  "newDriverId": "2078001000000000402",
+  "holdMode": 0,
+  "protocolPrice": "1688.00",
+  "confirmCrossResident": false,
+  "reason": "订�调整�更�车辆和�机",
+  "requestId": "fleet-change-4938-20260719-001"
+}
+```
+
+`newVehicleId`�`newDriverId` 至少传一个。`605041` �适用于 `holdMode=0`；`holdMode=1` �按排车待�机确认�程处�。
+
+### 4.2 holdMode=0 �功�应
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "assignmentId": "2078001000000000502",
+    "assignmentSlotId": "2078001000000000701",
+    "previousAssignmentGroupId": "2078001000000000601",
+    "newAssignmentGroupId": "2078001000000000602",
+    "assignmentStatus": "assigned",
+    "effectiveDate": "2026-07-22",
+    "affectedDays": 2,
+    "protocolPrice": "1688.00",
+    "otherVehicleCount": 1,
+    "warningCode": "ORDER_HAS_OTHER_VEHICLES",
+    "warningMessage": "该订��有1个车辆槽�，当�仅修改本车辆，请核对其它车辆安排",
+    "otherVehicles": [
+      {
+        "assignmentSlotId": "2078001000000000702",
+        "vehiclePlate": "è’™B-66666",
+        "driverName": "�师傅",
+        "startDate": "2026-07-21",
+        "endDate": "2026-07-23"
+      }
+    ],
+    "dailyDifferences": null
+  },
+  "traceId": "7db459fd-0b8e-4f29-9c46-4938a200001",
+  "success": true
+}
+```
+
+change �功�应没有 `confirmed` 和 `sideEffects` 字段。�有 `code=200` 时�能用新派车组替�页�中的旧版本；`warningCode=ORDER_HAS_OTHER_VEHICLES` 时继续�留既有强�示。
+
+### 4.3 605041 失败�应
+
+```json
+{
+  "code": 605041,
+  "message": "订�行程或用车派�已�化，请按�日差异处���试",
+  "data": {
+    "assignmentId": null,
+    "assignmentSlotId": null,
+    "previousAssignmentGroupId": null,
+    "newAssignmentGroupId": null,
+    "assignmentStatus": null,
+    "effectiveDate": null,
+    "affectedDays": null,
+    "protocolPrice": null,
+    "otherVehicleCount": null,
+    "warningCode": null,
+    "warningMessage": null,
+    "otherVehicles": null,
+    "dailyDifferences": [
+      {
+        "serviceDate": null,
+        "differenceType": "HEADCOUNT_BASELINE_MISMATCH",
+        "assignmentId": null,
+        "assignmentSlotId": null,
+        "passengerCount": 8,
+        "passengerCapacity": null,
+        "capacityGap": null,
+        "message": "订�当�人数与用车需求冻结人数�一致"
+      },
+      {
+        "serviceDate": "2026-07-22",
+        "differenceType": "CAPACITY_INSUFFICIENT",
+        "assignmentId": null,
+        "assignmentSlotId": null,
+        "passengerCount": 8,
+        "passengerCapacity": 5,
+        "capacityGap": 3,
+        "message": "车辆载客��足，已按�车�机�一座计算"
+      }
+    ]
+  },
+  "traceId": "7db459fd-0b8e-4f29-9c46-4938a605041",
+  "success": false
+}
+```
+
+此时旧派�和原派车组�是有效业务状�。�端�能新增一� `CHANGE_FAILED` �作审计，但�会生��用的新派车版本。�得用 `dailyDifferences[].assignmentId` 替�页�主键，也�得本地切�车辆��机或状�。
+
+## 五�最终确认 confirm
+
+### 5.1 请求
+
+```http
+POST /admin/fleet/assignments/2078001000000000501/confirm
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+```
+
+```json
+{
+  "requestId": "fleet-final-confirm-4938-20260719-001"
+}
+```
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|---|---|---|---|---|---|
+| `assignmentId` | Path | String | 是 | 有效派� ID | 当�派车组中的任一派� ID |
+| `requestId` | Body | String | 是 | �空，最长 64 | 最终确认幂等标识 |
+
+### 5.2 �功�应
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "confirmed": true,
+    "assignmentStatus": "assigned",
+    "stageCode": "assigned",
+    "stageLabel": "已派车",
+    "currentStep": 4,
+    "assignmentGroupId": "2078001000000000601",
+    "confirmedAt": "2026-07-19 14:30:00",
+    "itineraryUrl": "https://h5.example.com/#/itinerary/<signed-token>",
+    "sideEffects": {
+      "vehicleStatusUpdated": "busy",
+      "driverStatusUpdated": "busy",
+      "reconPrepRowsCreated": 0,
+      "reconPrepMarkedCanceled": null
+    },
+    "dailyDifferences": null
+  },
+  "traceId": "7db459fd-0b8e-4f29-9c46-4938f200001",
+  "success": true
+}
+```
+
+`itineraryUrl` 签��置��用时�许为空，�影�确认�功。�端�有在 `code=200 && data.confirmed===true` 时展示最终确认�功，并刷新派�详情�看�列表和汇总。
+
+### 5.3 日期�人数与容��时存在差异
+
+```json
+{
+  "code": 605041,
+  "message": "订�行程或用车派�已�化，请按�日差异处���试",
+  "data": {
+    "confirmed": false,
+    "assignmentStatus": null,
+    "stageCode": null,
+    "stageLabel": null,
+    "currentStep": null,
+    "assignmentGroupId": null,
+    "confirmedAt": null,
+    "itineraryUrl": null,
+    "sideEffects": null,
+    "dailyDifferences": [
+      {
+        "serviceDate": "2026-07-21",
+        "differenceType": "ORDER_DATE_MISMATCH",
+        "assignmentId": null,
+        "assignmentSlotId": null,
+        "passengerCount": null,
+        "passengerCapacity": null,
+        "capacityGap": null,
+        "message": "订�当�日期与用车需求冻结日期�一致"
+      },
+      {
+        "serviceDate": null,
+        "differenceType": "HEADCOUNT_BASELINE_MISMATCH",
+        "assignmentId": null,
+        "assignmentSlotId": null,
+        "passengerCount": 8,
+        "passengerCapacity": null,
+        "capacityGap": null,
+        "message": "订�当�人数与用车需求冻结人数�一致"
+      },
+      {
+        "serviceDate": "2026-07-22",
+        "differenceType": "CAPACITY_INSUFFICIENT",
+        "assignmentId": null,
+        "assignmentSlotId": null,
+        "passengerCount": 8,
+        "passengerCapacity": 5,
+        "capacityGap": 3,
+        "message": "车辆载客��足，已按�车�机�一座计算"
+      }
+    ]
+  },
+  "traceId": "7db459fd-0b8e-4f29-9c46-4938f605041",
+  "success": false
+}
+```
+
+### 5.4 缺少�日车辆槽�
+
+```json
+{
+  "code": 605041,
+  "message": "订�行程或用车派�已�化，请按�日差异处���试",
+  "data": {
+    "confirmed": false,
+    "assignmentStatus": null,
+    "stageCode": null,
+    "stageLabel": null,
+    "currentStep": null,
+    "assignmentGroupId": null,
+    "confirmedAt": null,
+    "itineraryUrl": null,
+    "sideEffects": null,
+    "dailyDifferences": [
+      {
+        "serviceDate": "2026-07-23",
+        "differenceType": "ASSIGNMENT_DATE_MISSING",
+        "assignmentId": null,
+        "assignmentSlotId": null,
+        "passengerCount": null,
+        "passengerCapacity": null,
+        "capacityGap": null,
+        "message": "该�务日缺少第2个车辆槽�派�"
+      }
+    ]
+  },
+  "traceId": "7db459fd-0b8e-4f29-9c46-4938f605042",
+  "success": false
+}
+```
+
+## 六��端统一处�顺�
+
+1. 先判断业务 `code`，�读�端点自己的 `data`：
+   - `code=200`：按对应�功模型处�；
+   - `code=605041`：按对应失败模型读� `dailyDifferences`；
+   - 其他业务�：继续走既有错误处�。
+2. `605041` 时���观更新：
+   - create �新增本地派�；
+   - change �替�旧派�；
+   - confirm �改为 `assigned` 或“已确认�。
+3. 展示顶层 `message`，并按 `dailyDifferences` 列出�务日�差异类型�人数�容�和缺�；字段为空时��对应展示项。
+4. �新请求最新订�和车务详情，��继续使用�作�缓存。
+5. 用户修正订�日期�行程�人数或派��，生�新的 `requestId` ��交新动作；仅在�一次动作网络结果�确定时�用原 `requestId`。
+
+## 七�其他直接错误分支
+
+| 业务� | 常�场景 | �端处� |
+|---|---|---|
+| `605009` | 派��存在 | 刷新详情和看�，�止�作旧记录 |
+| `605020` | 当�状���许�作 | 刷新最新生命周期与�作能力 |
+| `605025` | 最终确认�缺少�机确认或有效凭� | 引导先完��机确认与凭�登记 |
+| `605001` / `605003` | 车辆或�机档期冲� | 展示�端错误并�新选车/�机 |
+| `605036` | 跨常驻车未显�确认 | 二次�示��带 `confirmCrossResident=true` �试 |
+| `605041` | 订��需求�行程��日派��人数或容�基线�一致 | 使用当�端点的 `data.dailyDifferences` 展示并处� |
+
+请求字段为空�格��正确或超过长度�制时走统一�数校验错误，�端应在�请求�完��样约�。
+
+## 八��影�范围
+
+- �新增管���接�，三个接�的请求字段结构����。
+- `holdMode=1` 的排车�定��机确认与凭�登记�程����。
+- �改��消��机拒接�驳回需求�撤销�消和��完结的�端调用契约。
+- ��求�端计算订�人数��日�务日期或车辆载客�，这些�由�端��校验并返回差异。
+- 本文件��述管���直接消费的 HTTP 契约，�包��务间调用或�布实现细节。
+
+## ��验收状�与待补��
+
+已完�：
+
+- 当� worktree 中 create�change�confirm Controller 的 `605041` 强类型 `data` ��核对。
+- `AssignmentWriteRespVO`�`ChangeAssignmentRespVO`�`ConfirmRespVO` 与 `dailyDifferences` 字段��核对。
+- 三�失败路径��交派��其关�业务状��化的��顺�核对。
+- �端 PR #5065 已�并至 `dev-v3`；Fleet �实例 `8087/8187` 已完�滚动部署并通过�康/Nacos 验�。
+- 最终��指纹下 Fleet `verify` 1909/1909�Order-v3 �影�回归 438/438�User Quartz 桥接 5/5 �通过。
+
+�端�调�需补充：
+
+- 三个接�在测试环境 OpenAPI 中的请求/�应模型截图或导出差异。
+- �网关分别�得 create�change�confirm 的�功�应和 `605041` 真实�应，记录 HTTP 状��业务��`traceId` 与完整 `data`。
+- 对 `605041` ���测试业务数�对照，确认派�版本/状��车辆�机�用��险�对账和订�派定结果未�生�化。
+- 管���页��调��：差异列表展示�空字段处��刷新行为��止�观更新，以�修正��新�交�功。
-- 
2.43.0