---
schema: "hl-changelog/v2"
ticket: "5827"
title: "⚠️ 派车取消「司机确认」环节：提交即派定、行程单短链直接生成；新增 sendItinerarySms 勾选字段；driver-confirmation 端点下线"
consumer: "admin"
change_type: "修改接口"
author: "wx(GIT)"
backend_status: "deployed"
gateway_status: "not_required"
frontend_status: "implemented"
frontend_owner: "mmg"
frontend_ref: ""
target_release: ""
verified_at: "2026-08-12"
status_note: "PR #5873 已合并 dev-v3 并部署测试服（19:22:57 构建，jar 早于进程启动，确认跑新代码）。测试服真实 API 实测通过：driver-confirmation 端点 404 已下线；不传 holdMode 不再 400；派车响应 assignmentStatus=assigned + confirmedAt 有值（提交即派定）；未传 sendItinerarySms 时 itinerarySmsStatus=NOT_SENT 且 outbox 无 ITINERARY_SMS/HOLD_NOTIFICATION（不勾不发、Step3 不发通知）；行程单链接派车后立即可打开（HTTP 200，带真实定稿代际）；看板 progressSteps 三步、holdNotificationStatus=NOT_REQUIRED、状态文案已更新。实测使用无人占用的测试单，验证后已取消还原。前端 2026-08-12 落地：向导 4 步改 3 步（订单详情/排车/确认执行），删 Step3DriverConfirm 与 useDispatchMessage 整套，三写端点顶层加 sendItinerarySms，存量 holding 恢复落第 3 步只读 confirm。fleet/board 35 文件 418 用例全绿。"
updated_at: "2026-08-12"
base: "dev-v3"
---

# ⚠️ 车务派车取消「司机确认」环节 —— 一步到位派定（#5827）

> **服务**: hl-fleet-service
> **性质**: **破坏性变更**（流程步骤减少、端点下线、默认行为变更），前端必须跟进

---

## 一、业务变化（一句话）

**派车提交即派定**：不再有「等司机回复确认 → 车务登记司机已确认 → 车务确认执行」这一段，提交后当场落 `assigned`、当场生成行程单短链，车务**不用再点第二次**。

配套：**Step3 不再自动给司机发「排车待确认」通知**；行程短信改为**只在车务显式勾选时发这一次**。

---

## 二、变更接口清单

| 方法 | 路径 | 变更 |
|---|---|---|
| `POST` | `/admin/fleet/assignments` | 请求新增 `sendItinerarySms`；响应新增三字段；`holdMode` 摘 `@NotNull` 并废弃；提交即派定 |
| `POST` | `/admin/fleet/assignments/batch` | 同上（`sendItinerarySms` 放 body 顶层，批次级统一决策） |
| `POST` | `/admin/fleet/assignments/{assignmentId}/change` | 同上；不勾选不再给司机重发行程短信 |
| `POST` | `/admin/fleet/assignments/{assignmentId}/driver-confirmation` | **端点下线** |
| `POST` | `/admin/fleet/assignments/{assignmentId}/confirm` | 契约文案更新（不再要求「已登记司机确认」）；新流程下非必经步骤 |
| `POST` | `/admin/fleet/assignments/requirements/{requirementId}/confirm` | 同上 |
| `POST` | `/admin/fleet/assignments/{assignmentId}/cancel` | 错误码清单更正：605024 → **605028** |
| `GET` | `/admin/fleet/board/orders/{orderId}` | `holdNotificationStatus` / `currentStep` / `stageCode` / 状态说明文案语义变更 |

## 三、⚠️ 前端必须做的四件事

### 1. 删掉「待司机确认」开关

派车表单底部的「待司机确认 · 先锁定司机并发送通知」开关（`holdMode`）**请删除**。

- 后端已**摘除该字段的 `@NotNull`**，不传不会再 400；
- 字段保留兼容但**服务端一律忽略**（传任何值都按一步派定处理）。

### 2. 删掉「等待司机回复确认」整块 UI

- 司机回复摘要输入框
- 司机确认凭证上传（最多 10 个）
- 「登记司机已确认」按钮

对应端点 **`POST /admin/fleet/assignments/{assignmentId}/driver-confirmation` 已下线**。

### 3. 新增「发送行程短信」勾选，并在派车/改派时传 `sendItinerarySms`

**这是本次最关键的行为变更。** 详见第四节。

### 4. 派车向导由 4 步改为 3 步

「订单详情 → 排车 → 确认执行」。后端 `currentStep` 已由 4 改 3，`stageCode` 不再产出 `driver_confirmed`。

---

## 四、新增字段 `sendItinerarySms`（三个写端点）

### 请求

| 端点 | 位置 | 字段 | 类型 | 必填 | 缺省 |
|---|---|---|---|---|---|
| `POST /admin/fleet/assignments` | body 顶层 | `sendItinerarySms` | Boolean | 否 | **不传 = `false` = 不发** |
| `POST /admin/fleet/assignments/batch` | **body 顶层**（不是 items 里） | `sendItinerarySms` | Boolean | 否 | 不传 = `false` |
| `POST /admin/fleet/assignments/{assignmentId}/change` | body 顶层 | `sendItinerarySms` | Boolean | 否 | 不传 = `false` |

