71aa64896e
一些检查失败了
changelog-filename-gate / validate (push) Failing after 2s
车务看板订单详情抽屉车辆执行段新增整单级「释放车辆/司机占用」按钮,调 clear-cancelled-occupancy 一键清已取消派单脏占用;与逐日软清 #5936 语义不同不混用。 frontend_ref=2ebfddc7。
88 行
4.6 KiB
Markdown
88 行
4.6 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "6107"
|
||
title: "终止行程后已取消派单「释放车辆/司机占用」入口（一键清除占用端点告知）"
|
||
consumer: "admin"
|
||
author: "wx"
|
||
change_type: "新增接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "2ebfddc7"
|
||
target_release: ""
|
||
verified_at: "2026-08-20"
|
||
status_note: "端点 POST /admin/fleet/assignments/clear-cancelled-occupancy 由 #5921（关联 #5913/#5828）交付并部署 TEST，但当初未单独发 changelog，前端不知其存在，导致「终止行程后已取消派单仍占着车/司机、无释放按钮」。本文补告知取值与 UI 挂载点。后端本次无代码变更。"
|
||
updated_at: "2026-08-20"
|
||
base: "dev-v3"
|
||
generated: "2026-08-20T00:00:00+08:00"
|
||
---
|
||
|
||
# 终止行程后已取消派单「释放车辆/司机占用」入口（#6107）
|
||
|
||
## 背景
|
||
|
||
订单**中止行程**后，订单侧已把对应车务派单截断为 `canceled`，看板正确显示「已取消」。
|
||
|
||
但「已取消」只是把派单行冻结，**该行原本锁住的车辆/司机资源占用（脏 busy）不会自动全部归还**——需要车务同事手动触发一次「释放占用」。此前前端不知道后端已有这个释放端点，导致看板详情里看不到任何释放按钮，资源一直被冻结，影响后续派车。
|
||
|
||
**本文一次性告知：释放占用的后端能力早已上线，前端只需补挂一个按钮。**
|
||
|
||
## 变更接口
|
||
|
||
| 接口 | 变更 |
|
||
| --- | --- |
|
||
| `POST /admin/fleet/assignments/clear-cancelled-occupancy` | **已上线，本次补告知**。一键圈定某订单/需求下全部已取消(canceled)派单的车辆/司机，清掉它们的脏占用（合法 busy 不动）。**只清占用，不修改派单任何字段** |
|
||
| `POST /admin/fleet/assignments/{assignmentId}/soft-clear-assignment` | 已上线（#5936）。单条软清备用；本单默认用上面的整单一键清 |
|
||
|
||
## 一、调用方式（clear-cancelled-occupancy）
|
||
|
||
**入参**（body）：
|
||
|
||
```json
|
||
{
|
||
"orderId": "1934567890123456789",
|
||
"requestId": "clear-cancel-20260820-001"
|
||
}
|
||
```
|
||
|
||
- `orderId` 与 `requirementId` **二选一**（都填/都不填返 100001）。车务看板详情页天然有 `orderId`，用它即可。
|
||
- `requestId` **必填**，幂等标识，≤64 字符，前端生成（如 `clear-cancel-` + 时间戳）。
|
||
|
||
**返回**（data）：
|
||
|
||
```json
|
||
{
|
||
"vehicleDriverPairs": 2,
|
||
"intentsWritten": 2,
|
||
"assignmentIds": ["1934567890123456701"]
|
||
}
|
||
```
|
||
|
||
- `assignmentIds` 为本次实际圈到的已取消派单 ID 列表（雪花按字符串返回）。
|
||
- `intentsWritten=0` 表示没有可清的脏占用（幂等安全，可视为成功）。
|
||
|
||
**错误码**：`100001`（orderId 与 requirementId 二选一）/ `605047`（行程已结束）/ `605054`（终止冻结中，稍后重试）/ `605600`（已关账）。
|
||
|
||
## 二、前端动作（本次唯一要改的地方）
|
||
|
||
在**车务看板 → 订单详情抽屉 → 「车辆执行段」列表**补一个入口：
|
||
|
||
1. **可见条件**：`GET /admin/fleet/board/orders/{orderId}` 返回的 `activeAssignments[]` / `vehicleSlots[]` 里存在 `assignmentStatus === "canceled"` 的行，且该行 `assignmentId` 非空时，显示「释放车辆/司机占用」按钮（或文字链）。
|
||
2. **点击**：弹确认框（文案建议「将释放该订单下已取消派单占用的车辆/司机，是否继续？」），确认后调 `clear-cancelled-occupancy`，`orderId` 取当前订单、`requestId` 前端生成。
|
||
3. **成功后**：提示成功并**重新拉取详情**（占用释放是异步 outbox 反算，稍候在矩阵/资源日历可见车、司机恢复 idle）。
|
||
4. **非 canceled 行不展示该入口**；`holding`/`assigned` 仍走既有「清空司机/车辆」(#5936)，语义不同，别混用。
|
||
|
||
## 三、取值字段（详情接口已返回，无需后端改）
|
||
|
||
`GET /admin/fleet/board/orders/{orderId}`（BoardOrderDetailVO）已含：
|
||
- `vehicleSlots[].assignmentStatus` / `assignmentStatusLabel`（canceled = 已取消）
|
||
- `vehicleSlots[].assignmentId`、`assignmentSlotId`、`vehicleId`、`driverId`
|
||
- `activeAssignments[].assignmentStatus` / `assignmentId`
|
||
|
||
## 验证证据
|
||
|
||
- 后端 `ClearCancelledOccupancy` 单测 7 例随 #5921 交付即绿；端点已在 TEST 部署。
|
||
- 全量 API 测试（2026-08-20，232 用例）复核：终止行程后 fleet assignment 正确置 `canceled`，仅缺前端释放按钮——纯前端缺口。
|
||
- 网关（TEST 9443，真 SUPER_ADMIN token）实测本端点：不存在 orderId 幂等返回 `200 {vehicleDriverPairs:0, intentsWritten:0, assignmentIds:[]}`，路由可达、结构符合 RespVO 契约。
|