9.7 KiB
schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base, generated
| schema | ticket | title | consumer | author | change_type | backend_status | gateway_status | frontend_status | frontend_owner | frontend_ref | target_release | verified_at | status_note | updated_at | base | generated |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| hl-changelog/v2 | 6152 | 车务派单异常态——已派车后取消进异常桶，处置完成转已完结 | admin | wx | 新增接口 | deployed | verified | verified | mmg | 36261d83 | 2026-08-23 | 车务派单看板/详情：①已派车后取消的订单不再落「已取消」消失，改进新「异常」桶等人工处置；②详情已取消/异常槽位行补 serviceDate/startDate/endDate 三字段（根治行级释放占用解析服务日失败误拦截）；③操作时间线新增「订单异常」「异常处置完成」系统留痕；④新增处置完成写口 POST /admin/fleet/assignments/resolve-exception。前端需适配异常分面 Tab + 详情异常行操作入口。 | 2026-08-22 | dev-v3 | 2026-08-22T17:20:00+08:00 |
【新增接口·管理后台】车务派单异常态——已派车后取消进异常桶，处置完成转已完结（#6152）
PR: #6177（功能）+ #6178（complete_source 列宽修复） | 服务: hl-fleet-service | 作者: wx | 更新时间: 2026-08-22
背景
现网案例：订单 26-9250（行程中中止，出团 2 天后取消）。派单看板详情显示「暂无逐日逐车方案 / 暂无实际用车费用」，已派好的车辆/司机明细完全看不到；且车辆/司机占用残留需人工释放，行级释放对已取消全程槽行报错「缺少该派单的服务日期」（前端解析服务日 7 种来源在已取消行上全空）。
业务口径（wx 2026-08-22 拍板）：
- 「已取消」分面只装未派车即取消的单；
- 凡已派车（holding/assigned）后取消（出行前取消/订单整体取消/行程中终止）一律进异常桶，保留车辆/司机占用，等车务人工处置；
- 异常处置完成后流转到「已完结」终态（对标房务异常桶「标记完成」）。
变更接口
新增端点
POST /admin/fleet/assignments/resolve-exception（异常处置完成）：把该订单全部异常派单行转已完结。入参 orderId（整单级处置）+ requestId（幂等）；前置门禁：车辆/司机占用须先经「一键清除已取消派单的占用」释放，否则 605072 拦回；无异常行幂等返回 0。
请求：
{
"orderId": "2086697882311680002",
"requestId": "resolve-exception-20260822-001"
}
响应（成功，处置 N 行）：
{
"code": 200,
"message": "成功",
"data": {
"resolvedCount": 4,
"assignmentIds": ["2086811469462011905", "2086811469466206209", "2086811469466206210", "2086811469470400514"]
},
"traceId": null,
"success": true
}
响应（幂等重放/无异常行）：data 为 {"resolvedCount": 0, "assignmentIds": []}，同样 code=200。
响应（占用未清拦回）：
{
"code": 605072,
"message": "异常派单的车辆/司机占用尚未释放，请先释放资源再处置完成",
"data": null,
"traceId": null,
"success": false
}
错误码：605072（占用未释放）、605073（异常态写口锁——异常行拒绝确认/改派/拒接/软清/提前完结等推进类写操作）。
修改端点
GET /admin/fleet/board/summary（看板汇总）
statusOptions 新增第 6 项、statusCounts 新增 exception 计数。响应片段（实测）：
{
"statusCounts": {"unassigned": 52, "holding": 1, "assigned": 20, "completed": 1, "canceled": 12, "exception": 1, "unassignedUrgent": 44, "holdingUrgent": 1},
"statusOptions": [
{"value": "canceled", "label": "已取消", "description": "派车需求已取消（仅未派车即取消，#6152）", "count": 12, "urgentCount": 0},
{"value": "exception", "label": "异常", "description": "已派车后再取消，待人工处置（释放资源后处置完成）", "count": 1, "urgentCount": 0}
]
}
（statusOptions 完整共 6 项：待派车/排车中/已派车/已完结/已取消/异常，上表仅示后两项。）
GET /admin/fleet/board/orders（看板列表）
statuses 筛选参数新增合法值 exception；混合取消订单（部分行已派落异常+部分未派占位落取消）的代表状态= exception（落异常桶）；每条记录 assignmentSlots[] 槽位行新增 serviceDate/startDate/endDate 三字段。槽位行片段（实测）：
{
"assignmentId": "2086811469462011905",
"assignmentStatus": "exception",
"serviceDate": null,
"startDate": "2026-08-27",
"endDate": "2026-08-27",
"vehiclePlate": "蒙A-H7777",
"driverName": "阿木古愣"
}
逐日切片行 serviceDate 有值；全程槽行 serviceDate=null，用 startDate~endDate 展开解析服务日。
GET /admin/fleet/board/orders/{orderId}（看板详情）
vehicleSlots[] 的 slotStatus 新增值 exception（slotStatusLabel=「异常」），身份字段保留展示不清空并带 cancelReason。槽位行片段（实测）：
{
"assignmentSlotId": "345201285773004800",
"slotStatus": "exception",
"slotStatusLabel": "异常",
"cancelReason": "6152异常桶验收-5784测试单",
"assignmentId": "2086811469462011905",
"serviceStartDate": "2026-08-28",
"serviceEndDate": "2026-08-31",
"serviceDays": 4,
"vehiclePlate": "蒙A-G8888",
"vehicleModel": "别克GL8",
"driverName": "满都拉",
"driverPhone": "135****5003",
"canDelete": true
}
（详情槽位用的是 serviceStartDate/serviceEndDate 字段名，列表槽位是 startDate/endDate，勿混用。）
GET /admin/fleet/orders/{orderId}/operation-log（派单操作时间线）
新增 opType 枚举值。新条目片段（实测）：
{
"id": "2091082889029419011",
"time": "2026-08-22 16:39:46",
"opType": "exception_marked",
"opTypeLabel": "订单异常",
"summary": "系统 订单异常：出行前取消，原因：6152异常桶验收-5784测试单",
"operatorName": "系统",
"effectiveDate": null,
"detailJson": "{\"scene\":\"出行前取消\",\"reason\":\"6152异常桶验收-5784测试单\",\"exceptionRowCount\":4}"
}
exception_resolved 条目：opTypeLabel=「异常处置完成」，summary 形如「admin 异常处置完成：共 4 行派单转已完结」，detailJson 为 {"resolvedCount":4}。存量已派后取消单读侧合成兜底（scene 判定：有终止退款标记=行程中终止 > order_cancelled=订单取消 > 出行前取消）。
DELETE /admin/fleet/assignments/{assignmentId}（取消派单）
已派车（holding/assigned）行取消后目标态从 canceled 改为 exception，响应 data.assignmentStatus="exception"、sideEffects.vehicleStatusUpdated/driverStatusUpdated 仍为 "busy"（保留占用）；未派占位行维持 canceled。其余响应结构不变。
POST /admin/fleet/assignments/clear-cancelled-occupancy（一键清除占用）
圈定集合从已取消扩为已取消+异常；异常行的释放= 异常桶里的「释放资源」动作。响应结构不变（vehicleDriverPairs/intentsWritten/assignmentIds[]，实测 vehicleDriverPairs:2, intentsWritten:2）。
行为语义变化（前端需知）
- 取消已派车的派单不再释放车辆/司机占用：取消后车/司机仍 busy，须走「一键清除已取消派单的占用」释放后才能「处置完成」转已完结。推荐操作流：取消（自动进异常桶）→ 看板异常 Tab 找到单 → 详情释放占用（整单级或行级）→ 处置完成（resolve-exception）→ 单进已完结。
- 「已取消」Tab 单量会减少：已派车后取消的单从该 Tab 移出进「异常」Tab，属预期口径变化。
- 详情已取消/异常行现在能解析服务日：
serviceDate/startDate/endDate三字段补齐后，行级释放占用不再被前端解析盲区误拦截（#6114 修复）。 - 撤销取消（restore-cancel）支持异常行：误操作可撤销回原状态。
- 保险退保、需求重开等取消副作用链路对异常行照常触发（占用保留语义只影响车/司机缓存态）。
前端动作
- 看板新增「异常」Tab/分面（数据已在 statusOptions 返回，value=exception，红色系建议）；
- 详情槽位行（异常态）展示身份字段 +「释放占用」「处置完成」操作入口（按 slotStatus/assignmentStatus=exception 自判，与已取消行同模式）；
- 行级释放占用改用 serviceDate（null 时 startDate~endDate 展开）解析服务日；
- 操作时间线渲染新 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 已合并随本单部署）。