---
schema: "hl-changelog/v2"
ticket: "5937"
title: "取消改期残留派车改为按单日精确取消——禁止误删整槽及整单配车"
consumer: "admin"
change_type: "修改接口"
author: "wx(GIT)"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: "mmg"
frontend_ref: ""
target_release: ""
verified_at: "2026-08-12"
status_note: "后端已修复并部署测试服：Step2 cell 新增 assignmentId，新端点 POST /admin/fleet/assignments/{assignmentId}/cancel-residue 仅取消指定窗外逐日残留行，不动同槽其他日期或其他槽位。前端必须把『取消残留派车』从槽位删除/老 cancel 切到新端点，使用 cells[].assignmentId；成功后重拉 candidates。禁止继续调用 DELETE /slots/{slotId} 或 DELETE /assignments/{assignmentId}，二者均是整槽语义。"
updated_at: "2026-08-12"
base: "dev-v3"
---

# 取消改期残留派车改为按单日精确取消（#5937 / PR #5939 + #5941）

> **服务**: hl-fleet-service
> **日期**: 2026-08-12
> **前端负责人**: @mmg
> **严重级别**: P0

## 问题实证（订单 26-3559 / 2086270159575535618）

车务在 Step2 栅格点击 08-24/25 行的「取消残留派车」，只想清理两天旧日期残留，实际触发了槽位删除：

- 18:44:39：旧槽 08-24/25/26 三行全部 canceled；
- 19:03:23：新槽 08-26/27/28 三行又全部 canceled；
- 最终整单两个槽位共 6 行配车被清空（订单主单未取消，仍为 CUSTOMIZING / VEHICLE PROCESSING）。

## 根因

1. `canonicalSnapshot.cells[]` 原来没有逐日 `assignmentId`，前端无法精确定位一行。
2. 前端只能退化调用槽位删除。
3. 老 `DELETE /admin/fleet/assignments/{assignmentId}` 名字看似按 assignmentId，后端实际也是稳定槽位整槽取消（`updateCancelSlotActive`），同样不能用于逐行残留清理。

## 新增响应字段

`POST /admin/fleet/assignments/candidates`：

```text
data.canonicalSnapshot.cells[].assignmentId
```

| 字段 | 类型 | 说明 |
|---|---|---|
| `assignmentId` | string | 当天逐日派车行 ID。仅逐日 USED 行返回；全程行/无行/UNUSED 为 null。前端按此 ID 调逐日残留取消。 |

配合既有字段：`serviceDate`、`rescheduleResidue`、`canDelete`、`deleteBlockReason`、`vehiclePlate`、`driverName`、`protocolPrice`。

全程行（`service_date=NULL`）展开的 cell：

```json
{
  "assignmentId": null,
  "canDelete": false,
  "deleteBlockReason": "全程派车不可按单日取消，请先拆分或改派"
}
```

## 变更接口（前端必须切换）

```http
POST /admin/fleet/assignments/{assignmentId}/cancel-residue
Content-Type: application/json
```

请求：

```json
{
  "requestId": "residue-cancel-{唯一请求ID}",
  "cancelReason": "改期残留逐日取消"
}
```

行为：

- 只允许取消当前需求日期窗外的逐日 `holding/assigned` 残留行；
- Mapper 只按 exact `assignmentId + expectedStatus` CAS 一行；
- 不取消同槽其他日期；
- 不影响其他槽位；
- 不写槽位删除意图，不移除 retained slot；
- 只释放目标日期车辆/司机占用、只退目标日期司机保险；
- 新窗内有效行、全程行、completed 行均拒绝；
- 已 canceled 行重复请求幂等 200，DB 零变化。

## 前端改法（必须全部完成）

1. 「取消残留派车」按钮仅在：
   - `rescheduleResidue === true`
   - `canDelete === true`
   - `assignmentId != null`
   时显示/启用。
2. 点击后调用新接口：
   ```http
   POST /admin/fleet/assignments/{cell.assignmentId}/cancel-residue
   ```
3. 成功后必须重新调用 `POST /admin/fleet/assignments/candidates`，用最新 `canonicalSnapshot` 重建栅格；被取消的目标旧日期行自然消失。
4. **禁止**继续调用：
   - `DELETE /admin/fleet/assignments/slots/{slotId}`（整槽删除）
   - `DELETE /admin/fleet/assignments/{assignmentId}`（老普通取消，实际整槽语义）
5. 不要只在本地数组里做状态修改；以后端重拉结果为唯一权威。

## 验证证据（测试与测试服）

- AssignmentServiceTest：487 / 0 / 0；覆盖 exact-ID、窗内拒绝、全程拒绝、canceled 幂等、completed 拒绝、状态 TOCTOU、资源身份漂移后只锁最新车/司机。
- Controller + Step2：60 / 0 / 0。
- ArchTest：13 / 0 / 0；spotless 绿。
- fleet 全量 3688：本改动相关测试全绿；两项无关环境/flaky 独立复跑 1/1、2/2 均绿。
- 测试服双实例 8087/8187 健康。
- 已 canceled 行实测新端点：HTTP 200、`effectiveDate=2026-08-24`，调用前后本单 8 行 DB 快照完全一致（幂等零副作用）。

## 联系人

- **后端负责人**: @wx
- **前端消费**: @mmg（切换新逐行端点 + 删除成功后重拉 candidates）