docs(changelog): 已取消派单显示派车快照+按未用天行级释放(#6114)

changelogs-v2/2026-08/20_6114_已取消派单显示派车快照与按未用天行级释放-修改接口-管理后台.md

@@ -0,0 +1,101 @@
+---
+schema: "hl-changelog/v2"
+ticket: "6114"
+title: "已取消派单显示当时派车快照+按未用天行级释放占用"
+consumer: "admin"
+author: "wx"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-08-20"
+status_note: "后端完成：PR #6115 已合并 dev-v3（squash fc3d40c92）并部署 TEST（hl-fleet-service 双实例 8087/8187，2026-08-20 18:09 重启）。车务看板已取消行新增 4 个取消时派车快照字段（可选只读，正常行为 null），清除占用接口新增可选 serviceDates 行级释放。前端据此在已取消行回显释放对象 + 按未用天逐行释放。"
+updated_at: "2026-08-20"
+base: "dev-v3"
+generated: "2026-08-20T18:15:00+08:00"
+---
+
+# 已取消派单显示当时派车快照+按未用天行级释放占用（#6114）
+
+## 背景
+
+订单中止行程后，车务看板里被勾选的「未用天」对应派单行被置为已取消，但当前派车信息（车牌/车型/司机/电话）按 #5828 读侧清空成 null，导致前端无法展示「这辆车/这位司机」是被谁占用、也无法让运营对着具体行去释放。本变更：(1) 已取消行**额外回显取消当时的派车快照**（只读展示用，当前派车字段维持 null 不变）；(2) 清除占用接口支持**按服务日子集行级释放**（对应中止时勾选的未用天）。纯新增，不影响既有任何字段与整单级释放行为。
+
+## 变更接口
+
+| 接口 | 变更 |
+| --- | --- |
+| `GET /admin/fleet/board/orders`（车务看板订单列表） | **响应新增字段**（均在派单行 slot 上，可选只读，正常/未取消行为 null）：`cancelledVehiclePlate`（String，取消时车牌快照，仅已取消行有值）、`cancelledVehicleModel`（String，取消时车型快照）、`cancelledDriverName`（String，取消时司机姓名快照）、`cancelledDriverPhone`（String，取消时司机手机号**脱敏**快照，形如 `135****5005`）。**注意**：既有 `vehiclePlate/vehicleModel/driverName/driverPhone` 在已取消行**仍为 null**（#5828 读侧清空逻辑不变），请改用 `cancelled*` 快照字段展示释放对象。 |
+| `POST /admin/fleet/assignments/clear-cancelled-occupancy`（清除已取消派单占用） | **请求新增可选字段** `serviceDates`（`LocalDate[]`，形如 `["2026-08-21","2026-08-22"]`）：传值=只释放服务日落在该子集内的已取消派单（行级/按未用天释放）；**不传或传空数组=维持原整单级释放全部**（向后兼容）。响应结构不变。 |
+
+## 响应示例
+
+`GET /admin/fleet/board/orders` 已取消行（仅列本次新增字段，其余字段省略）：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "list": [
+      {
+        "orderNo": "HL20260819132123689",
+        "fleetItems": [
+          {
+            "slots": [
+              {
+                "assignmentId": "2089945846031257601",
+                "assignmentStatus": "CANCELED",
+                "lifecycleStageLabel": "已取消",
+                "vehiclePlate": null,
+                "vehicleModel": null,
+                "driverName": null,
+                "driverPhone": null,
+                "cancelledVehiclePlate": "蒙A-K1999",
+                "cancelledVehicleModel": "丰田考斯特",
+                "cancelledDriverName": "乌云毕力格",
+                "cancelledDriverPhone": "135****5005"
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## 请求示例（行级释放）
+
+`POST /admin/fleet/assignments/clear-cancelled-occupancy` —— 只释放未用天 `2026-08-21`、`2026-08-22` 的已取消派单占用：
+
+```json
+{
+  "orderId": "2089945804415315969",
+  "requestId": "clear-cancel-20260820-001",
+  "serviceDates": ["2026-08-21", "2026-08-22"]
+}
+```
+
+整单级释放（原有用法，`serviceDates` 不传）：
+
+```json
+{
+  "orderId": "2089945804415315969",
+  "requestId": "clear-cancel-20260820-002"
+}
+```
+
+## 前端改造点
+
+1. **已取消行回显**：派单行 `assignmentStatus="CANCELED"`（或 `lifecycleStageCode` 已取消）时，车牌/车型/司机/电话改读 `cancelledVehiclePlate/cancelledVehicleModel/cancelledDriverName/cancelledDriverPhone`（为 null 再降级为「—」），不要再读 `vehiclePlate` 等当前字段（恒为 null）。
+2. **行级释放按钮**：未用天对应的已取消车行上加「释放占用」入口，调 `POST /admin/fleet/assignments/clear-cancelled-occupancy`，把该行覆盖的服务日放入 `serviceDates`（单日行传 1 个日期即可）。
+3. 释放成功后建议刷新看板占用展示。
+
+## 验证证据
+
+- 单测：`AssignmentServiceClearCancelledOccupancyTest` 9/9 绿（含 #6114 新增 `clearCancelledOccupancy_withServiceDates_onlyReleasesMatchingDays` / `..._noMatch_returnsZero`，行级只释放命中日、无命中幂等返回 0）。
+- 网关实测（TEST，`GET /admin/fleet/board/orders?keyword=26-9250`）：已取消行 `vehiclePlate/vehicleModel/driverName/driverPhone` 均为 null（#5828 不变），同时新增 `cancelledVehiclePlate="蒙A-K1999"`、`cancelledVehicleModel="丰田考斯特"`、`cancelledDriverName="乌云毕力格"`、`cancelledDriverPhone="135****5005"`（脱敏），快照正确回显。
+- 部署：hl-fleet-service 双实例 8087/8187 于 2026-08-20 18:09 滚动重启生效（jar 含 `fc3d40c92` 字段，javap 已核）。