> 批量为**批次级统一决策**：整批用同一个值，避免同一需求同一代际内 `itinerary_sms_decision` 不一致。

### 响应（三个端点新增，与 `ConfirmRespVO` 同口径）

| 字段 | 类型 | 说明 |
|---|---|---|
| `sendItinerarySms` | Boolean | 本次是否选择发送行程短信 |
| `itinerarySmsEventId` | String（雪花，字符串序列化） | 行程短信事件 ID；未发送时为 `null` |
| `itinerarySmsStatus` | String | `PENDING`（已入队待发） / `NOT_SENT`（未勾选，不发） |

### 🔴 行为口径（务必理解）

- **不勾（含不传）→ 一条司机短信都不发**。
- **行程单短链与短信无关**：不发短信也照样生成短链、照样可打开。
- 改派同理：**「只改计费日期 / 只改车费」不勾就不会给司机重发短信**（此前会重发）。
- 改派的幂等载荷哈希**不含**该字段：同一 `requestId` 改了勾选再提交会返回已冻结的旧回执，**换新 `requestId` 即生效**。

### 请求示例

```json
POST /admin/fleet/assignments
Authorization: Bearer <admin token>
Content-Type: application/json

{
  "orderId": 2086270138171994114,
  "vehicleId": 2064998142394183681,
  "driverId": 2065272145633591298,
  "startDate": "2026-08-17",
  "endDate": "2026-08-19",
  "headcount": 10,
  "sendItinerarySms": true,
  "requestId": "f3c1c8e2-0a1a-4f2b-9a77-1b2c3d4e5f60"
}
```

