docs: 车务派单异常桶+处置完成写口+详情已取消行字段+异常留痕 changelog (#6152)

2026-08-22 09:10:44 +00:00
@@ -0,0 +1,72 @@
+---
+schema: "hl-changelog/v2"
+ticket: "6152"
+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-22"
+status_note: "车务派单看板/详情：①已派车后取消的订单不再落「已取消」消失，改进新「异常」桶等人工处置；②详情已取消/异常槽位行补 serviceDate/startDate/endDate 三字段（根治行级释放占用解析服务日失败误拦截）；③操作时间线新增「订单异常」「异常处置完成」系统留痕；④新增处置完成写口 POST /admin/fleet/assignments/resolve-exception。前端需适配异常分面 Tab + 详情异常行操作入口。"
+updated_at: "2026-08-22"
+base: "dev-v3"
+generated: "2026-08-22T17:20:00+08:00"
+---
+
+# 车务派单异常态——已派车后取消进异常桶，处置完成转已完结（#6152）
+
+## 背景
+
+现网案例：订单 26-9250（行程中中止，出团 2 天后取消）。派单看板详情显示「暂无逐日逐车方案 / 暂无实际用车费用」，已派好的车辆/司机明细完全看不到；且车辆/司机占用残留需人工释放，行级释放对已取消全程槽行报错「缺少该派单的服务日期」（前端解析服务日 7 种来源在已取消行上全空）。
+
+**业务口径（wx 2026-08-22 拍板）**：
+- 「已取消」分面只装**未派车即取消**的单；
+- 凡**已派车（holding/assigned）后取消**（出行前取消/订单整体取消/行程中终止）一律进**异常桶**，保留车辆/司机占用，等车务人工处置；
+- 异常处置完成后流转到「已完结」终态（对标房务异常桶「标记完成」）。
+
+## 变更接口
+
+### 新增端点
+
+| 接口 | 变更 |
+| --- | --- |
+| `POST /admin/fleet/assignments/resolve-exception`（异常处置完成） | **新端点**。入参 `orderId`（整单级处置）+ `requestId`（幂等）。把该订单全部异常派单行转已完结；前置门禁：车辆/司机占用须先经「一键清除已取消派单的占用」释放，否则 605072 拦回。返回 `{ resolvedCount, assignmentIds[] }`；无异常行幂等返回 0。 |
+
+**错误码**：`605072`（异常派单的车辆/司机占用尚未释放，请先释放资源再处置完成）、`605073`（派单处于异常待处置状态，请先释放资源并完成异常处置——异常行拒绝确认/改派/拒接/软清/提前完结等推进类写操作）。
+
+### 修改端点
+
+| 接口 | 变更 |
+| --- | --- |
+| `GET /admin/fleet/board/summary`（看板汇总） | `statusOptions` 新增第 6 项 `{"value":"exception","label":"异常","description":"已派车后再取消，待人工处置（释放资源后处置完成）","count":N,"urgentCount":0}`；`statusCounts` 新增 `exception` 计数。已取消分面 description 更新为「仅未派车即取消」。 |
+| `GET /admin/fleet/board/orders`（看板列表） | `statuses` 筛选参数新增合法值 `exception`；混合取消订单（部分行已派落异常+部分未派占位落取消）的代表状态= exception（落异常桶）；每条记录 `assignmentSlots[]` 槽位行**新增 `serviceDate`/`startDate`/`endDate` 三字段**（逐日切片行 serviceDate 有值；全程槽行 serviceDate=null 时用 startDate~endDate 展开解析服务日）。 |
+| `GET /admin/fleet/board/orders/{orderId}`（看板详情） | `vehicleSlots[]` 的 `slotStatus` 新增值 `exception`（`slotStatusLabel`=「异常」），身份字段（vehiclePlate/vehicleModel/driverName/driverPhone）保留展示不清空，带 `cancelReason`；详情槽位行同样补 `serviceDate`/`startDate`/`endDate`。 |
+| `GET /admin/fleet/orders/{orderId}/operation-log`（派单操作时间线） | 新增 `opType` 枚举值：`exception_marked`（`opTypeLabel`=「订单异常」，操作人=系统，summary 形如「系统 订单异常：出行前取消，原因：xxx」，detailJson 带 scene/reason/exceptionRowCount）；`exception_resolved`（`opTypeLabel`=「异常处置完成」，summary 带「共 N 行派单转已完结」）。存量已派后取消单读侧合成兜底。 |
+| `DELETE /admin/fleet/assignments/{assignmentId}`（取消派单） | 已派车（holding/assigned）行取消后目标态从 canceled 改为 **exception**（返回值 `assignmentStatus="exception"`）；未派占位行维持 canceled。车辆/司机占用**保留不释放**（原取消即条件释放，现等人工处置）。 |
+| `POST /admin/fleet/assignments/clear-cancelled-occupancy`（一键清除占用） | 圈定集合从已取消扩为已取消+异常；异常行的释放= 异常桶里的「释放资源」动作，行为语义不变。 |
+
+## 行为语义变化（前端需知）
+
+1. **取消已派车的派单不再释放车辆/司机占用**：取消后车/司机仍 busy，须走「一键清除已取消派单的占用」释放后才能「处置完成」转已完结。推荐操作流：取消（自动进异常桶）→ 看板异常 Tab 找到单 → 详情释放占用（整单级或行级）→ 处置完成（resolve-exception）→ 单进已完结。
+2. **「已取消」Tab 单量会减少**：已派车后取消的单从该 Tab 移出进「异常」Tab，属预期口径变化。
+3. **详情已取消/异常行现在能解析服务日**：`serviceDate`/`startDate`/`endDate` 三字段补齐后，行级释放占用不再被前端解析盲区误拦截（#6114 修复）。
+4. **撤销取消（restore-cancel）支持异常行**：误操作可撤销回原状态。
+5. 保险退保、需求重开等取消副作用链路对异常行照常触发（占用保留语义只影响车/司机缓存态）。
+
+## 前端动作
+
+1. 看板新增「异常」Tab/分面（数据已在 statusOptions 返回，value=exception，红色系建议）；
+2. 详情槽位行（异常态）展示身份字段 +「释放占用」「处置完成」操作入口（按 slotStatus/assignmentStatus=exception 自判，与已取消行同模式）；
+3. 行级释放占用改用 serviceDate（null 时 startDate~endDate 展开）解析服务日；
+4. 操作时间线渲染新 opTypeLabel（订单异常/异常处置完成），徽标文案直接用后端 label 勿硬编码。
+
+## 验证证据
+
+- 单测：3854 tests 全绿（含状态机 12 转移/看板分面/Mapper 圈定/resolve-exception 5 例）+ ArchTest 门禁 + spotless。
+- TEST 网关实测（订单 2086697882311680002，验 5784A 测试单）：取消 assigned 派单 → `assignmentStatus="exception"` 且车/司机保持 busy ✓；异常分面 count=1 ✓；resolve-exception 占用未清 605072 拦回 ✓；异常行 soft-clear 605073 拦截 ✓；操作时间线 `exception_marked` 留痕（系统·出行前取消+原因）✓；详情异常槽位身份字段保留 + serviceDate/startDate/endDate 补齐 ✓；清占用后车辆转 idle ✓；**处置完成闭环**：resolve-exception 成功转 4 行已完结（resolvedCount=4）✓、异常分面归 0 ✓、`exception_resolved` 留痕（共 4 行派单转已完结）✓、同 requestId 重放幂等返 0 ✓、终态行写口闸回归正常（605043）✓。
+- 列宽修复：complete_source VARCHAR(16)→32（EXCEPTION_RESOLVE 17 字符落库超长，网关实测发现，PR #6178 已合并随本单部署）。