### 成功响应示例（**测试服实测原样**，未传 `sendItinerarySms` / 未传 `holdMode`）

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "id": "2086824442578542594",
    "assignmentGroupId": "2086824442578542594",
    "assignmentSlotId": "345214258881105920",
    "assignmentStatus": "assigned",
    "stageCode": "assigned",
    "stageLabel": "已派车",
    "currentStep": 3,
    "skippedStepCodes": [],
    "protocolPrice": "800.00",
    "vehicleFeeAutoTotal": "2400.00",
    "vehicleFeeAutoComplete": true,
    "vehicleFeeTotal": "2400.00",
    "vehicleFeeSource": "AUTO",
    "vehicleFeeAdjustmentReason": null,
    "dailyVehicleFees": null,
    "holdSentAt": null,
    "confirmedAt": "2026-08-11 19:28:02",
    "sideEffects": {
      "vehicleStatusUpdated": "busy",
      "driverStatusUpdated": "busy",
      "reconPrepRowsCreated": 0,
      "reconPrepMarkedCanceled": null
    },
    "sendItinerarySms": false,
    "itinerarySmsEventId": null,
    "itinerarySmsStatus": "NOT_SENT",
    "dailyDifferences": null
  }
}
```

勾选发短信时，仅这三个字段不同：

```json
"sendItinerarySms": true,
"itinerarySmsEventId": "345528786529423360",
"itinerarySmsStatus": "PENDING"
```

### ⚠️ 行程单链接不在派车响应里

派车响应**不含** `itineraryUrl`。行程单链接在**看板订单详情**里取：

```
GET /admin/fleet/board/orders/{orderId}
→ data.currentAssignment.itineraryUrl
```

**实测**：派车成功后立刻读该字段即有值，且链接**当场可打开**（HTTP 200 返回完整行程数据），token 内 `dispatchPlanGeneration` 为**真实定稿代际**（不是待确认期的 `0` 哨兵）。

**未勾选发短信时链接同样可用** —— 行程单链接与是否发短信无关。

> 补充说明：`fleet_itinerary_short_link` 里的**短码**（`/s/xxxx` 形式）只在**发短信时**才铸造（它只服务于短信长度限制）。不发短信时使用的是上面这个完整 token 链接，功能等价、当场可用。

---

## 五、废弃字段（保留兼容，服务端忽略）

| 字段 | 所在端点 | 现在的行为 |
|---|---|---|
| `holdMode` | create / batch / change | **已摘 `@NotNull`**，传任何值都被忽略，一律按一步派定落库 |
| `messageTemplateId` | create / batch.items / change | 已废弃（不再发「待司机确认」通知，无模板可冻结） |
| `customBody` | create / batch.items / change | 同上 |

---

## 六、下线端点

| 方法 | 路径 | 说明 |
|---|---|---|
| `POST` | `/admin/fleet/assignments/{assignmentId}/driver-confirmation` | 「登记司机已确认」，随司机确认环节一并下线 |

---

## 七、响应语义变更（读侧）

| 位置 | 原来 | 现在 |
|---|---|---|
| 派车/批量/改派响应 `assignmentStatus` | 可能是 `holding` | **恒 `assigned`** |
| 派车/批量/改派响应 `skippedStepCodes` | 可能非空 | **恒空数组**（字段保留兼容） |
| 派车/批量/改派响应 `holdSentAt` | 可能有值 | **恒 `null`** |
| 派车/批量/改派响应 `confirmedAt` | 仅确认后才有 | **恒有值**（提交即派定） |
| 看板 `currentAssignment.holdNotificationStatus` | `assigned`/`completed` 行恒返回 `PENDING` | **恒返回 `NOT_REQUIRED`**（此前会诱导车务点无效重发） |
| 生命周期 `currentStep` | 四阶段 / 4 | **三阶段 / 3** |
| 生命周期 `stageCode` | 可能是 `driver_confirmed` | **不再产出该派生态**（时间轴事件类型 `driver_confirmed` 仍保留，用于存量数据回显） |
| `holding` 状态中文名 | 「待确认」 | **「待确认执行」**（新流程下只有存量数据会停在该态） |
| 看板状态筛选项「已派车」说明 | 「司机已确认，派车已生效」 | **「车务已派定，行程单已生成」** |

---

## 八、错误码变化

### 从契约中移除（不会再抛出，常量保留仅供历史数据字典对照）

| 码 | 原含义 |
|---|---|
| `605024` | 排车模式不合法 |
| `605025` | 请先登记司机已确认接单 |

### 更正（此前文档错标）

`POST /admin/fleet/assignments/{assignmentId}/cancel` 的错误码清单里原写「605024 取消生效日无效」是**错标**（605024 的真实含义是排车模式不合法），已更正为：

| 码 | 含义 |
|---|---|
| `605028` | 生效日期不在派单服务日期范围内 |

---

## 九、不变的部分（免得误删）

- **行程单短链**照常生成，且带真实定稿代际；短链身份与「是否发短信」无关。
- **时间轴事件类型 `driver_confirmed`** 保留（存量数据回显用）。
- **取消 / 撤销取消 / 改派 / 逐日派车**的既有入参与语义不变。
- 保险投保时序、槽位锁互斥、占用释放四条链路不变。

---

## 十、验证证据

### 测试服实测（2026-08-11 19:22 部署，19:28 实测）

部署核实：服务器仓库含合并提交 `1c46e6abf`；fleet jar 构建于 19:22:57，两个实例进程分别启动于 19:23:08 / 19:23:25（**jar 早于进程，确认跑的是新代码**）；8087 / 8187 健康检查均 200。

| 验证项 | 方法 | 结果 |
|---|---|---|
| `driver-confirmation` 端点已下线 | `POST .../driver-confirmation` | **HTTP 404「接口不存在」** ✅ |
| 不传 `holdMode` 不再 400 | 派车请求省略该字段 | **code 200** ✅ |
| **提交即派定** | 派车响应 | `assignmentStatus: "assigned"` + `confirmedAt: "2026-08-11 19:28:02"`，**无需第二次调用** ✅ |
| 向导 3 步 | 派车响应 + 看板 | `currentStep: 3`；看板 `progressSteps = [ORDER_DETAIL, DISPATCH, CONFIRM_EXECUTE]` ✅ |
| `skippedStepCodes` 恒空 / `holdSentAt` 恒 null | 派车响应 | `[]` / `null` ✅ |
| **不勾不发** | 未传 `sendItinerarySms` | `sendItinerarySms: false`、`itinerarySmsStatus: "NOT_SENT"`、`itinerarySmsEventId: null` ✅ |
| **Step3 不发任何通知** | 查 outbox 全部事件 | 只有 `OCCUPANCY_RECOMPUTE` + `ASSIGNED`（均 SUCCESS），**无 `ITINERARY_SMS`、无 `HOLD_NOTIFICATION`** ✅ |
| **行程单链接直接可用** | 看板 `itineraryUrl` → 直接 GET | **HTTP 200 返回完整行程**，token 内 `dispatchPlanGeneration` 为真实定稿代际 ✅ |
| `holdNotificationStatus` 修复 | 看板 `currentAssignment` | 已派定行返回 **`NOT_REQUIRED`**（此前恒 `PENDING`）✅ |
| 状态说明文案 | 看板 `statusOptions` | `holding` →「车务已排车，待车务确认执行」；`assigned` →「车务已派定，行程单已生成」✅ |
| 占用副作用 | 派车响应 `sideEffects` | 车与司机均置 `busy` ✅ |

> 实测用的是一张**无人使用的测试单**（非现场在用订单），验证完毕已通过业务接口取消还原，占用已释放、无脏数据残留。

### 后端质量门禁（rebase 到最新 dev-v3 后）

| 项 | 结果 |
|---|---|
| `mvn -pl hl-fleet-service clean test-compile` | BUILD SUCCESS |
| `mvn -pl hl-fleet-service test -Dtest=*ArchTest` | Tests run **13**，Failures 0 |
| `mvn -pl hl-fleet-service spotless:check` | BUILD SUCCESS |
| `mvn -pl hl-fleet-service test`（全量） | Tests run **3605**，Failures **0**，Errors **0**，Skipped 5（Docker 门控自跳过的容器类 IT） |

---

## 十一、关联

- 工单 #5827
- 换版槽位人工制：#5810
- 换版后看板缺口：#5824
- 换版即作废定稿：#5851